Running and exit codes¶

The commands¶

Command	Does
`nanopnp run case.yaml`	Walks the pipeline for one case and writes a run directory; `--progress` prints each stage and solver rung to standard error as it starts, which is the default on a terminal, and `--no-progress` stops it
`nanopnp stage <name> case.yaml`	Runs one stage and the stages it reads, and prints its artefact; `--only` refuses to compute anything upstream
`nanopnp stage --list`	Lists the stages, without importing any of them
`nanopnp inspect <path>`	Reads a run directory, a stored artefact or a record back
`nanopnp reproduce <run>`	Re-solves an archived run in a fresh store and compares every scalar (QR-08)
`nanopnp plot <case, run or sweep> [stage] --out <file>`	Draws a stage's figure to a PNG, SVG or PDF file; needs the `plot` extra (Outputs and quantities)
`nanopnp geometry cylinder`	Writes an idealised pore as a geometry file (Meshes)
`nanopnp mesh <geometry file>\\|reference`	Writes a gated mesh (Meshes)
`nanopnp sweep plan\\|run\\|collect`	Plans, dispatches and collects a sweep (Sweeps)
`nanopnp validate case case.yaml`	Checks a case as a run would, without meshing or solving it
`nanopnp validate …`	The Tier-3 COMSOL comparison harness
`nanopnp env`	Reports the version, the data locations and the store

Every option is in the generated command-line reference.

No flag changes what is solved. Flags choose where output goes (--store, --run-dir), which stages run (--upto, --only), and how much is logged. Every quantity that changes a number lives in the case file, so the manifest records one source of truth.

--upto <stage> runs that stage and every stage it reads, directly or through another, in the walk's order, and nothing else. --upto mesh runs the geometry stages and the mesh; --upto protonation runs the structure and the protonation, without the geometry between them; --upto materials runs the case and the materials alone. A stage is handed only the artefacts it declares, so a truncated walk cannot hand a stage less than a complete one does.

Output streams¶

Standard output carries only the command's result, as aligned text or, with --json, as one JSON document you can parse. Log records and diagnostics go to standard error. -v logs at INFO, including each continuation rung and Newton's progress; -vv logs at DEBUG. --log-file also writes the log to a file.

A failure prints its diagnostic without a traceback. For a gate abort, the diagnostic is the message: which gate, what value, where (QR-12). --traceback prints the traceback too. It is the thing to attach to a bug report for an exit code 1.

Exit codes¶

The exit status is a contract (the IF-02 exit-code NOTE): a job array branches on it, and a member that failed must be told apart from one that was refused.

Code	Meaning	What to do
`0`	success
`1`	unexpected failure	a bug: re-run with `--traceback` and report it
`2`	usage error	fix the command line
`3`	the case was refused	fix the case file; a retry fails identically
`4`	a numerical gate aborted	read the diagnostic: refine the mesh, fix the field, or change the operating point
`5`	Newton or the continuation ladder did not converge	a harder operating point; approach it from a converged neighbour (a sweep does this for you)
`130`	cancelled

Which exception maps to which code is in the generated exit-code reference.

Continuation¶

A hard operating point, such as high salt, high bias or strong charge, is not solved cold. With numerics.continuation: default_ladder, the solve climbs the fixed ladder of NUM-18. It starts from Poisson–Boltzmann and equilibrium PNP, ramps the fixed charge and then the bias, switches on the flow, then the corrections, then the steric flux, and finally sweeps the salt to its target. Each rung starts from the last converged state, and every rung is recorded. -v shows them. Because the ladder is a fixed path, a case that switches the flow or its terms off is refused under it: use numerics.continuation: none for such an ablation (the NUM-18 NOTE). A sweep continues the same way across its points: each member starts from a converged neighbour.

The store and the case's files¶

The artefact store is nanopnp-store/ in the working directory. --store or $NANOPNP_STORE names another. The files a case names by a relative path are read beside the case file, so the working directory chooses the store and nothing else (Case files). nanopnp env prints the store and the data locations a run would use.

Threads and cost¶

NGSolve and the linear algebra libraries under it use every core of the host unless told otherwise. nanopnp run --threads <N> sets OMP_NUM_THREADS, OPENBLAS_NUM_THREADS and MKL_NUM_THREADS to N before those libraries start; setting the three in the shell or the submission script does the same. A sweep run with more than one worker pins each worker to one thread, so --workers sets how many cores a sweep uses.

A solve takes seconds on the coarse meshes of the examples. On a fine mesh it takes minutes to tens of minutes, and most of that time goes to assembling and factorising the system. Measured timings are in cost-study.json.