Merge branch 'master' into piotr/integrate_with_docs

Author: piotrkluba

docs/01.introduction/05.project-tree.md

@@ -114,6 +114,13 @@ The project tree supports multiple branches at each level:
 - Simulation continues from the last state of the parent case
 - Multiple forks can branch from the same parent case
 
+### **Interpolation**
+
+- Interpolation transfers solution from a case onto a new mesh
+- New mesh can exist either within the same project, or in a different one
+- Useful when running a refined mesh or slightly altered geometry
+- Arrow on the volume mesh asset icon in project tree indicates that the volume mesh exists in a different project
+
 ### **Component Actions**
 
 When clicking on a component in the project tree, a menu of available actions appears. Below are the available actions:
@@ -126,7 +133,7 @@ When clicking on a component in the project tree, a menu of available actions ap
 |------------|-----------------|
 | Open in workbench | Opens the component workbench |
 | New run | Creates a new simulation run draft using settings from this component |
-| Interpolation | Transfers solution data between different mesh resolutions |
+| Interpolation | Transfers solution data between different meshes |
 | Rename | Changes the display name of the component |
 | Details | Shows components details such as ID, name, cost, parent asset ID, etc. |
 | Expand all sub-items | Shows all sub-components derived from this component |

docs/01.introduction/Figures/interpolate.svg

@@ -17,6 +17,7 @@ The Meshing Defaults define the baseline mesh generation parameters that control
 | **Boundary layer first layer thickness** | First layer thickness for volumetric anisotropic layers |
 | **Refinement factor** | Global scaling factor for mesh refinement |
 | **Gap treatment strength** | Controls mesh behavior in narrow gaps |
+| **Preserve thin geometry** | Specifies whether thin geometry features should be resolved accurately during surface meshing|
 
 ---
 
@@ -89,14 +90,16 @@ The Meshing Defaults define the baseline mesh generation parameters that control
 
 #### **Refinement factor**
 
-*Global scaling factor that affects the overall mesh refinement level.*
+*Global scaling factor that affects the overall **volume** mesh refinement level.*
 
 - **Default:** `1.0`
 - **Units:** Dimensionless
 >**Notes:**
+>  - Doesn't work with beta mesher
+>  - Adjusts all spacings in refinement regions and first layer thickness to generate r-times finer mesh, where r is the refinement factor value. For example, if `refinement factor=2`, all spacings will be divided by \[ 2^{1/3} \], so the resulting mesh will have approximately 2 times more nodes
 >  - Values > `1.0` increase global mesh refinement
 >  - Values < `1.0` decrease global mesh refinement
->  - Affects both surface and volume mesh density
+>  - Affects volume mesh density only
 >  - Useful for quick mesh resolution studies
 
 #### **Gap treatment strength**
@@ -111,6 +114,16 @@ The Meshing Defaults define the baseline mesh generation parameters that control
 >  - Critical for mesh quality in tight geometric spaces
 >  - Helps prevent highly skewed elements in narrow regions
 
+#### **Preserve thin geometry**
+
+*Flag to specify whether thin geometry features should be resolved accurately during the surface meshing process.*
+
+- **Default:** `False`
+>**Notes:**
+>  - This setting is only effective when using Geometry AI.
+>  - Resolves features with thickness roughly equal to `geometry_accuracy`.
+>  - Can be overridden using **GeometryRefinement**.
+
 ---
 
 <details>
