uclchem.advanced.advanced_settings
==================================

.. py:module:: uclchem.advanced.advanced_settings

.. autoapi-nested-parse::

   General settings interface for UCLCHEM Fortran modules.

   This module provides class-based interfaces for accessing and modifying runtime
   settings across all UCLCHEM Fortran modules:

   - Setting: Represents a single setting with metadata and edit tracking
   - ModuleSettings: Container for all settings in a Fortran module
   - GeneralSettings: Top-level interface to all modules

   **Thread Safety Warning:**
   All classes in this module modify global Fortran module state and are **NOT thread-safe**.
   Do not use with multiprocessing, multithreading, or concurrent model runs.
   Settings should only be modified during initialization, before running models.

   Note: Changes made through these classes affect the global Fortran state and persist
   across model runs in the same Python session.



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

Classes
~~~~~~~

.. autoapisummary::

   uclchem.advanced.advanced_settings.GeneralSettings
   uclchem.advanced.advanced_settings.ModuleSettings
   uclchem.advanced.advanced_settings.Setting




Attributes
~~~~~~~~~~

.. autoapisummary::

   uclchem.advanced.advanced_settings.logger


.. py:class:: GeneralSettings

   General interface to all UCLCHEM settings across all Fortran modules.

   Provides dynamic access to modifiable parameters in any uclchemwrap module,
   with automatic detection of read-only PARAMETERs and internal solver settings.

   Each setting is represented by a Setting object that tracks:
   - Current value (with caching)
   - Edit status
   - Default value
   - Metadata (dtype, shape, flags)

   **Thread Safety Warning:**
       This class modifies global Fortran module state and is **NOT thread-safe**.
       Do not use with multiprocessing or concurrent model runs. Settings should
       only be modified during initialization, before running models.

   Usage:
       >>> from uclchem.advanced.advanced_settings import GeneralSettings
       >>> settings = GeneralSettings()
       >>>
       >>> # Access a setting
       >>> setting = settings.defaultparameters.initialdens
       >>> print(setting.get())
       100.0
       >>>
       >>> # Modify a setting
       >>> setting.set(500.0)
       >>>
       >>> # Get the modified value
       >>> print(setting.get())
       500.0
       >>>
       >>> # Or use attribute-style syntax
       >>> settings.defaultparameters.initialdens = 500.0
       >>>
       >>> # List all settings in a module
       >>> settings.defaultparameters.print_settings() # doctest: +SKIP
       ...
       >>>
       >>> # Use context manager for temporary changes
       >>> with settings.temporary_changes():
       ...     settings.defaultparameters.initialdens = 1000.0
       ...     print(setting.get())
       ...     # Run model with modified settings
       ...
       1000.0
       >>> # Settings automatically restored after context
       >>> print(setting.get())
       500.0
       >>> # As well as in the GeneralSettings instance
       >>> print(settings.defaultparameters.initialdens)
       Setting(defaultparameters.initialdens = 500.0 [EDITED])
       >>>
       >>> # Reset to the original value
       >>> setting.set(100.0)


   Initialize with all available uclchemwrap modules.


   .. py:method:: list_modules() -> None

      List all available modules with statistics.



   .. py:method:: print_all_edited() -> None

      Print all settings that have been modified from defaults.



   .. py:method:: print_all_settings() -> None

      Print all settings across all modules.



   .. py:method:: reset_all(confirm: bool = True) -> None

      Reset all settings to their default values.

      :param confirm: If True, require user confirmation. Default = True.
      :type confirm: bool



   .. py:method:: search(pattern: str, include_internal: bool = False, include_parameters: bool = False) -> dict[str, Setting]

      Search for settings matching a pattern across all modules.

      :param pattern: String pattern to search for (case-insensitive).
      :type pattern: str
      :param include_internal: Include internal solver parameters. Default = False.
      :type include_internal: bool
      :param include_parameters: Include read-only PARAMETERs. Default = False.
      :type include_parameters: bool

      :returns: Dict mapping "module.setting" to Setting objects
      :rtype: dict[str, Setting]



   .. py:method:: temporary_changes() -> collections.abc.Iterator[GeneralSettings]

      Context manager for temporary setting modifications.

      Saves current state on entry and restores it on exit, even if an
      exception occurs. Useful for running models with temporary parameter
      changes without affecting the global state.

      :Yields: **self** (*GeneralSettings*) -- The GeneralSettings instance for chaining

      .. rubric:: Examples

      >>> settings = GeneralSettings()
      >>> settings.defaultparameters.initialdens = 100.0
      >>> print(settings.defaultparameters.initialdens.get())
      100.0
      >>>
      >>> with settings.temporary_changes():
      ...     settings.defaultparameters.initialdens = 5000.0
      ...     print(settings.defaultparameters.initialdens.get())
      ...     # Run model here
      ...
      5000.0
      >>>
      >>> print(settings.defaultparameters.initialdens.get())
      100.0



