Skip to content

cli_usage.md

Latest commit

 

History

History
281 lines (197 loc) · 8.83 KB

cli_usage.md

File metadata and controls

281 lines (197 loc) · 8.83 KB
Raw

CLI usage guide

This page gives practical command-line examples for running LDSFL-Meander without the GUI.

The CLI entry point is:

python -m run_ldsfl

or, after installing the package in editable mode:

ldsfl-run

Quick start

From the repository root:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 100 --no-plots

This runs case 1 from Input/Parameter.csv, reads the initial centreline from Input/xy.csv, writes results under Output/, and disables plot generation.

Recommended smoke test

Use this before opening a pull request or after changing environments:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 1 --no-plots
python -m pytest

Selecting cases

The --cases option selects one or more case IDs from Input/Parameter.csv.

Examples:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 100 --no-plots
python -m run_ldsfl --base-dir . --cases 1,2 --max-steps 100 --no-plots
python -m run_ldsfl --base-dir . --cases 1-2 --max-steps 100 --no-plots

The case IDs must exist in the Id column of Input/Parameter.csv.

Common options

Option Typical use
--base-dir . Use the current repository as the project root.
--cases 1 Run one selected case from Input/Parameter.csv.
--max-steps 1000 Limit the number of solver iterations. Useful for reproducible short runs.
--nprint 100 Save periodic outputs every Nprint iterations.
--no-plots Disable PNG plot generation. Useful for CI, remote servers, and headless sessions.
--backend numpy Use the reference NumPy backend. This is the default and safest option.
--backend numba Use the optional Numba backend if installed and validated for the selected path.
--geometry-unwrap-backend python Use the reference/default curvature-angle unwrap.
--geometry-unwrap-backend numba Use the optional exact JIT curvature-angle unwrap; requires the numba extra and is independent of --backend.
--neck-detector-backend kdtree Use the SciPy KDTree neck cutoff detector. This is the reference/default.
--neck-detector-backend numba_grid Use the optional exact Numba spatial-grid neck detector; requires the numba extra and is independent of the flow and geometry unwrap backends.
--flow-bc free Use the default free-boundary flow solver.
--flow-bc periodic Use the periodic solver path. Treat as experimental unless validated for the target study.
--cstab 0.01 Set the adaptive-timestep stability coefficient.
--erosion-rate 1e-8 Set the finite, positive bank-erodibility / migration-rate coefficient.
--stop-on-sinuosity-stability 1 Stop early when the equivalence-style sinuosity stability criterion is satisfied.
--return-equivalence-stability 1 Compute and return the final equivalence/HAC stability diagnostic without using it as a stopping criterion.

Bank erodibility and simulated-time scaling

The bank-erodibility / migration-rate coefficient is exposed through:

python -m run_ldsfl --base-dir . --cases 1 --erosion-rate 1e-8

The historical default is 1.0e-8. The value must be finite and strictly positive.

The coefficient multiplies the migration-velocity response. However, the adaptive timestep is inversely proportional to the maximum migration component. Consequently, changing --erosion-rate normally changes cumulative simulated time much more than it changes geometry versus solver iteration.

This distinction matters when:

  • comparing runs stopped at the same max_steps;
  • interpreting dt_cum;
  • using --max-sim-time;
  • calibrating results against a physical timescale.

The selected value is returned in the run summary as erosion_rate.

Backend guidance

The neck cutoff detector is selected independently with --neck-detector-backend kdtree|numba_grid. The default kdtree path uses the SciPy reference implementation and does not require Numba. numba_grid uses the optional exact spatial-grid detector and requires the numba extra. The choice does not change --backend or --geometry-unwrap-backend. If an individual numba_grid search cannot safely represent its cell coordinates in the integer grid, it delegates to the KDTree reference. This numerical-safety fallback does not select a different backend automatically or replace the error when Numba is missing.

