# API Reference

CFDPre's public interface is the single function `yhgrcalc`, importable directly from the
package:

```python
from cfdpre import yhgrcalc
```

---

## `yhgrcalc`

```python
yhgrcalc(
    fluid,
    temperature_c,
    pressure_bar,
    massflow_kgpersec,
    hydraulicdia_mm,
    target_yplus,
    num_layers,
    flow_type="internal",
    flow_velocity_mpersec=None,
    bl_thickness_mm=None,
    bl_thickness_fraction=None,
    roughness_mm=0.0,
)
```

Calculate boundary-layer mesh sizing — first layer height, growth ratio, and final layer
thickness — for a given fluid, flow condition, and target $y^+$. See
[Theory & Methodology](../theory.md) for the underlying physics.

### Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `fluid` | `str` | — | CoolProp fluid name, e.g. `"Air"`, `"Water"`. |
| `temperature_c` | `float` | — | Static temperature in degrees Celsius. |
| `pressure_bar` | `float` | — | Static pressure in bar (absolute). |
| `massflow_kgpersec` | `float` | — | Mass flow rate in kg/s (used for internal flow). |
| `hydraulicdia_mm` | `float` | — | Hydraulic diameter (internal) **or** characteristic length (external), in mm. |
| `target_yplus` | `float` | — | Target $y^+$ at the first cell centroid. |
| `num_layers` | `int` | — | Number of inflation / prism layers, $N$. |
| `flow_type` | `str` | `"internal"` | `"internal"` (pipe/duct) or `"external"` (flat-plate/aero). |
| `flow_velocity_mpersec` | `float`, optional | `None` | Free-stream velocity in m/s. **Required** for `flow_type="external"`; ignored for internal flow. |
| `bl_thickness_mm` | `float`, optional | `None` | Explicit total prism-stack thickness in mm. Overrides the default $\delta_{99}$. |
| `bl_thickness_fraction` | `float`, optional | `None` | Internal only. Prism-stack thickness as a fraction of pipe radius, in $(0, 1]$. Ignored if `bl_thickness_mm` is given. |
| `roughness_mm` | `float` | `0.0` | Absolute wall roughness in mm for the Haaland turbulent internal correlation. `0.0` = hydraulically smooth. |

### Returns

A `dict` with the following keys. Inputs are echoed back; computed quantities are grouped at
the end.

| Key | Description |
|---|---|
| `fluid` | Echoed input. |
| `temperature [C]` | Echoed input. |
| `pressure [bar]` | Echoed input. |
| `massflow [kg/sec]` | Echoed input. |
| `hydraulicdia [mm]` | Echoed input. |
| `target yplus` | Echoed input. |
| `number of layers` | Echoed input. |
| `flow type` | `"internal"` or `"external"`. |
| `roughness [mm]` | Echoed input. |
| `dynvisc [N-sec/m^2]` | Dynamic viscosity $\mu$. |
| `thermal conductivity [W/m-k]` | $k$. |
| `specific heat [cp] [J/kg-k]` | $c_p$. |
| `density [kg/m^3]` | $\rho$. |
| `kinematic viscosity [m^2/s]` | $\nu = \mu/\rho$. |
| `flow velocity [m/sec]` | Bulk (internal) or free-stream (external) velocity $V$. |
| `reynolds number` | $Re$. |
| `prandtl number` | $Pr = c_p\mu/k$. |
| `skin friction coefficient [cf]` | Fanning skin-friction coefficient $c_f$. |
| `wall shear stress [tau_wall]` | $\tau_w$ in Pa. |
| `boundary layer thickness [delta99] [m]` | Total thickness $\delta_{99}$ spanned by the stack. |
| `height of cell centroid from wall [yp] [m]` | First-cell centroid height $y_p$. |
| `first layer height [yh] [m]` | **First layer height $y_H = 2y_p$.** |
| `Growth Ratio` | **Geometric growth ratio $r$** (`nan` if unresolvable). |
| `Final Layer Thickness [m]` | **Outermost layer thickness $y_H r^{N-1}$** (`nan` if unresolvable). |

### Raises

- **`ValueError`** — if `flow_type` is not `"internal"`/`"external"`, if
  `flow_type="external"` is used without `flow_velocity_mpersec`, or if
  `bl_thickness_fraction` is outside $(0, 1]$.

### Warns

- **`UserWarning`** — if the resulting growth ratio exceeds ~1.3, or if the boundary-layer
  thickness is not larger than the first layer height (inputs inconsistent; growth ratio and
  final layer thickness are returned as `nan`).

### Examples

Internal pipe flow (default):

```python
from cfdpre import yhgrcalc
yhgrcalc("Air", 50, 10, 2.5, 125, 1, 8)
```

Internal flow, prism stack limited to 30 % of the radius:

```python
yhgrcalc("Air", 50, 10, 2.5, 125, 1, 8, bl_thickness_fraction=0.3)
```

External flat-plate flow (velocity required):

```python
yhgrcalc("Air", 25, 1.01325, 2.5, 1000, 1, 15,
         flow_type="external", flow_velocity_mpersec=30)
```

---

:::{admonition} Auto-generated API docs
:class: note
This reference is currently hand-maintained. Once the updated library is published, it can
be switched to pull directly from the source docstrings via Sphinx `autodoc` —
the configuration (`napoleon`, `autodoc`) is already wired up in `conf.py`. The equivalent
directive would be:

```
::: {eval-rst}
.. autofunction:: cfdpre.yhgrcalc
:::
```
:::