uclchem.advanced.worker_state
=============================

.. py:module:: uclchem.advanced.worker_state

.. autoapi-nested-parse::

   Snapshot and restore of advanced settings for multiprocessing propagation.

   When UCLCHEM runs grid models or managed-mode models, worker processes are
   spawned via ``mp.Pool`` or ``mp.Process`` with the ``spawn`` context.  These
   fresh processes import ``uclchemwrap`` from scratch, losing any runtime
   modifications made through ``GeneralSettings``, ``HeatingSettings``, or
   ``NetworkState``.

   This module provides :func:`create_snapshot` / :func:`restore_snapshot` to
   capture the current Fortran module state into a picklable dict and re-apply
   it in a worker process before the model runs.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   uclchem.advanced.worker_state.create_snapshot
   uclchem.advanced.worker_state.restore_snapshot



Attributes
~~~~~~~~~~

.. autoapisummary::

   uclchem.advanced.worker_state.logger


.. py:function:: create_snapshot() -> dict[str, Any]

   Capture the current Fortran module state into a picklable dict.

   Reads directly from Fortran memory (not cached Python values) to ensure
   accuracy even when settings were modified outside the wrapper classes.

   The returned dict has three sections:

   * ``"general"`` – scalar settings from all uclchemwrap sub-modules
     (excluding PARAMETERs, INTERNAL, FILE_PATH, and arrays).
   * ``"heating"`` – heating/cooling boolean arrays, scalars, and coolant
     configuration.
   * ``"network"`` – Everything in :data:`_NETWORK_ARRAYS_TO_TAKE_SNAPSHOT_OF`.

   :returns: Fully picklable dict suitable for passing to :func:`restore_snapshot`.
   :rtype: dict[str, Any]


.. py:function:: restore_snapshot(snapshot: dict[str, Any]) -> None

   Apply a previously captured snapshot to the current process.

   Must be called **before** running any model in the worker process.

   :param snapshot: Dict produced by :func:`create_snapshot`.
   :type snapshot: dict[str, Any]


.. py:data:: logger