Running numgeo¶

`pynumgeo.solver` ¶

Run numgeo and judge the outcome.

:func:run writes or copies the input into a job folder, starts numgeo there (numgeo inp=<job> out=<job> ncpus=<n>), streams the console and decides from the report files whether the run succeeded (:class:RunStatus): numgeo's exit status is 0 after most errors (report%error ends with a plain stop, src/report/report_error_.f90:62), so pynumgeo reads the .log, .sta, .msg, the console and the dump files, and checks that every step reached its end time (a step whose inc= is exhausted ends silently, src/main.f90:555). :func:assess judges a job folder that has already run.

Example (needs numgeo; NUMGEO_EXE or numgeo on PATH)::

from pynumgeo.solver import run
res = run("model.inp", "runs/beam", job="beam", ncpus=2, timeout=600, on_line=print)
print(res.status, res.reason)
for s in res.steps:
    print(s.name, s.t_reached, "/", s.t_end, s.increments, "increments", s.cutbacks, "cutbacks")
for m in res.errors:
    print(m.text, m.message_id)    # e.g. src/input/read_input.f90:543

res = run(deck, "runs/check", check_only=True)   # INPUT_ACCEPTED or FAILED with the input errors

Examples:

>>> from pynumgeo.solver import RunStatus
>>> [s.value for s in RunStatus]
['SUCCESS', 'FAILED', 'INCOMPLETE', 'TIMEOUT', 'CRASHED', 'INPUT_ACCEPTED']

`ExecutableNotFoundError` ¶

Bases: FileNotFoundError

No numgeo executable could be found.

`MessageMatch(message_id, file, line, routine, severity, terminates, candidates)` `dataclass` ¶

The template a message text matches.

Attributes:

Name	Type	Description
`message_id`	`str`	catalogue id `src/...f90:<line>`.
`file`	`str`	solver source file.
`line`	`int`	solver source line.
`routine`	`str \| None`	routine containing the line.
`severity`	`str`	severity of the template (`error`, `warning`, `fatal-stop`, `info`).
`terminates`	`bool \| None`	whether the solver stops at this site.
`candidates`	`tuple[str, ...]`	ids of all equally good templates (identical text written at several sites).

`RunFailedError(result)` ¶

Bases: RuntimeError

Raised by :meth:RunResult.raise_for_status; the result is in .result.

`RunResult(status, reason, workdir, job, exit_code=None, duration=0.0, command=list(), steps=list(), messages=list(), files=list(), version=None, notes=list(), console_tail=list())` `dataclass` ¶

Outcome of :func:pynumgeo.solver.run (or :func:pynumgeo.solver.assess for an existing job folder).

Attributes:

