flow-props 0.1.2__tar.gz → 0.3.0__tar.gz

flow_props-0.3.0/.github/workflows/package.yml

@@ -0,0 +1,41 @@
+# GPL-3.0-or-later - see LICENSE
+name: Package
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Build distributions
+        run: |
+          python -m pip install build twine
+          python -m build
+          python -m twine check dist/*
+
+      - name: Smoke-test wheel
+        run: |
+          python -m venv "${RUNNER_TEMP}/wheel-test"
+          "${RUNNER_TEMP}/wheel-test/bin/python" -m pip install dist/*.whl
+          cd "${RUNNER_TEMP}"
+          "${RUNNER_TEMP}/wheel-test/bin/python" -c "import flow_props"
+          "${RUNNER_TEMP}/wheel-test/bin/flow-props" --help
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: distributions
+          path: dist/

{flow_props-0.1.2 → flow_props-0.3.0}/.github/workflows/publish.yml

@@ -10,12 +10,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -32,10 +32,10 @@ jobs:
     needs: test
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: "3.11"
 
@@ -46,7 +46,7 @@ jobs:
         run: python -m build
 
       - name: Upload dist artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -60,7 +60,7 @@ jobs:
 
     steps:
       - name: Download dist artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -74,7 +74,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
       - name: Create GitHub Release (skip if it already exists)
         run: |
           if gh release view "${{ github.ref_name }}" >/dev/null 2>&1; then

{flow_props-0.1.2 → flow_props-0.3.0}/.github/workflows/test.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.11", "3.12", "3.13"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v6

{flow_props-0.1.2 → flow_props-0.3.0}/CITATION.cff

@@ -6,7 +6,6 @@ type: software
 authors:
   - family-names: "Hader"
     given-names: "Christoph"
-    affiliation: "University of Arizona"
     orcid: "https://orcid.org/0000-0002-0956-000X"
 repository-code: "https://github.com/uahypersonics/flow-props"
 license: GPL-3.0-or-later

{flow_props-0.1.2 → flow_props-0.3.0}/PKG-INFO

@@ -1,18 +1,19 @@
 Metadata-Version: 2.4
 Name: flow-props
-Version: 0.1.2
-Summary: Extract flow properties from CFD data: boundary layer thickness, entropy layer thickness
-Author-email: Christoph Hader <chader@arizona.edu>
+Version: 0.3.0
+Summary: Extract flow properties from CFD data: boundary layer, entropy layer, shock
+Author-email: Christoph Hader <christoph.hader@gmail.com>
 License-Expression: GPL-3.0-or-later
 Project-URL: Homepage, https://github.com/uahypersonics/flow-props
 Project-URL: Repository, https://github.com/uahypersonics/flow-props
-Keywords: boundary-layer,entropy-layer,cfd,flow-properties,aerodynamics
+Keywords: boundary-layer,entropy-layer,shock,cfd,flow-properties,aerodynamics
 Classifier: Development Status :: 1 - Planning
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Physics
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -30,7 +31,7 @@ Dynamic: license-file
 
 # flow-props
 
-Python tool suite to extract flow properties from CFD data, such as boundary layer thickness and entropy layer thickness.
+Python tool suite to extract flow properties from CFD data, such as boundary layer thickness, entropy layer thickness and the shock.
 
 [![Test](https://github.com/uahypersonics/flow-props/actions/workflows/test.yml/badge.svg)](https://github.com/uahypersonics/flow-props/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/flow-props)](https://pypi.org/project/flow-props/)
@@ -45,15 +46,37 @@ Python tool suite to extract flow properties from CFD data, such as boundary lay
 pip install flow-props
 ```
 
+To upgrade an existing installation:
+
+```bash
+pip install --upgrade flow-props
+```
+
 ## Quick Start
 
-```python
-import flow_props
+Every calculation is a command group (`bl`, `entropy-layer`, `profiles`, `shock`):
+
+```bash
+flow-props bl init     # writes bl.toml, every key documented
+flow-props bl run      # reads bl.toml
+flow-props shock init  # shock curve of a solution (for grid-generator's [shock] curve)
+flow-props shock run
 ```
 
-## Features
+`flow-props -v <calculation> run` adds debug output.
+
+## Documentation
+
+Full documentation: https://uahypersonics.github.io/flow-props
+
+## Testing
 
-- under construction
+Run the ruff check and pytest check in the project root:
+
+```bash
+ruff check
+pytest --cov
+```
 
 ## Documentation
 

{flow_props-0.1.2 → flow_props-0.3.0}/README.md

@@ -1,6 +1,6 @@
 # flow-props
 
-Python tool suite to extract flow properties from CFD data, such as boundary layer thickness and entropy layer thickness.
+Python tool suite to extract flow properties from CFD data, such as boundary layer thickness, entropy layer thickness and the shock.
 
 [![Test](https://github.com/uahypersonics/flow-props/actions/workflows/test.yml/badge.svg)](https://github.com/uahypersonics/flow-props/actions/workflows/test.yml)
 [![PyPI](https://img.shields.io/pypi/v/flow-props)](https://pypi.org/project/flow-props/)
@@ -15,15 +15,37 @@ Python tool suite to extract flow properties from CFD data, such as boundary lay
 pip install flow-props
 ```
 
+To upgrade an existing installation:
+
+```bash
+pip install --upgrade flow-props
+```
+
 ## Quick Start
 
-```python
-import flow_props
+Every calculation is a command group (`bl`, `entropy-layer`, `profiles`, `shock`):
+
+```bash
+flow-props bl init     # writes bl.toml, every key documented
+flow-props bl run      # reads bl.toml
+flow-props shock init  # shock curve of a solution (for grid-generator's [shock] curve)
+flow-props shock run
 ```
 
-## Features
+`flow-props -v <calculation> run` adds debug output.
+
+## Documentation
+
+Full documentation: https://uahypersonics.github.io/flow-props
+
+## Testing
 
-- under construction
+Run the ruff check and pytest check in the project root:
+
+```bash
+ruff check
+pytest --cov
+```
 
 ## Documentation
 

flow_props-0.3.0/docs/api/architecture.md

@@ -0,0 +1,39 @@
+# Architecture
+
+`flow_props` follows a narrow pipeline:
+
+1. `cfd-io` reads a CFD dataset
+2. `flow_props.profiles.extract_profiles` slices wall-normal profiles at chosen stations
+3. reduction modules compute derived quantities from those profiles
+
+## Module Layout
+
+- `profiles/`: wall-normal profile extraction (along grid lines or interpolated normals)
+- `bl.py`: boundary-layer edge detection and integral thicknesses
+- `entropy_layer.py`: entropy-layer thickness
+- `shock.py`: shock point per grid line and the shock curve
+- `wall.py`: wall shear and thermal quantities
+- `output.py`: Tecplot ASCII writers
+- `calculators/`: one module per CLI calculation (`bl`, `entropy_layer`, `profiles`,
+  `shock`) with its pydantic config model, its `init` template and its `run_case`;
+  `common.py` holds the shared parts (input files, `[stations]`, `[gas]`), and
+  `__init__.py` the registry the CLI is built from
+- `cli/`: Typer app (`app.py`), callbacks (`--version`, `--verbose`), the command-group
+  factory (`cmd_calculator.py`) and the `examples` command
+- `examples/<calculation>/<name>/`: bundled cases; the folders are the registry
+
+## Adding a Calculation
+
+Write `calculators/<name>.py` with a config model, a `TEMPLATE` and
+`run_case(config, config_dir) -> list[str]`, and add one entry to `CALCULATORS` in
+`calculators/__init__.py`. The CLI then has `flow-props <name> init` and `run`.
+
+## Design Intent
+
+The package is deliberately lightweight.
+
+- it does not own CFD file I/O
+- it assumes `cfd-io` has already constructed a dataset
+- it focuses on profile-based property extraction rather than general field operations
+
+That separation keeps `flow_props` easy to reason about and consistent with the rest of the workspace.

{flow_props-0.1.2 → flow_props-0.3.0}/docs/api/index.md

@@ -7,6 +7,7 @@ The public API is intentionally small and organized around the main post-process
 - `flow_props.profiles` for wall-normal profile extraction
 - `flow_props.bl` for boundary-layer edge detection and integral thicknesses
 - `flow_props.entropy_layer` for entropy-layer thickness
+- `flow_props.shock` for the shock point on each grid line and the shock curve
 - `flow_props.wall` for wall shear and heat-transfer quantities
 - `flow_props.cli` for command-line entry points
 
@@ -15,7 +16,7 @@ The public API is intentionally small and organized around the main post-process
 The package re-exports the most common functions through `flow_props` itself, so this style works:
 
 ```python
-from flow_props import extract_profiles, run_bl, run_entropy, run_wall
+from flow_props import extract_profiles, extract_shock, run_bl, run_entropy, run_wall
 ```
 
 Use the pages in this section for a module-by-module view.

flow_props-0.3.0/docs/api/shock.md

@@ -0,0 +1,46 @@
+# Shock
+
+Module: `flow_props.shock`
+
+## Purpose
+
+This module finds the shock on each wall-normal grid line of a structured solution and
+writes the shock curve (see [Shock Extraction](../theory/shock.md) for the method).
+
+## Main Functions
+
+- `find_shock_on_line(values, level=0.5, min_rise=0.05, max_thickness=20.0, method="walk",
+  indicator_threshold=0.0025)`: the shock on one line, as a `ShockCrossing` (fractional
+  `j`, `j_tail`, the outer edge `j_foot`, `thickness_cells`, `detected_by`, and each
+  detector's own point `j_walk`, `j_indicator`, whatever the method), or `None`
+- `extract_shock(ds, quantity="pressure", ..., method="walk", indicator_threshold=0.0025)`:
+  every line of a dataset, as a `ShockExtraction` (station, x, y, j, distance,
+  thickness_cells, detected_by, and the stations without a shock)
+- `smoothness_indicator(values, reference)`: the WENO smoothness indicator along a line,
+  divided by 5040 reference^2
+- `smooth_shock(ds, extraction, length)`: the same points moved, along their grid lines,
+  onto local quadratics fitted in the shock's frame over `length` wall-to-shock distances
+  (see
+  [Smoothing the Curve](../theory/shock.md#smoothing-the-curve))
+- `write_shock_curve(path, extraction)`: the x, y CSV that grid-generator's `[shock] curve`
+  reads
+
+## Example
+
+```python
+import cfd_io
+from flow_props import extract_shock, smooth_shock, write_shock_curve
+
+dataset = cfd_io.read_file("solution.h5")
+extraction = extract_shock(dataset)
+smoothed = smooth_shock(dataset, extraction, length=0.5)
+write_shock_curve("shock_cfd.csv", smoothed)
+
+print(extraction.thickness_cells.max(), extraction.stations_without_shock)
+```
+
+## Notes
+
+- the dataset must use a `StructuredGrid` with $j = 0$ at the wall (cfd-io's canonical
+  orientation) and the outer boundary in the freestream
+- the quantity's field is looked up as `pres`, `pressure`, `p` (or `dens`, `density`, `rho`)

{flow_props-0.1.2 → flow_props-0.3.0}/docs/index.md

@@ -1,6 +1,6 @@
 # flow_props
 
-`flow_props` extracts physically meaningful boundary-layer and wall quantities from structured CFD datasets.
+`flow_props` extracts physically meaningful boundary-layer, entropy-layer and shock quantities from structured CFD datasets.
 
 ## Quick Start
 
@@ -15,8 +15,8 @@ pip install flow-props
 === "CLI"
 
 	```bash
-	flow-props init --bl
-	flow-props run --bl
+	flow-props bl init
+	flow-props bl run
 	```
 
 === "API"

flow_props-0.3.0/docs/theory/shock.md

@@ -0,0 +1,143 @@
+# Shock Extraction
+
+`flow-props shock` finds the shock of a CFD solution on every wall-normal grid line. Each
+line runs from the wall ($j = 0$) to the outer boundary, which must lie in the freestream.
+A shock-capturing solver smears the shock over a few cells, so along the line the
+quantity $q$ (pressure by default, or density) climbs from its freestream value to the
+post-shock value over a short stretch.
+
+## Finding the Jump
+
+Walking inward from the line's outer end, where $q_\infty$ is $q$ at the outer end, a
+detector proposes where a jump starts (`method`):
+
+- **walk** (default): the first point where $q > (1 + \text{min\_rise})\, q_\infty$;
+- **indicator**: the first point whose smoothness indicator reaches
+  `indicator_threshold` (see [Smoothness Indicator](#smoothness-indicator));
+- **hybrid**: both detectors, and the outermost jump either finds, since the shock is
+  the first jump from outside. The report says which detector found each line.
+
+From the proposed start, the steepest cell within `max_thickness` cells inward is the
+jump's core. Walking on inward, the rise per cell shrinks across the jump's rounded
+shoulder; once past the jump's center (the rise below half the steepest), the jump ends
+where the rise shrinks by less than 1 % of the steepest from one cell to the next: at the
+knee into the post-shock plateau or the top of an overshoot. $q_t$ is the post-shock
+value there. The profile is flat
+there, so $q_t$ barely changes when the shock drifts by a cell from one grid line to the
+next. (Ending the jump on the shoulder instead makes $q_t$, and with it the shock point,
+jump at every such drift: a staircase along the shock.)
+
+Because the walk starts outside, the first jump it meets is the shock: the boundary layer,
+the entropy layer and any inner compression are never reached.
+
+## Placing the Shock Point
+
+The shock point is where $q$ crosses
+
+$$
+q_\text{level} = q_\infty + \text{level}\,(q_t - q_\infty),
+$$
+
+interpolated linearly between the two grid points around the crossing. `level = 0.5`
+puts it in the middle of the captured jump, which is where a grid line should sit; values
+toward 0 move it to the freestream side, toward 1 to the post-shock side.
+
+Only this crossing places the point; the foot and tail just bracket the jump. The point
+therefore doesn't depend on `min_rise`, and is placed the same way for a shock of 40 times
+freestream pressure at the nose and a weak one far downstream. On synthetic captured
+shocks (jumps 0.3 to 40 times freestream) it lands within 0.1 cell of the jump's center
+for shocks captured over up to about 5 cells; with a post-shock gradient, a shock smeared
+over more cells comes out inward by up to about 2 % of its thickness. As a shock drifts
+across the cells from one grid line to the next, its point moves smoothly; what remains
+is a small error that repeats with the shock's position inside a cell (about 0.03 to
+0.07 cell for shocks captured over 1 to 2 cells), which the smoothing removes.
+
+## Thickness and Smooth Compressions
+
+The captured thickness is the distance, in cells, between the crossings of 10 % and 90 %
+of the jump. A rise spread over more than `max_thickness` cells (default 20) is a smooth
+compression, not a shock: for example the pressure rise toward the stagnation point on a
+line that ends inside the shock layer. Such lines are reported as having no shock.
+
+## Comparison with a Shock-Line Grid
+
+On a shock-line grid the shock is meant to lie on grid line `shock_line_j`. The report
+gives each line's offset $j_\text{shock} - j_s$ in cells, and the run summary the range of
+offsets and the number of lines more than a quarter cell off.
+
+## Checks in the Report
+
+Both detectors run on every line, whichever the method, so each result can be checked
+against the other. The run summary warns when
+
+- the shock's outer edge (where $q$ crosses 10 % of the jump) lies within 5 cells of the
+  outer boundary: too little freestream outside it to read $q_\infty$ from, or a
+  disturbance ahead of the shock was taken for it;
+- the walk and the indicator differ by more than 3 cells on a line: one of them found
+  something else. A smooth compression ahead of the shock (e.g. freestream compressed
+  against a bent symmetry line) is met first by the walk, while the indicator, which
+  only flags sharp jumps, finds the shock.
+
+It also counts how often the shock's outer edge changes grid row along the body and, on
+a shock-line grid, how often it crosses the shock line `shock_line_j`. A captured shock
+that moves between rows makes a solver's wall quantities wave; on a converged
+shock-line grid the edge stays on one side of the shock line.
+
+## Solutions at Cell Centres
+
+A finite-volume solution holds cell values. Read through cfd-io as fields at the cell
+centres of the vertex grid (association `cell`: one point fewer than the grid in each
+direction), they are put on a grid of the cell centres, each the mean of its cell's
+corners, and the shock is found along the lines through them. Those lines lie half a
+cell from the vertex grid's lines, so:
+
+- the shock line `shock_line_j` counts vertices, and cell $j$ lies at $j + 0.5$ on the
+  vertex grid; the report's `j_shock` and the offsets use that, and the run summary
+  says the solution was at cell centres;
+- the first line runs half a cell off the symmetry axis, so the curve starts there;
+  grid-generator continues a curve that starts slightly off the axis to it.
+
+A solution whose grid is the cell centres themselves (stored as an ordinary grid)
+can't be told from vertex data; write cell values on the vertex grid instead.
+
+## Smoothing the Curve
+
+The extracted curve becomes a grid line of the next grid, so line-to-line jitter of the
+points would become wiggles in the grid. With `smoothing_length = a` (default 0.5), each
+point is moved onto a quadratic fitted, by least squares, through the shock points within
+a stretch of the shock $a\,d$ long, with $d$ the local wall-to-shock distance, and the
+curve that is written is the smoothed one.
+
+The stretch scales with $d$ because the shock bends on scales of $d$: tightly around a
+blunt nose, gently far downstream. A fixed number of grid lines fails one way or the
+other: a precursor grid's lines are dense on the body compared with a shock-line grid's
+cells, so a short window leaves wiggles a few millimetres long that the new grid resolves
+(its shock line zig-zags), and a long one flattens the nose.
+
+The fit is made in the shock's own local frame: the tangent along the chord of the window
+and the normal to it. The point then moves along its own grid line onto the fitted
+quadratic, so there is still one point per grid line. Fitting the distance along the grid
+lines instead would be wrong where the body's curvature jumps: at a nose-body tangency
+the wall normals stop turning, and the distance along them bends although the shock is
+smooth. A straight shock over such lines stays exactly where it is.
+
+The report keeps the raw and the smoothed points, and the run summary says how far the
+smoothing moved them, in cells; `smoothing_length = 0` writes the points as found.
+
+## Smoothness Indicator
+
+A WENO smoothness indicator measures how far a stencil is from smooth. flow-props uses the
+central five-point measure of ninth-order WENO (Balsara and Shu, J. Comput. Phys. 160,
+2000) divided by $5040\, q_\infty^2$, which on a smooth ramp equals
+$(\Delta q_\text{cell} / q_\infty)^2$, with $\Delta q_\text{cell}$ the rise per cell; a jump
+captured over fewer cells scores higher. The default threshold 0.0025 is thus a rise of
+5 % of freestream per cell. Dividing by $q_\infty^2$ makes one threshold work for any
+freestream pressure.
+
+Its peak scales with $(\text{jump} / \text{thickness})^2$, so the threshold that finds
+the shock depends on how strong and how smeared it is: on synthetic captured shocks a
+jump of $0.3\, q_\infty$ peaks at about 0.06 when captured over 2 cells and at about
+0.0015 over 9 cells. Along a body, from the strong nose shock to a weak, smeared shock
+downstream, a single threshold can miss part of the shock; lower it, or use the walk (its
+`min_rise` is a total rise, whatever the width) or the hybrid. Where the walk and the
+indicator find the same jump, the shock point is the same: the level crossing places it.

{flow_props-0.1.2 → flow_props-0.3.0}/docs/user-guide/basic-usage.md

@@ -17,7 +17,7 @@ For split solution/grid formats, provide the separate grid file through `cfd-io`
 ```python
 from flow_props import extract_profiles
 
-profiles = extract_profiles(dataset, stations=[10, 50, 100], j_max=80)
+profiles = extract_profiles(dataset, stations=[10, 50, 100])
 print(profiles[0].keys())
 ```
 
@@ -27,6 +27,19 @@ Each extracted profile includes:
 - `eta`
 - one array per flow field available in the input dataset
 
+For config-driven extraction, `flow-props bl init` creates `bl.toml`. Set
+`fname` to a structured HDF5 file, then run `flow-props bl run`. To look at the
+profiles behind the table, `flow-props profiles init` / `run` writes them, for the
+same stations, as multi-zone Tecplot ASCII.
+`cfd-io` handles file reading; `flow-props` does not convert CFD formats.
+Leave `[stations]` empty to process all i-indices from 0 through `Nx - 1` with
+step 1, or choose one station-selection mode to limit the run.
+
+Only the `htot_derivative` criterion requires gas constants. The tool reads
+`gamma` and `r_gas` from HDF5 attributes, fills missing values from an adjacent
+`flow_conditions.json`, and allows optional `[gas]` overrides. The default
+`velocity_ratio` criterion does not require those values.
+
 ## Compute Boundary-Layer Properties
 
 ```python
@@ -58,6 +71,18 @@ entropy_results = run_entropy(
 )
 ```
 
+## Extract the Shock
+
+```python
+from flow_props import extract_shock, write_shock_curve
+
+extraction = extract_shock(dataset, quantity="pressure", level=0.5)
+write_shock_curve("shock_cfd.csv", extraction)
+```
+
+`extraction.j` holds the fractional grid index of the shock on each line, for comparing
+with a shock-line grid's shock line.
+
 ## Compute Wall Quantities
 
 ```python

flow_props-0.3.0/docs/user-guide/cli.md

@@ -0,0 +1,60 @@
+# CLI
+
+The command-line interface is exposed through `flow-props`. Every calculation is a
+command group with the same commands:
+
+```bash
+flow-props <calculation> init       # write <calculation>.toml, every key documented
+flow-props <calculation> run        # run <calculation>.toml
+flow-props <calculation> examples   # bundled cases (calculations that ship some)
+```
+
+## Calculations
+
+| Command | What it computes | Default config |
+|---|---|---|
+| `bl` | boundary-layer edge $\delta$, $\delta^*$, $\theta$, $H$ and edge state per station | `bl.toml` |
+| `entropy-layer` | entropy-layer thickness per station | `entropy-layer.toml` |
+| `profiles` | wall-normal profiles of every flow variable per station | `profiles.toml` |
+| `shock` | the shock curve, and its offset from a shock-line grid's shock line | `shock.toml` |
+
+## Global Options
+
+Global options go before the calculation:
+
+```bash
+flow-props --version        # or -V
+flow-props -v shock run     # --verbose: debug output from flow-props (not from cfd-io)
+```
+
+## init
+
+```bash
+flow-props bl init                    # writes bl.toml
+flow-props bl init -o ogive_bl.toml   # another name (then: flow-props bl run -c ogive_bl.toml)
+flow-props bl init --force            # overwrite an existing file
+```
+
+## run
+
+`run` reads the calculation's default config, or the one named with `--config` / `-c`.
+Paths in the config (solution file, outputs) are relative to the config file's folder.
+
+```bash
+flow-props bl run
+flow-props shock run -c precursor.toml
+```
+
+Bad input (a misspelled key, a missing solution file, a missing field) is reported as one
+`error: ...` line with exit code 1.
+
+## examples
+
+```bash
+flow-props bl examples                       # list the bundled cases
+flow-props bl examples sharp_flat_plate_m5   # copy its files here (as bl.toml)
+flow-props bl run
+```
+
+An example is copied into the current folder; it refuses to overwrite existing files
+unless `--force` is given.