# Structured Box Refinement

*Structured box refinement creates a semi-structured mesh inside a box region, with the spacing along each of the box axes set independently. Use it when a region needs different resolution in different directions, such as a thin shear layer or a wake that is long in the streamwise direction but narrow across it.*

---

## Available Options

| *Option* | *Description*                  |
|------------|----------------------------------|
| **Name** | Identifier for the refinement |
| **Spacing axis 1** | Mesh spacing along the box's first principal axis |
| **Spacing axis 2** | Mesh spacing along the box's second principal axis |
| **Spacing normal** | Mesh spacing along the box's third (computed) axis |
| **Assigned volumes** | Target box regions for refinement |

---

## Detailed Descriptions

### Name

*Identifier for the structured box refinement.*

- **Required**

### Spacing axis 1

*Defines the mesh spacing along the first principal axis of the assigned box.*

- **Required**
- **Units:** Length
- **Example:** `0.04 m`
>**Note:** The first axis is the one that aligns with the box's size X, as set on the [Box](../../../04.entities-browser/04.volumes/00.box.md) entity.

### Spacing axis 2

*Defines the mesh spacing along the second principal axis of the assigned box.*

- **Required**
- **Units:** Length
- **Example:** `0.06 m`
>**Note:** The second axis aligns with the box's size Y.

### Spacing normal

*Defines the mesh spacing along the box's third axis, the one computed automatically to complete the right-handed coordinate system.*

- **Required**
- **Units:** Length
- **Example:** `0.05 m`
>**Note:** The third axis aligns with the box's size Z.

### Assigned volumes

*Specifies the box regions where structured box refinement will be applied.*

- **Required**
>**Notes:**
>  - Only **box** entities can be assigned. Cylinders, spheres and custom volumes are not accepted.
>  - Assign the entity by selecting from the list using the + button or select graphically in the viewer region.
>  - The refinement cannot enclose or intersect another refinement object.

---

## Mesher support

Structured box refinement requires the **beta mesher**. With the **legacy** mesher the setup is rejected at validation with the message *"`StructuredBoxRefinement` is only supported with the beta mesher."*

The refinement is offered in the **Refinements** menu regardless of which mesher is selected, so the restriction surfaces when the setup is validated rather than when the refinement is added. If you see that message, switch the project to the beta mesher or remove the refinement.

Structured box refinement is always **volume-only**: it never changes the surface mesh, whichever surface mesher is in use.

```{seealso}
User guide: {doc}`Volumetric refinements </user_guide/Meshing/VolumeMesher>`
```

---

<details>
<summary><h3 style="display:inline-block"> 🐍 Python Example Usage</h3></summary>

```{seealso}
Python API:
- {py:class}`~flow360.StructuredBoxRefinement`
- {py:class}`~flow360.Box`
```

```python
import flow360 as fl

# A wake box resolved finely across the wake and coarsely along it
wake_box = fl.Box.from_principal_axes(
    name="wakeBox",
    center=(2, 0, 0) * fl.u.m,
    size=(4, 1, 1) * fl.u.m,
    axes=((1, 0, 0), (0, 1, 0)),
)

wake_ref = fl.StructuredBoxRefinement(
    name="wake_region",
    entities=[wake_box],
    spacing_axis1=0.04 * fl.u.m,   # along the wake
    spacing_axis2=0.01 * fl.u.m,   # across the wake
    spacing_normal=0.01 * fl.u.m,
)
```
</details>