Name	Type	Description
`status`	`RunStatus`	see :class:`RunStatus`.
`reason`	`str`	human-readable explanation of the status.
`workdir`	`Path`	job folder (numgeo's working directory).
`job`	`str`	job name (`inp=` and `out=`).
`exit_code`	`int \| None`	exit status of the process (negative: killed by that signal, POSIX); `None` if unknown.
`duration`	`float`	wall-clock seconds of the run.
`command`	`list[str]`	the command line that was started.
`steps`	`list[StepReport]`	one report per step of the deck.
`messages`	`list[SolverMessage]`	errors, warnings and notes of numgeo (in file order: `.log`, `.sta`, `.msg`, console, dump files).
`files`	`list[Path]`	files created or changed by the run (absolute paths, sorted).
`version`	`str \| None`	numgeo version from the banner (`numgeo2026-v2 (Oct 26 2026)`).
`notes`	`list[str]`	remarks of the runner (environment, fallbacks, what could not be verified).
`console_tail`	`list[str]`	the last lines of the console output (stdout and stderr).

`ok` `property` ¶

True for SUCCESS and INPUT_ACCEPTED.

`log_path` `property` ¶

<workdir>/<job>.log (may not exist if numgeo stopped before opening it).

`sta_path` `property` ¶

<workdir>/<job>.sta.

`msg_path` `property` ¶

<workdir>/<job>.msg.

`console_path` `property` ¶

<workdir>/<job>.console.log: stdout and stderr of the run, written by pynumgeo.

`errors` `property` ¶

Messages with severity error.

`warnings` `property` ¶

Messages with severity warning.

`raise_for_status()` ¶

Raise :class:RunFailedError unless :attr:ok; return self otherwise.

`summary()` ¶

JSON-serialisable summary (for agents and --json output).

`RunStatus` ¶

Bases: StrEnum

Outcome of a numgeo run (compares equal to its name, e.g. status == "SUCCESS").

`SolverMessage(severity, text, origin, file=None, line=None, routine=None, message_id=None, candidates=(), rule_ids=(), phase=None, runtime=False, count=1)` `dataclass` ¶

An error, warning or note found in the report files, the console or a dump file.

Attributes:

Name	Type	Description
`severity`	`MessageSeverity`	`error`, `warning` or `info`.
`text`	`str`	the message text (70-character chunks of the `.log` joined again, report_.f90:205-238).
`origin`	`str`	where it was found, `<file>:<line>` (`console:<line>` for the console).
`file`	`str \| None`	numgeo source file of the matching message template (`src/...f90`), if matched.
`line`	`int \| None`	line of that source file.
`routine`	`str \| None`	routine of that source line.
`message_id`	`str \| None`	id of the template in the catalogue's message inventory (`src/...f90:<line>`).
`candidates`	`tuple[str, ...]`	ids of all equally good templates (the same text is written at several places).
`rule_ids`	`tuple[str, ...]`	pynumgeo validator rules whose `source` covers the matched source line.
`phase`	`Phase`	`input` (before `-> PREPROCESSING END` in the `.log`), `analysis` (after it), `None` (not from the `.log`).
`runtime`	`bool`	the message comes from the Fortran runtime or the operating system (crash), not from numgeo's own code.
`count`	`int`	how often the identical message was written (repetitions are listed once, at the first origin).

`source` `property` ¶

file:line of the solver source, if the message was matched.

`as_dict()` ¶

Plain dict (JSON-serialisable).

`StepReport(index, name, t_end, t_reached, increments, cutbacks, started, terminated, completed, iterations=None, procedure=None, skipped=False, note=None)` `dataclass` ¶

What happened in one step of the deck.

Attributes:

Name	Type	Description
`index`	`int`	1-based position of the step in the deck (in the `.sta` if the deck is unknown).
`name`	`str \| None`	step name (as written in the `.sta`: upper case, blanks removed).
`t_end`	`float \| None`	end time of the step from the deck (`None` if unknown or not a time, e.g. `*Reduction`).
`t_reached`	`float \| None`	step time of the last accepted increment from the `.sta` (4 significant digits, `g11.4`, report_statistics.f90:207); `None` if not reported.
`increments`	`int \| None`	accepted increments.
`cutbacks`	`int \| None`	rejected attempts (a rejected attempt is followed by a line with the same increment number, src/main.f90:574-579).
`started`	`bool`	the step block exists in the `.sta` (`-> Step = ...`, report_statistics.f90:71).
`terminated`	`bool`	the `.sta` has `Step sucessfully terminated` for it (report_statistics.f90:139); numgeo prints it also when `inc=` was exhausted before `t_end`.
`completed`	`bool`	terminated and (where verifiable) `t_reached` equals `t_end` (relative tolerance `1e-3`, the `.sta` prints 4 significant digits).
`iterations`	`int \| None`	total number of equilibrium iterations (`Total number of iterations`).
`procedure`	`str \| None`	`STATIC`, `TRANSIENT`, ... (`Type =` line of the `.sta`, else the deck).
`skipped`	`bool`	not run in this job (restart with `oldjob=` continues after it).
`note`	`str \| None`	why the step is not complete, or what could not be verified.

`as_dict()` ¶

Plain dict (JSON-serialisable).

`check_flags(flags)` ¶

Validate extra command-line flags and return them as a list.

Known flags: :data:KNOWN_FLAGS, oldjob=<job name> (restart, main.f90:493-497) and assembly-partitions=<integer >= 0>. inp=, out= and ncpus= are set by :func:pynumgeo.solver.run; check-input is requested with check_only=True, native_check=True.

Raises:

Type	Description
`ValueError`	unknown or malformed flag.

`check_job_name(job)` ¶

Return job if numgeo can use it as inp=/out= name, else raise :class:ValueError.

Allowed: letters, digits, _ and -, not starting with -, not a Windows device name. A . makes numgeo cut the name (.INP test, read_command_prompt_.f90:155-161), a path breaks the VTK output, blanks and shell characters break the unquoted rm -rf <out>-out (VTK_type.f90:1041-1048); a leading - would be read as an option of rm.

check_job_name("my job") # doctest: +ELLIPSIS Traceback (most recent call last): ... ValueError: job name 'my job' is not allowed: use letters, digits, '_' and '-' only ...

`locate_executable(executable=None)` ¶

Find the numgeo executable.

Order: the argument, the environment variable NUMGEO_EXE, then numgeo (numgeo.exe on Windows) on PATH. A name without a path in the argument or in NUMGEO_EXE is looked up on PATH.

Parameters:

Name	Type	Description	Default
`executable`	`str \| PathLike[str] \| None`	path or name of the executable.	`None`

Returns:

Type	Description
`Path`	Absolute path of an existing executable file.

Raises:

Type	Description
`ExecutableNotFoundError`	nothing found, or the given file does not exist or is not executable.

`classify(text, severity=None)` ¶

Find the message template that text was produced from.

Parameters:

Name	Type	Description	Default
`text`	`str`	message as written by numgeo (chunks joined; a leading `ERROR:` is ignored).	required
`severity`	`str \| None`	severity seen in the output (`error` / `warning` / `info`); templates of a compatible severity are preferred.	`None`

Returns:

Type	Description
`MessageMatch \| None`	The best match, or `None` if no template matches (see the module docstring for partial
`MessageMatch \| None`	matches).

`assess(workdir, job='job', deck=None, *, exit_code=None, flags=(), check_only=False, console=None)` ¶

Judge a numgeo job folder that has already run (e.g. started outside pynumgeo).

Without a deck, the step end times are not checked. Without exit_code, the exit status is not checked. Dump files ERROR_*_elem_*.sta count regardless of their age (the start time of the run is unknown).

Parameters:

Name	Type	Description	Default
`workdir`	`str \| PathLike[str]`	the job folder.	required
`job`	`str`	job name (`out=`).	`'job'`
`deck`	`Deck \| None`	the deck that was run (for the end time of each step).	`None`
`exit_code`	`int \| None`	exit status of numgeo, if known.	`None`
`flags`	`Sequence[str]`	command-line flags that were used (`oldjob=`, `no-sta`).	`()`
`check_only`	`bool`	judge as an input check (`INPUT_ACCEPTED`).	`False`
`console`	`str \| PathLike[str] \| None`	file with the console output (stdout and stderr); default `<job>.console.log` (written by :func:`pynumgeo.solver.run`), not read if missing.	`None`

`run(deck_or_path, workdir, job='job', executable=None, ncpus=1, timeout=None, check_only=False, flags=(), env=None, on_line=None, *, native_check=False, files=(), on_sta=None)` ¶

Run numgeo and judge the outcome.

Parameters:

Name	Type	Description	Default
`deck_or_path`	`Deck \| str \| PathLike[str]`	a :class:`~pynumgeo.deck.Deck` or the path of an input file (see module docstring).	required
`workdir`	`str \| PathLike[str]`	job folder (created if missing); numgeo's working directory.	required
`job`	`str`	job name, used as `inp=` and `out=` (letters, digits, `_`, `-`).	`'job'`
`executable`	`str \| PathLike[str] \| None`	the numgeo executable; default `NUMGEO_EXE`, then `numgeo` on `PATH` (:func:`~pynumgeo.solver.locate_executable`).	`None`
`ncpus`	`int`	number of threads (`ncpus=`; `OMP_NUM_THREADS` is set to the same value).	`1`
`timeout`	`float \| None`	seconds after which the process tree is killed (status `TIMEOUT`); `None`: no limit.	`None`
`check_only`	`bool`	only check the input: stop numgeo as soon as the `.log` shows `-> PREPROCESSING END` (input read and model database built, database.f90:1114) and report `INPUT_ACCEPTED` (or `FAILED` with the input errors). Errors of the remaining setup (constraints, embedded regions, output initialisation) are not reached.	`False`
`flags`	`Iterable[str]`	further numgeo flags (:data:`~pynumgeo.solver.executable.KNOWN_FLAGS`, `oldjob=<job>`, `assembly-partitions=<n>`).	`()`
`env`	`Mapping[str, str \| None] \| None`	environment variables for numgeo (`None` as value removes one). Precedence: `env` > `OMP_NUM_THREADS=<ncpus>` and `OMP_STACKSIZE=64M` (only if unset) > inherited environment; deviations are reported in `result.notes`.	`None`
`on_line`	`Callable[[str], None] \| None`	called with every console line (stdout and stderr) while numgeo runs.	`None`
`native_check`	`bool`	with `check_only`, also pass `check-input` so that an executable that knows the flag stops by itself after the input phase. An executable without it prints "Unknown input parameter" and starts the analysis; pynumgeo then stops it at the same point.	`False`
`files`	`Iterable[str \| PathLike[str]]`	further files copied into the job folder before the run (same base name).	`()`
`on_sta`	`Callable[[str], None] \| None`	called with every new line of `<job>.sta` (one line per increment attempt) while numgeo runs.	`None`

Returns:

Name	Type	Description
`The`	`RunResult`	class:`~pynumgeo.solver.RunResult`.

Raises:

Type	Description
`ValueError`	invalid job name, flag or `ncpus`.
`FileNotFoundError`	the input file, an include or one of `files` does not exist.
`ExecutableNotFoundError`	no numgeo executable.

Running numgeo¶

pynumgeo.solver ¶

ExecutableNotFoundError ¶

MessageMatch(message_id, file, line, routine, severity, terminates, candidates) dataclass ¶

RunFailedError(result) ¶

RunResult(status, reason, workdir, job, exit_code=None, duration=0.0, command=list(), steps=list(), messages=list(), files=list(), version=None, notes=list(), console_tail=list()) dataclass ¶

ok property ¶

log_path property ¶

sta_path property ¶

msg_path property ¶

console_path property ¶

errors property ¶

warnings property ¶

raise_for_status() ¶

summary() ¶

RunStatus ¶

SolverMessage(severity, text, origin, file=None, line=None, routine=None, message_id=None, candidates=(), rule_ids=(), phase=None, runtime=False, count=1) dataclass ¶

source property ¶

as_dict() ¶

StepReport(index, name, t_end, t_reached, increments, cutbacks, started, terminated, completed, iterations=None, procedure=None, skipped=False, note=None) dataclass ¶

as_dict() ¶

check_flags(flags) ¶

check_job_name(job) ¶

locate_executable(executable=None) ¶

classify(text, severity=None) ¶

assess(workdir, job='job', deck=None, *, exit_code=None, flags=(), check_only=False, console=None) ¶

run(deck_or_path, workdir, job='job', executable=None, ncpus=1, timeout=None, check_only=False, flags=(), env=None, on_line=None, *, native_check=False, files=(), on_sta=None) ¶

`pynumgeo.solver` ¶

`ExecutableNotFoundError` ¶

`MessageMatch(message_id, file, line, routine, severity, terminates, candidates)` `dataclass` ¶

`RunFailedError(result)` ¶

`RunResult(status, reason, workdir, job, exit_code=None, duration=0.0, command=list(), steps=list(), messages=list(), files=list(), version=None, notes=list(), console_tail=list())` `dataclass` ¶

`ok` `property` ¶

`log_path` `property` ¶

`sta_path` `property` ¶

`msg_path` `property` ¶

`console_path` `property` ¶

`errors` `property` ¶

`warnings` `property` ¶

`raise_for_status()` ¶

`summary()` ¶

`RunStatus` ¶

`SolverMessage(severity, text, origin, file=None, line=None, routine=None, message_id=None, candidates=(), rule_ids=(), phase=None, runtime=False, count=1)` `dataclass` ¶

`source` `property` ¶

`as_dict()` ¶

`StepReport(index, name, t_end, t_reached, increments, cutbacks, started, terminated, completed, iterations=None, procedure=None, skipped=False, note=None)` `dataclass` ¶

`as_dict()` ¶

`check_flags(flags)` ¶

`check_job_name(job)` ¶

`locate_executable(executable=None)` ¶

`classify(text, severity=None)` ¶

`assess(workdir, job='job', deck=None, *, exit_code=None, flags=(), check_only=False, console=None)` ¶

`run(deck_or_path, workdir, job='job', executable=None, ncpus=1, timeout=None, check_only=False, flags=(), env=None, on_line=None, *, native_check=False, files=(), on_sta=None)` ¶