@@ -191,6 +204,7 @@ meshing_defaults = fl.MeshingDefaults(
     curvature_resolution_angle=12 * u.deg,
     boundary_layer_growth_rate=1.2,
     boundary_layer_first_layer_thickness=0.01 * u.mm,
+    preserve_thin_geometry=True
 ) 
 ```
-</details>
+</details>

docs/01.introduction/Figures/project_tree.png

@@ -0,0 +1,84 @@
+# Geometry Refinement
+
+*Geometry refinement allows for controlling the resolution of the surface mesh by defining the smallest geometric features to be captured. It ensures that the mesh accurately represents the geometry down to a specified length scale. Geometry AI needs to be enabled to use this feature.*
+
+---
+
+## **Available Options**
+
+| *Option* | *Description* |
+|------------|-----------------|
+| **Geometry accuracy** | The smallest length scale to be accurately resolved by the surface mesher. |
+| **Preserve thin geometry** | Specifies whether to accurately resolve thin geometry features. |
+| **Assigned surfaces** | The surfaces to which the refinement is applied. |
+
+---
+
+## **Detailed Descriptions**
+
+### **Geometry accuracy**
+
+*Specifies the minimum length scale that the surface meshing process will accurately resolve.*
+
+- **Required**
+- **Example:** `0.01 m`
+
+> **Notes:**
+> - A smaller `Geometry accuracy` value will result in a finer mesh and consequently a larger cell count and longer computation time.
+> - Start with a larger value and decrease it iteratively to find the optimal balance between accuracy and computational cost.
+
+### **Preserve thin geometry**
+
+*Specifies whether thin geometry features should be accurately resolved during surface meshing.*
+
+- **Default:** `false`
+> **Notes:**
+> - Resolves features with thickness roughly equal to `geometry_accuracy`.
+
+### **Assigned surfaces**
+
+*The list of surfaces where the geometry refinement will be applied.*
+
+- **Required**
+> **Notes:**
+> - Must reference valid surface entities in the geometry.
+> - Surfaces can be assigned from the list using the `+` button or by graphical selection in the viewer.
+
+---
+
+<details>
+<summary><h3 style="display:inline-block"> 💡 Tips</h3></summary>
+
+- Use this refinement to ensure small but important geometric features (e.g., sharp corners, small fillets) are not lost during meshing.
+
+</details>
+
+---
+
+<details>
+<summary><h3 style="display:inline-block"> ❓ Frequently Asked Questions</h3></summary>
+
+- **What is a typical value for Geometry accuracy?**  
+  > The value is highly dependent on the specific geometry and the scale of the features you want to capture. It should be smaller than the smallest important feature size. For example, for a vehicle simulation, you might want to resolve features on the scale of millimeters.
+
+- **What is the difference between Geometry Refinement and Surface Refinement?**  
+  > `Surface Refinement` controls the maximum edge length of surface cells directly. `Geometry Refinement` provides a more automated way of refining the mesh based on geometric curvature and feature size, driven by geometry AI.
+
+</details>
+
+---
+
+<details>
+<summary><h3 style="display:inline-block"> 🐍 Python Example Usage</h3></summary>
+
+```python
+import flow360 as fl
+
+geometry_refinement = fl.GeometryRefinement(
+    name="fine_features_refinement",
+    faces=[geometry["wing_surface"], geometry["fuselage_surface"]],
+    geometry_accuracy=0.001 * fl.u.m,
+    preserve_thin_geometry=True
+)
+```
+</details>

docs/02.simulation-setup/02.mesh/01.mesh.md

@@ -12,6 +12,7 @@
 |[**Passive Spacing**](./04.passive-spacing.md) | Controls mesh behavior without direct refinement |
 |[**Uniform Refinement**](./05.uniform-refinement.md) | Creates uniform mesh spacing in a region |
 |[**Axisymmetric Refinement**](./06.axisymmetric-refinement.md) | Creates structured-like mesh with cylindrical bias |
+|[**Geometry Refinement**](./07.geometry-refinement.md) | Controls mesh resolution based on geometric features |
 
 ## **General Guidelines**
 
@@ -21,6 +22,7 @@
    - Use Surface Edge Refinement for leading/trailing edges
    - Apply Surface Refinement for general surface resolution
    - Implement Boundary Layer Refinement for wall regions
+   - Select geometry refinement to accurately capture small features
 
 2. **Off-Body Features**
    - Use Uniform Refinement for wakes and shocks
@@ -87,58 +89,56 @@
 <summary><h3 style="display:inline-block"> 🐍 Python Example Usage</h3></summary>
 
 ```python
