# Gravity

*The gravity model applies a gravitational body force to the fluid momentum and energy equations, enabling simulation of buoyancy-driven flows. Gravity is applied globally to all fluid zones in the simulation and is disabled by default.*

---

## Available Parameters

| *Parameter* | *Description* |
|-------------|---------------|
| **Gravity** (toggle) | Enable or disable the gravitational body force |
| **Direction** | Unit vector defining the direction of gravitational acceleration [X, Y, Z] |
| **Magnitude** | Magnitude of the gravitational acceleration |

---

## Detailed Descriptions

### Gravity (toggle)

*Enables or disables the gravitational body force. When enabled, gravity is applied globally to all fluid zones by adding a body force to the momentum equations and a work term to the energy equation: $\mathbf{f}_{\text{mom}} = \rho \, \mathbf{g}, \qquad f_{\text{energy}} = \rho \, (\mathbf{g} \cdot \mathbf{u})$*

- **Default:** Disabled (off)

### Direction

*The unit vector specifying the direction of the gravitational acceleration. Defines the orientation of the gravity vector in the simulation coordinate system.*

- **Default:** `X: 0, Y: 0, Z: -1` (pointing in the negative Z-direction)
- **Example:** `(0, 0, -1)` for vertical-down in a Z-up coordinate system, `(0, -1, 0)` for a Y-up coordinate system
>**Notes:**
>- The direction vector will be normalised automatically; you do not need to supply a unit vector.
>- Only available when the Gravity toggle is enabled.

### Magnitude

*The magnitude of the gravitational acceleration.*

- **Default:** `9.81 m/s²` (Earth surface gravity)
- **Example:** `9.81 m/s²`, `1.62 m/s²` (lunar gravity)
>**Notes:**
>- Must be a positive value.
>- Only available when the Gravity toggle is enabled.

---

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

- When using a Z-up coordinate system, the default direction `(0, 0, -1)` corresponds to Earth's downward gravity and requires no adjustment.
- For conjugate heat transfer (CHT) simulations with buoyancy-driven convection, enabling gravity is essential for physically accurate results.

</details>

---

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

```{seealso}
Python API:
- {py:class}`~flow360.Gravity`
- {py:class}`~flow360.Fluid`
```

```python
import flow360 as fl

# Gravity is configured via the `gravity` field on the Fluid model.
# Using fl.Gravity() applies Earth's defaults: direction=(0, 0, -1), magnitude=9.81 m/s^2.
fluid = fl.Fluid(
    gravity=fl.Gravity(),
)

# Custom direction and magnitude (e.g. a Y-up coordinate system, lunar gravity)
fluid_custom = fl.Fluid(
    gravity=fl.Gravity(
        direction=(0, -1, 0),
        magnitude=1.62 * fl.u.m / fl.u.s**2,
    ),
)
```

</details>