General options

General options#

pyCIF is run as a Python module through its __main__.py entry point. All options are passed on the command line; the YAML configuration file controls everything else.

To print a summary of available options at any time:

python -m pycif -h

Available options#

def_file#

(positional, mandatory)

Path to the YAML configuration file that defines the full simulation set-up — plugins, dates, working directory, tracers, and all tuning parameters. See Yaml configuration for the full reference.

python -m pycif path/to/my_config.yml
-h, --help#

(stand-alone)

Print the option summary and exit immediately. No simulation is started.

--debug#

(optional)

On an uncaught exception, print the full traceback and drop into an interactive ipdb post-mortem debugging session. This lets you inspect the live Python state (variables, call stack) at the point of the crash.

Equivalent to setting verbose: 0 in the YAML for log verbosity, but also activates the debugger. Requires ipdb (pip install ipdb).

python -m pycif my_config.yml --debug
--faulthandler#

(optional)

Enable Python’s built-in faulthandler module, which catches low-level OS signals (segmentation fault, bus error, etc.) and prints a Python-level traceback before the process terminates.

Useful when a compiled Fortran or C model executable crashes silently inside a subprocess call.

Warning

This option adds a small but measurable overhead to every Python frame transition. Use it for diagnosis, not in production runs.

python -m pycif my_config.yml --faulthandler
--monitor_memory#

(optional)

Enable memory-usage tracking inside the observation-operator transform loop. After each transform step, peak and current RSS (resident set size) are logged to the run log.

Helpful for identifying which transform is responsible for excessive memory growth in large runs.

python -m pycif my_config.yml --monitor_memory
--profiling [OUTPUT]#

(optional)

Profile the full run with pyinstrument and write a self-contained interactive HTML report to OUTPUT. When the run finishes the report is opened automatically in the default browser.

OUTPUT is resolved relative to the simulation working directory (workdir in the YAML). Defaults to profile.html when the flag is given without a filename.

Requires pyinstrument (pip install pyinstrument).

This option can also be set directly in the YAML configuration file, which is convenient for batch submissions where command-line arguments are harder to pass. The CLI flag takes priority over the YAML key if both are present. See Diagnostic and profiling options.

python -m pycif my_config.yml --profiling              # → workdir/profile.html
python -m pycif my_config.yml --profiling perf.html    # → workdir/perf.html
python -m pycif my_config.yml --profiling /tmp/p.html  # absolute path

Reading the pyinstrument report

The HTML report shows a call tree ordered by wall-clock time. Each row is one function; the bar on the right shows the fraction of total time spent inside that function and all functions it called.

Practical tips:

  • Start at the top. The widest bar is where most time goes. Drill down by clicking the triangle to expand child calls.

  • “Self time” vs “total time.” A function with high total but low self time is a passthrough — the real cost is in its children. A function with high self time is doing the actual work (or is blocked on I/O).

  • Filter noise. Click Hide runtime (top-right toggle) to collapse Python interpreter internals and focus on pyCIF code.

  • Timeline view. Switch to the Timeline tab to see how time is distributed across the run (useful when there are repeated calls with varying cost, e.g. per-period model runs).

  • Export / share. The HTML file is fully self-contained — copy it anywhere or attach it to an issue report without losing interactivity.

Tip

If a single transform or model call dominates the profile, consider enabling --monitor_memory at the same time: high memory pressure can cause apparent slowness through paging rather than CPU work.

--tracking EMAIL#

(optional)

Send a structured plain-text crash report to EMAIL whenever an uncaught exception terminates the run.

Warning

GDPR / data-privacy notice

By activating this option — whether on the command line or via the tracking YAML key — you explicitly consent to the collection and transmission of the following computation-environment information to the configured recipient address:

  • Your Unix username ($USER) and fully-qualified hostname.

  • The current working directory and the full command line (sys.argv), which may include file paths containing personal or project-specific information.

  • SLURM job metadata (job ID, job name, array task ID) if running inside a cluster job.

  • The path to the pyCIF YAML configuration file.

  • The Python traceback of the crash, which may reference source-file paths on your system.

No data is transmitted to any third party; the report is sent only to the address you supply, via your local SMTP relay. If you do not wish to share this information, simply omit the option.

Report format

The email subject encodes a short fingerprint derived from the exception type and crash location, making deduplication of repeated alerts easy:

[pyCIF-Error][a3f1bc02] CifRuntimeError: model executable returned 1

The body contains two mandatory sections and one optional section:

=== Environment ===

UTC timestamp, hostname, $USER, Python version, CWD, full command line (sys.argv), SLURM variables (SLURM_JOB_ID, SLURM_JOB_NAME, SLURM_ARRAY_TASK_ID — each shown as n/a when absent), and the path to the config file.

=== Traceback ===

Full formatted exception chain (__cause__ / __context__ aware), identical to what Python prints to stderr.

=== Last log lines === (only when the log buffer is attached)

The last N pyCIF log records (timestamps, level, logger name, message) recorded before the crash. This section is not present by default; it is enabled programmatically via pycif.utils.check.error_reporting.attach_log_buffer().

SMTP configuration

The report is delivered by unauthenticated SMTP (no TLS, no login). Host and port default to localhost:25 and can be overridden with environment variables:

Environment variable

Purpose

PYCIF_ERROR_SMTP_HOST

SMTP relay hostname (default: localhost)

PYCIF_ERROR_SMTP_PORT

SMTP relay port (default: 25)

The sender address defaults to {USER}@{hostname} and can be overridden programmatically via the Python API.

This option can also be set directly in the YAML configuration file, which is convenient for batch jobs. The CLI flag takes priority over the YAML key. See Diagnostic and profiling options.

Note

--tracking has no effect when --debug is also given: the ipdb post-mortem intercepts the exception before the crash hook fires.

python -m pycif my_config.yml --tracking oncall@example.org
PYCIF_ERROR_SMTP_HOST=smtp.lab.fr python -m pycif my_config.yml --tracking you@lab.fr
--strict_deprecations#

(optional)

Turn every DeprecationWarning and FutureWarning raised during the run into an exception (warnings.simplefilter() with action="error"), instead of Python’s default of merely printing them. The run then stops at the first soon-to-break API use instead of continuing silently.

Useful ahead of a dependency upgrade (numpy, xarray, dask, …) to proactively catch breaking changes rather than discovering them after the upgrade.

python -m pycif my_config.yml --strict_deprecations