-from flow360 import (
-    MeshingParams,
-    SurfaceEdgeRefinement,
-    SurfaceRefinement,
-    BoundaryLayer,
-    PassiveSpacing,
-    UniformRefinement,
-    AxisymmetricRefinement,
-    u
-)
+import flow360 as fl
 
 # Example of combining multiple refinements
 meshing=MeshingParams(
     refinements=[
         # Surface edge refinement for leading edge
-        SurfaceEdgeRefinement(
+        fl.SurfaceEdgeRefinement(
             name="leading_edge",
             edges=[leading_edge],
-            method=HeightBasedRefinement(value=0.001 * u.m)
+            method=fl.HeightBasedRefinement(value=0.001 * fl.u.m)
         ),
         # Surface refinement for general resolution
-        SurfaceRefinement(
+        fl.SurfaceRefinement(
             name="wing_surface",
             faces=[wing_surface],
-            max_edge_length=0.05 * u.m
+            max_edge_length=0.05 * fl.u.m
         ),
         # Boundary layer refinement for wall regions
-        BoundaryLayer(
+        fl.BoundaryLayer(
             name="wing_bl",
             faces=[wing_surface],
-            first_layer_thickness=1e-5 * u.m,
+            first_layer_thickness=1e-5 * fl.u.m,
             growth_rate=1.2
         ),
         # Passive spacing refinement for interface region
-        PassiveSpacing(
+        fl.PassiveSpacing(
             name="interface_region",
             type="projected",
             faces=[interface_surface]
         ),
         # Wake region refinement
-        UniformRefinement(
+        fl.UniformRefinement(
             name="wake_region",
             entities=[wake_box],
-            spacing=0.1 * u.m
+            spacing=0.1 * fl.u.m
         ),
         # Axisymmetric refinement for propeller region
-        AxisymmetricRefinement(
+        fl.AxisymmetricRefinement(
             name="propeller_region",
             entities=[prop_cylinder],
-            spacing_axial=0.02 * u.m,
-            spacing_radial=0.01 * u.m,
-            spacing_circumferential=0.015 * u.m
+            spacing_axial=0.02 * fl.u.m,
+            spacing_radial=0.01 * fl.u.m,
+            spacing_circumferential=0.015 * fl.u.m
+        ),
+        # Geometry refinement for fine features
+        fl.GeometryRefinement(
+            name="fine_features_refinement",
+            faces=[wing_surface, fuselage_surface],
+            geometry_accuracy=0.001 * fl.u.m,
+            preserve_thin_geometry=True
         )
     ]
 )

docs/02.simulation-setup/02.mesh/03.refinements/07.geometry-refinement.md

@@ -23,7 +23,7 @@ A section for defining the meshing settings.
 
 ### **[Refinements](./03.refinements/README.md)**
 
-*Comprehensive local mesh control system for critical regions. Provides six refinement types.*
+*Comprehensive local mesh control system for critical regions. Provides seven refinement types.*
 
 **Subsections:**
 - **[Surface Edge Refinement](./03.refinements/01.surface-edge-refinement.md)** - Controls mesh resolution near edges
@@ -32,11 +32,13 @@ A section for defining the meshing settings.
 - **[Passive Spacing](./03.refinements/04.passive-spacing.md)** - Controls mesh behavior without direct refinement
 - **[Uniform Refinement](./03.refinements/05.uniform-refinement.md)** - Creates uniform mesh spacing in a region
 - **[Axisymmetric Refinement](./03.refinements/06.axisymmetric-refinement.md)** - Creates structured-like mesh with cylindrical bias
+- **[Geometry Refinement](./03.refinements/07.geometry-refinement.md)** - Controls mesh resolution based on geometric features
 
 ```{toctree}
 :hidden:
 :maxdepth: 3
 ./01.mesh.md
 ./02.rotation-regions.md
 ./03.refinements/README.md
-```
+```
+

docs/02.simulation-setup/02.mesh/03.refinements/README.md

@@ -0,0 +1,97 @@
+# Stopping criterion
+
+*Stopping criterion provides a mechanism to automatically terminate a simulation when a monitored field reaches a certain value. This is achieved by tracking the deviation of the field over a moving window of iterations. When the deviation falls below a defined tolerance, the simulation is considered converged and stops.*
+
+---
+
+## **Available Parameters**
+
+| *Parameter*    | *Description*                                                                                              |
+|----------------|------------------------------------------------------------------------------------------------------------|
+| **Output type**    | The type of output to be monitored (e.g., Probe, Surface Integral).                                        |
+| **(Output name)**  | The name of a specific, pre-defined output instance. This field appears after selecting an **Output type**. |
+| **Output field**   | The specific scalar field within the selected output to monitor for convergence.                           |
+| **Tolerance**      | The threshold for the moving deviation of the monitored field.                                             |
+| **Change window**  | The number of iterations over which to calculate the moving deviation of the monitored field.              |
+
+---
+
+## **Detailed Descriptions**
+
+### **Output type**
+
+*Specifies the category of output that contains the field to be monitored.*
+
+- **Default:** None
+- **Options:**
+  - `Probe`
+  - `Surface probe`
+> **Notes:**
+> - The chosen output type must be configured in output section of the simulation setup.
+> - This determines which specific outputs are available in the next dropdown.
+
+### **Output name**
+
+*Selects a specific, named output instance of the chosen "Output type" to monitor.*
+
+- **Default:** None
+> **Notes:**
+> - You must define an output (e.g., a `ProbeOutput` or `SurfaceIntegralOutput`) before it can be selected here.
+> - The list of available names is filtered based on the selected **Output type**.
+
+### **Output field**
+
+*Field within the selected output whose convergence will be tracked.*
+
+- **Default:** None
+- **Example:** `Cl`, `Pressure`, `MyVelocityVariable`
+> **Note:**
+> - The selected field must be one of the `output_fields` defined in the selected output instance.
+
+### **Tolerance**
+
+*Convergence threshold. The simulation stops when the moving deviation of the **Output field** is less than this value.*
+
+- **Default:** `0.01`
+- **Example:** `1e-4`
+> **Notes:**
+> - This value is non-dimensional if the monitored field is a string-defined default field (e.g., 'Cl').
+> - If using a `UserVariable` for the output field, the dimensions of the tolerance must match the dimensions of the field.
+
+### **Change window**
+
+*The number of data points used for the moving window to calculate the deviation of the monitored field.*
+
+- **Default:** `10`
+- **Example:** `20`
+> **Notes:**
+> - The value must be an integer greater than or equal to 2.
+> - A larger window provides a more stable measure of convergence but may react slower to changes.
+
+---
+
+<details>
+<summary><h3 style="display:inline-block"> 🐍 Python Example Usage</h3></summary>
+
+```python
+import flow360 as fl
+
+fl.Fluid(
+    stopping_criterion=[
+        stop_on_lift_convergence = fl.Criterion(
+            name="StopOnLift",
+            monitor_output=fl.SurfaceIntegralOutput(
+                name="wing_forces",
+                entities=[surface_mesh['wing']],
+                output_fields=['Cf', 'Cl', 'Cd']
+            ),
+            monitor_field='Cl',
+            tolerance=1e-5,
+            criterion_change_window=50
+        )
+    ],
+    ...
+)
+```
+
+</details>