.. py:class:: ModuleSettings(module_name: str, fortran_module: types.ModuleType, parameter_names: set[str], internal_names: set[str], file_path_names: set[str])

   Container for all settings from a single Fortran module.

   Provides dict-like access to Setting objects with attribute-style syntax.


   Initialize settings for a module.

   :param module_name: Name of the Fortran module
   :type module_name: str
   :param fortran_module: Reference to the actual Fortran module
   :type fortran_module: ModuleType
   :param parameter_names: Set of names that are PARAMETERs
   :type parameter_names: set[str]
   :param internal_names: Set of names that are internal solver parameters
   :type internal_names: set[str]
   :param file_path_names: Set of names that are file paths (should use param_dict)
   :type file_path_names: set[str]


   .. py:method:: list_settings(include_internal: bool = False, include_parameters: bool = False) -> dict[str, Setting]

      List settings with their current values.

      :param include_internal: Include internal solver parameters. Default = False.
      :type include_internal: bool
      :param include_parameters: Include read-only PARAMETERs. Default = False.
      :type include_parameters: bool

      :returns: Dict mapping setting names to Setting objects
      :rtype: dict[str, Setting]



   .. py:method:: print_settings(include_internal: bool = False, include_parameters: bool = False) -> None

      Print all settings in a readable format.

      :param include_internal: Include internal solver parameters. Default = False.
      :type include_internal: bool
      :param include_parameters: Include read-only PARAMETERs. Default = False.
      :type include_parameters: bool



   .. py:attribute:: module_name


.. py:class:: Setting(name: str, module_name: str, fortran_module: types.ModuleType, is_parameter: bool = False, is_internal: bool = False, is_file_path: bool = False)

   Represents a single runtime setting from a Fortran module.

   Tracks the current value, edit status, default value, and metadata
   for a Fortran module variable.

   .. attribute:: name

      Setting name

      :type: str

   .. attribute:: module_name

      Parent Fortran module name

      :type: str

   .. attribute:: current_value

      Current value (cached on last read)

      :type: Any

   .. attribute:: is_edited

      Whether value has been modified from default

      :type: bool

   .. attribute:: default_value

      Original default value at initialization

      :type: bool

   .. attribute:: dtype

      NumPy dtype or Python type

      :type: npt.DTypeLike

   .. attribute:: is_parameter

      True if this is a compile-time constant (read-only)

      :type: bool

   .. attribute:: is_internal

      True if this is an internal solver parameter

      :type: bool

   .. attribute:: is_file_path

      True if this is a file path (should use param_dict)

      :type: bool

   .. attribute:: shape

      Array shape (None for scalars)

      :type: tuple[int, int] | None

   Initialize a Setting object.

   :param name: Setting name
   :type name: str
   :param module_name: Parent module name
   :type module_name: str
   :param fortran_module: Reference to the Fortran module
   :type fortran_module: ModuleType
   :param is_parameter: Whether this is a PARAMETER (read-only). Default = False.
   :type is_parameter: bool
   :param is_internal: Whether this is an internal solver parameter. Default = False.
   :type is_internal: bool
   :param is_file_path: Whether this is a file path parameter (should use param_dict).
                        Default = False.
   :type is_file_path: bool


   .. py:method:: get(check_memory: bool = True) -> float | int | numpy.ndarray

      Get the current value of the setting.

      :param check_memory: If True, compare cached value with actual Fortran memory
                           and warn if they differ. Default = True.
      :type check_memory: bool

      :returns: Current value from Fortran memory
      :rtype: float | int | np.ndarray



   .. py:method:: reset() -> None

      Reset the setting to its default value.

      :raises RuntimeError: If the setting is a Fortran parameter



   .. py:method:: set(value: float | int | numpy.ndarray) -> None

      Set the value of the setting.

      :param value: New value to set
      :type value: float | int | np.ndarray

      :raises RuntimeError: If attempting to modify a PARAMETER or file path parameter



   .. py:attribute:: current_value


   .. py:attribute:: default_value


   .. py:attribute:: is_edited
      :value: False



   .. py:attribute:: is_file_path
      :value: False



   .. py:attribute:: is_internal
      :value: False



   .. py:attribute:: is_parameter
      :value: False



   .. py:attribute:: module_name


   .. py:attribute:: name


.. py:data:: logger