########################### 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: .. code-block:: bash python -m pycif -h .. _general-options-ref: Available options =================== .. option:: 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 :doc:`/documentation/yaml/index` for the full reference. .. code-block:: bash python -m pycif path/to/my_config.yml .. option:: -h, --help *(stand-alone)* Print the option summary and exit immediately. No simulation is started. .. option:: --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``). .. code-block:: bash python -m pycif my_config.yml --debug .. option:: --faulthandler *(optional)* Enable Python's built-in :mod:`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. .. code-block:: bash python -m pycif my_config.yml --faulthandler .. option:: --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. .. code-block:: bash python -m pycif my_config.yml --monitor_memory .. option:: --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 :ref:`yaml-diagnostic-options`. .. code-block:: bash 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 .. rubric:: 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. .. option:: --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. .. rubric:: Report format The email subject encodes a short fingerprint derived from the exception type and crash location, making deduplication of repeated alerts easy: .. code-block:: text [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()``. .. rubric:: 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: .. list-table:: :header-rows: 1 :widths: 35 65 * - 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 :ref:`yaml-diagnostic-options`. .. note:: ``--tracking`` has no effect when ``--debug`` is also given: the ``ipdb`` post-mortem intercepts the exception before the crash hook fires. .. code-block:: bash 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 .. option:: --strict_deprecations *(optional)* Turn every :class:`DeprecationWarning` and :class:`FutureWarning` raised during the run into an exception (:func:`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. .. code-block:: bash python -m pycif my_config.yml --strict_deprecations