# Periodic Boundary Condition

*The Periodic boundary condition links two separate boundaries so that flow exiting one boundary enters the other, enabling simulation of infinitely repeating geometry with a reduced computational domain.*

---

## Available Options

| *Option* | *Description* | *Applicable* |
|------------|----------------------------------|----------|
| **Periodicity Type** | Type of periodicity (translational or rotational) | always |
| **Axis of rotation** | Rotation axis for rotational periodicity | **Periodicity type** is `Rotational` |
| **Assigned surfaces** | Matching pairs of boundaries to be treated as periodic | always |

---

## Detailed Descriptions

### Periodicity Type

*Defines the geometric relation between periodic boundaries.*

- **Options:**
  - `Translational`
  - `Rotational`
- **Default:** `Translational`
>**Note:** Translational periodicity is typically used for linear arrays, while rotational periodicity is used for circular arrangements.

### Axis of rotation

*The axis about which rotational periodicity is applied.*

- **Required when `Rotational` is selected.**
- **Example:** Vector `(0, 0, 1)` for rotation around the z-axis.
>**Note:** The rotation angle is determined automatically from the mesh geometry.

### Assigned surfaces

*Matching pairs of boundaries that will be treated as periodic interfaces.*

- **Required.**
- **Accepted types:** Pairs of Surface objects
- **Example:** `front_plane AND back_plane`
>**Note:** The mesh must be conformal at periodic interfaces, meaning nodes on paired surfaces must match exactly after applying the periodic transformation.

---

<details>
<summary><h3 style="display:inline-block"> 💡 Tips</h3></summary>

**Mesh Preparation for Periodic Boundaries**

- **Conformal mesh requirement:**
  - The mesh must be conformal at periodic interfaces
  - Nodes on paired surfaces must match exactly after applying the periodic transformation (translation or rotation)
  - Ensure your mesh generator creates matching node distributions on both periodic surfaces

- **For Translational Periodicity:**
  - Ensure identical node positions on both surfaces, offset only by the translation vector

- **For Rotational Periodicity:**
  - Ensure nodes on both surfaces match exactly when one surface is rotated to align with the other

**Common Applications**

- **Translational Periodicity:**
  - Airfoil or blade cascades
  - Heat exchanger channels
  - Infinite arrays of elements
  - Channel flow with repeating features

- **Rotational Periodicity:**
  - Single blade passage in turbomachinery
  - Sectional analysis of axisymmetric components
  - Propeller/rotor blade analysis using one blade
  - Components with cyclic symmetry

### Performance Considerations

- Periodic boundaries typically reduce computational cost significantly
- For rotational cases, ensure sufficient sector size to capture relevant flow features
- Verify that periodicity is a valid assumption for your flow physics

</details>

---

<details>
<summary><h3 style="display:inline-block"> ❓ Frequently Asked Questions</h3></summary>

- **How do I determine if periodicity is appropriate for my simulation?**  
  > Periodicity is appropriate when:
  > - Your geometry repeats in a regular pattern
  > - Flow conditions are expected to be identical across the repeating units
  > - You're interested in the fully developed flow rather than entrance/exit effects
  > - The problem has no major asymmetries that would invalidate the periodic assumption

- **What mesh requirements must be met for periodic boundaries?**  
  > Periodic boundaries require conformal meshes:
  > - Nodes on paired surfaces must match exactly after applying the periodic transformation
  > - The node count must be identical on both periodic surfaces
  > - Ensure your mesh generator creates matching node distributions when generating periodic boundaries

- **Can I use periodicity with other boundary conditions?**  
  > Yes, periodic boundaries are often combined with:
  > - Wall conditions for solid surfaces
  > - Inflow/outflow for the flow direction perpendicular to the periodic directions
  > - Symmetry planes for additional domain reduction

- **How many repeating units should I include in my periodic simulation?**  
  > For most cases, a single repeating unit is sufficient. However, include multiple units when:
  > - Vortex shedding or instabilities with wavelengths larger than one unit are expected
  > - Flow features may develop with periodicity different from the geometric periodicity
  > - Investigating possible asymmetric solutions in nominally periodic configurations

- **Can I use periodicity for time-dependent simulations?**  
  > Yes, periodicity works for both steady and unsteady simulations, but:
  > - Ensure that time-dependent phenomena respect the periodic assumption
  > - For some unsteady flows (e.g., vortex shedding), include enough repeating units to capture the correct wavelength
  > - Consider phase-lag periodicity for turbomachinery with relative motion between components

- **What's the difference between periodicity and symmetry?**  
  > - Periodicity connects two separate boundaries, simulating infinite repetition
  > - Symmetry reflects flow across a single plane, imposing the condition that flow doesn't cross that plane
  > - Use periodicity for repeating patterns, symmetry for mirror-image configurations

</details>

---

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

```python
# Example of translational periodicity
translational_periodic = fl.Periodic(
    name="x_direction_periodicity",
    surface_pairs=[
        (volume_mesh["left_face"], volume_mesh["right_face"])
    ],
    spec=fl.Translational()
)

# Example of rotational periodicity
rotational_periodic = fl.Periodic(
    name="blade_passage_periodicity",
    surface_pairs=[
        (volume_mesh["passage_minus"], volume_mesh["passage_plus"])
    ],
    spec=fl.Rotational(
        axis_of_rotation=(0, 0, 1)  # Rotation around z-axis
    )
)

# Example with multiple periodic pairs
multi_periodic = fl.Periodic(
    name="multi_direction_periodicity",
    surface_pairs=[
        (volume_mesh["left_face"], volume_mesh["right_face"]),
        (volume_mesh["bottom_face"], volume_mesh["top_face"])
    ],
    spec=fl.Translational()
)

# Example of turbomachinery setup with periodicity
def create_turbo_boundaries():
    return [
        fl.Wall(
            name="blade_surface",
            entities=volume_mesh["blade"],
            heat_spec=fl.HeatFlux(0 * fl.u.W / fl.u.m**2)  # Adiabatic wall
        ),
        fl.Inflow(
            name="inlet",
            entities=[volume_mesh["inlet"]],
            total_temperature=300 * fl.u.K,
            spec=fl.TotalPressure(
                value=150000 * fl.u.Pa
            )
        ),
        fl.Outflow(
            name="outlet",
            entities=volume_mesh["outlet"],
            spec=fl.Pressure(
                value=101325 * fl.u.Pa
            )
        ),
        fl.Periodic(
            name="blade_passage",
            surface_pairs=[
                (volume_mesh["periodic_minus"], volume_mesh["periodic_plus"])
            ],
            spec=fl.Rotational(
                axis_of_rotation=(1, 0, 0)  # Rotation around x-axis
            )
        )
    ]
```

</details> 