For the validated case-1 5,000-step study, benchmark-prototype measurements showed median speedups of about 19.93x for detector calls, 2.71x for geometry, and 1.59x for the whole solver. These are workload- and machine-specific measurements, not a guarantee for other runs. Record the selected neck detector backend with the run configuration.

Use NumPy first:

python -m run_ldsfl --base-dir . --cases 1 --backend numpy --max-steps 100 --no-plots

The Numba backend is optional:

python -m run_ldsfl --base-dir . --cases 1 --backend numba --max-steps 100 --no-plots

NumPy should be treated as the reference backend. Numba is an acceleration path and should be compared with NumPy for the selected solver branch before relying on it for a study.

The flow-field backend (--backend) and curvature-angle unwrap backend (--geometry-unwrap-backend) are independent controls. The unwrap backend defaults to python, the authoritative reference implementation. Selecting numba opts into the exact serial JIT implementation and requires Numba to be installed; its first use may incur JIT compilation. Installing Numba does not change the default path.

For example, use the Numba flow solver with the Python curvature unwrap:

python -m run_ldsfl --base-dir . --cases 1 --backend numba --geometry-unwrap-backend python

Or use the NumPy flow solver with the Numba curvature unwrap:

python -m run_ldsfl --base-dir . --cases 1 --backend numpy --geometry-unwrap-backend numba

Output folders

The --cases option selects case IDs from Input/Parameter.csv, but the generated output directory uses the solver output identifier id_files. This identifier is built from the selected case ID and key parameter values, matching the README convention Output/<id_files>/.

For a run with generated output identifier <id_files>, results are written under:

Output/<id_files>/

The main subfolders are:

Folder Contents
Output/<id_files>/xyu/ Geometry snapshots with centreline coordinates, arclength, tangent angle, curvature, and migration velocity.
Output/<id_files>/files/ Variable-history CSV files and the sinuosity-history CSV file.
Output/<id_files>/plot/ PNG planform and sinuosity plots when plotting is enabled.
Output/<id_files>/xy_cut/ Cutoff geometry CSV files when cutoffs occur.

Main output files

Geometry snapshot CSV files

Pattern:

Output/<id_files>/xyu/xyu_<id_files>_*.csv

Columns:

Column Meaning
x Centreline x-coordinate.
y Centreline y-coordinate.
s Arclength coordinate.
th Tangent angle.
c Curvature.
U Migration velocity response used by the morphodynamic update.

Variable-history CSV files

Pattern:

Output/<id_files>/files/var_<id_files>_*.csv

These files store model variables accumulated over saved iteration blocks.

Sinuosity-history CSV file

Pattern:

Output/<id_files>/files/sinuosity_history_<id_files>.csv

Columns:

Column Meaning
step Solver iteration step.
sinuo Dimensionless sinuosity.

The x-axis in the sinuosity history is solver iteration step, not dimensional physical time.

Headless and CI runs

For automated runs, remote machines, GitHub Actions, or macOS sessions without a stable GUI backend, use:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 100 --no-plots

This avoids GUI display requirements and reduces the chance of matplotlib backend issues.

Example reproducible run

On Windows cmd:

python -m run_ldsfl ^
  --base-dir . ^
  --cases 1 ^
  --backend numpy ^
  --max-steps 1000 ^
  --nprint 100 ^
  --no-plots

On Linux/macOS shells:

python -m run_ldsfl \
  --base-dir . \
  --cases 1 \
  --backend numpy \
  --max-steps 1000 \
  --nprint 100 \
  --no-plots

Troubleshooting

The run is slow

Use a shorter run first:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 10 --no-plots

Then increase --max-steps.

Plotting fails on macOS or a remote machine

Use:

python -m run_ldsfl --base-dir . --cases 1 --max-steps 100 --no-plots

Also see macos_gui_notes.md.

I need the final equivalence/HAC stability diagnostic

Use:

python -m run_ldsfl --base-dir . --cases 1 --return-equivalence-stability 1

This diagnostic is more expensive than the lightweight moving-window diagnostic and is not computed by default for long runs.