# Quickstart

CFDPre exposes a single high-level function, `yhgrcalc`, which works for two flow regimes
selected with the `flow_type` argument. This page shows both in code; the
[Theory & Methodology](theory.md) page explains *why* each number comes out the way it does.

## 1. Internal flow (pipe / duct)

This is the default (`flow_type="internal"`). You provide a **mass flow rate** and a
**hydraulic diameter**, and CFDPre derives the bulk velocity and Reynolds number for you.

```python
from cfdpre import yhgrcalc

result = yhgrcalc(
    fluid="Air",
    temperature_c=50,        # degrees Celsius
    pressure_bar=10,         # bar (absolute)
    massflow_kgpersec=2.5,   # kg/s
    hydraulicdia_mm=125,     # mm
    target_yplus=1,          # wall-resolved
    num_layers=8,
)

for key in ("reynolds number", "first layer height [yh] [m]",
            "Growth Ratio", "Final Layer Thickness [m]"):
    print(f"{key:32s}: {result[key]}")
```

:::{admonition} About the growth ratio in this example
:class: note
With `target_yplus=1` and only 8 layers at this high Reynolds number (~1.29 × 10⁶), the
growth ratio comes out around **3.66** — well above the ~1.3 maximum recommended for mesh
quality. CFDPre raises a `UserWarning` to tell you so. In practice you would either use
many more layers (20–40+) or restrict the prism stack to part of the radius (see below).
:::

### Restricting the prism stack thickness

Filling the **entire** pipe radius with prism layers is rarely what you actually mesh —
usually you grow prisms in the near-wall region and let a coarser core mesh take over.
Use `bl_thickness_fraction` (a fraction of the radius) or `bl_thickness_mm` (an absolute
thickness) to control this:

```python
# Span only 30 % of the pipe radius with the prism stack
yhgrcalc("Air", 50, 10, 2.5, 125, 1, 8, bl_thickness_fraction=0.3)   # GR ~ 3.04

# Or specify an absolute total stack thickness of 10 mm
yhgrcalc("Air", 50, 10, 2.5, 125, 1, 20, bl_thickness_mm=10)          # GR ~ 1.39
```

### Rough walls

The turbulent internal correlation (Haaland) accepts an absolute wall roughness:

```python
yhgrcalc("Air", 50, 10, 2.5, 125, 1, 8, roughness_mm=0.5)
```

## 2. External flow (flat plate / aerodynamic surface)

For external flows, set `flow_type="external"`. Here `hydraulicdia_mm` is reinterpreted as
the **characteristic length** along the flow (e.g. chord or plate length), and you **must**
supply the free-stream velocity with `flow_velocity_mpersec` — deriving a velocity from
mass flow and a pipe-area assumption is meaningless for external flow.

```python
from cfdpre import yhgrcalc

result = yhgrcalc(
    fluid="Air",
    temperature_c=25,
    pressure_bar=1.01325,
    massflow_kgpersec=2.5,        # ignored for external flow
    hydraulicdia_mm=1000,         # characteristic length (1 m chord) in mm
    target_yplus=1,
    num_layers=15,
    flow_type="external",
    flow_velocity_mpersec=30,     # required for external flow
)

print(result["Growth Ratio"])                          # ~ 1.49
print(result["boundary layer thickness [delta99] [m]"]) # ~ 0.0210 m
```

You can still override the correlation-based boundary-layer thickness with
`bl_thickness_mm` if you want to target a specific stack height.

## Reading the result

`yhgrcalc` returns a plain `dict`. The keys most relevant to meshing are:

| Key | Meaning |
|---|---|
| `first layer height [yh] [m]` | First (wall-adjacent) layer thickness |
| `Growth Ratio` | Geometric expansion ratio between layers |
| `Final Layer Thickness [m]` | Thickness of the outermost layer |
| `boundary layer thickness [delta99] [m]` | Total thickness the stack spans |
| `reynolds number` | Reynolds number used for the correlations |
| `skin friction coefficient [cf]` | Fanning skin friction coefficient |

The full set of keys (including all intermediate fluid properties) is listed in the
[API Reference](api/reference.md).