uclchem.advanced.advanced_settings#

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#

`GeneralSettings`	General interface to all UCLCHEM settings across all Fortran modules.
`ModuleSettings`	Container for all settings from a single Fortran module.
`Setting`	Represents a single runtime setting from a Fortran module.

Attributes#

logger

class uclchem.advanced.advanced_settings.GeneralSettings[source]#

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()
...
>>>
>>> # 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.

list_modules() → None[source]#: List all available modules with statistics.

print_all_edited() → None[source]#: Print all settings that have been modified from defaults.

print_all_settings() → None[source]#: Print all settings across all modules.

reset_all(confirm: bool = True) → None[source]#

Reset all settings to their default values.

Parameters:: confirm (bool) – If True, require user confirmation. Default = True.

search(pattern: str, include_internal: bool = False, include_parameters: bool = False) → dict[str, Setting][source]#

Search for settings matching a pattern across all modules.

Parameters:

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

Returns:

Dict mapping “module.setting” to Setting objects

Return type:

dict[str, Setting]

temporary_changes() → collections.abc.Iterator[GeneralSettings][source]#

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

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

class uclchem.advanced.advanced_settings.ModuleSettings(module_name: str, fortran_module: types.ModuleType, parameter_names: set[str], internal_names: set[str], file_path_names: set[str])[source]#

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.

Parameters:

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

list_settings(include_internal: bool = False, include_parameters: bool = False) → dict[str, Setting][source]#

List settings with their current values.

Parameters:

include_internal (bool) – Include internal solver parameters. Default = False.
include_parameters (bool) – Include read-only PARAMETERs. Default = False.

Returns:

Dict mapping setting names to Setting objects

Return type:

dict[str, Setting]

print_settings(include_internal: bool = False, include_parameters: bool = False) → None[source]#

Print all settings in a readable format.

Parameters:

include_internal (bool) – Include internal solver parameters. Default = False.
include_parameters (bool) – Include read-only PARAMETERs. Default = False.

module_name[source]#

class uclchem.advanced.advanced_settings.Setting(name: str, module_name: str, fortran_module: types.ModuleType, is_parameter: bool = False, is_internal: bool = False, is_file_path: bool = False)[source]#

Represents a single runtime setting from a Fortran module.

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

name[source]#

Setting name

Type:: str

module_name[source]#

Parent Fortran module name

Type:: str

current_value[source]#

Current value (cached on last read)

Type:: Any

is_edited[source]#

Whether value has been modified from default

Type:: bool

default_value[source]#

Original default value at initialization

Type:: bool

dtype#

NumPy dtype or Python type

Type:: npt.DTypeLike

is_parameter[source]#

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

Type:: bool

is_internal[source]#

True if this is an internal solver parameter

Type:: bool

is_file_path[source]#

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

Type:: bool

shape#

Array shape (None for scalars)

Type:: tuple[int, int] | None

Initialize a Setting object.

Parameters:

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

get(check_memory: bool = True) → float | int | numpy.ndarray[source]#

Get the current value of the setting.

Parameters:: check_memory (bool) – If True, compare cached value with actual Fortran memory and warn if they differ. Default = True.
Returns:: Current value from Fortran memory
Return type:: float | int | np.ndarray

reset() → None[source]#

Reset the setting to its default value.

Raises:: RuntimeError – If the setting is a Fortran parameter

set(value: float | int | numpy.ndarray) → None[source]#

Set the value of the setting.

Parameters:: value (float | int | np.ndarray) – New value to set
Raises:: RuntimeError – If attempting to modify a PARAMETER or file path parameter

current_value[source]#

default_value[source]#

is_edited = False[source]#

is_file_path = False[source]#

is_internal = False[source]#

is_parameter = False[source]#

module_name[source]#

name[source]#

uclchem.advanced.advanced_settings.logger[source]#