Command-Line Interface

Command-Line Interface#

underPINN ships a YAML-driven CLI so experiments require zero code changes. Run scripts directly, or point the CLI at the same YAML — both work identically.

Command

Description

run

Run a single problem from a YAML config

resume

Verify the config MD5 hash against a stored snapshot and reset done for continuation; warns if any field changed

sweep

Cartesian-product hyperparameter sweep; each combination gets its own sub-directory

bench

Full benchmark suite across all registered problems

list

List all registered runners

show

Print the resolved config without training

version

Print the framework version string

Single run#

python -m underPINN run examples/burgers/config.yaml
python -m underPINN run examples/wave/config.yaml
python -m underPINN run examples/helmholtz/config.yaml
python -m underPINN run examples/ramp/config.yaml
python -m underPINN run examples/airfoil/config.yaml
python -m underPINN run examples/cylinder/config.yaml
python -m underPINN run examples/sod_shock/config.yaml
python -m underPINN run examples/AAA/config.yaml
python -m underPINN run examples/pipe_flow_rheology/config.yaml
python -m underPINN run examples/pipe_flow/pipe_flow.yaml

Hyperparameter sweep#

Cartesian product across any dot-separated config key. Each run gets its own sub-directory with a saved config.yaml for full reproducibility.

python -m underPINN sweep examples/burgers/burgers_nu_sweep.yaml

# sweep YAML anatomy
base:                           # shared config for all runs
  problem: burgers
  network:
    type: mlp
    layers: [2, 64, 64, 64, 1]
  training:
    epochs: 5000

sweep:                          # dot-separated key → list of values
  physics.nu       : [0.1, 0.05, 0.025, 0.01]
  training.epochs  : [3000, 5000]

Each run lands in outputs/…/run_000, run_001, …

Inspect & list#

python -m underPINN show examples/wave/config.yaml     # print resolved config
python -m underPINN resume examples/burgers/config.yaml # verify config hash, allow resume
python -m underPINN list                                # list registered runners
python -m underPINN version                              # print version string

Registered runners: burgers, wave, helmholtz, heat_forward, heat_inverse,
ode, ldc, airfoil, pipe_flow, ramp, burgers_transfer,
pipe_flow_unsteady_transfer, inverse_diffusion, ...

Benchmark suite#

python -m underPINN bench
python -m underPINN bench \
    --problems burgers wave ode_exp \
    --epochs 500 2000 5000 \
    --output outputs/bench
python -m underPINN bench --all
python -m underPINN bench --from-json outputs/bench/results.json

See Benchmark Suite for the full options and output file reference.

Adding a new physics case#

Registering a new problem only requires touching one dispatch table:

underPINN/runner/dispatch.py#
_REGISTRY = {
    "burgers"  : ("examples/burgers/burgers.py",  "run_burgers"),
    "wave"     : ("examples/wave/wave.py",        "run_wave"),
    "mycase"   : ("examples/mycase/mycase.py",    "run_mycase"),  # ← add this
    # ... no other files need to change
}

Three-step recipe

  1. Create examples/mycase/mycase.py — define run_mycase(cfg) -> dict

  2. Create examples/mycase/config.yaml — set problem: mycase

  3. Add one line to underPINN/runner/dispatch.py

No other files need to change.

Contents