uclchem.advanced.advanced_heating#

Heating and cooling mechanism configuration for UCLCHEM.

This module provides class-based interface for accessing and modifying the Fortran heating module that controls UCLCHEM’s heating and cooling mechanisms during execution.

Thread Safety Warning: HeatingSettings modifies global Fortran module state and is 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 HeatingSettings affect the global Fortran state and persist across model runs in the same Python session.

Module Contents#

Classes#

HeatingSettings

Class-based wrapper for UCLCHEM heating and cooling configuration.

Functions#

`auto_initialize_coolant_directory`(→ bool)	Automatically initialize the coolant data directory for the Fortran module.
`initialize_coolant_directory`(→ str)	Locate and return the collisional rate data directory.

Attributes#

logger

class uclchem.advanced.advanced_heating.HeatingSettings[source]#

Class-based wrapper for UCLCHEM heating and cooling configuration.

This class provides access to the heating and cooling mechanism controls, solver parameters, and computed values from heating.f90.

PHOTOELECTRIC[source]#

Photoelectric heating implementations - ‘BAKES’: Bakes & Tielens method (index 1) - ‘WEINGARTNER’: Weingartner method (index 2) (Only one can be enabled at a time)

Type:: dict

H2_FORMATION[source]#

Index for H2 formation heating (3)

Type:: int

H2_PHOTODISSOCIATION[source]#

Index for H2 photodissociation heating (4)

Type:: int

H2_FUV_PUMPING[source]#

Index for H2 FUV pumping heating (5)

Type:: int

CARBON_IONIZATION[source]#

Index for carbon ionization heating (6)

Type:: int

COSMIC_RAY[source]#

Index for cosmic ray heating (7)

Type:: int

TURBULENT[source]#

Index for turbulent heating (8)

Type:: int

GAS_GRAIN_COLLISIONS[source]#

Index for gas-grain collisional heating/cooling (9)

Type:: int

ATOMIC_LINE_COOLING[source]#

Index for atomic line cooling

Type:: int

H2_COLLISIONALLY_INDUCED[source]#

Index for H2 collisionally induced emission

Type:: int

COMPTON_COOLING[source]#

Index for Compton cooling

Type:: int

CONTINUUM_EMISSION[source]#

Index for continuum emission cooling

Type:: int

MOLECULAR_LINE_COOLING[source]#

Index for molecular line cooling

Type:: int

DUST_TEMP_HOCUK[source]#

Hocuk et al. 2017 dust temperature method

Type:: int

DUST_TEMP_HOLLENBACH[source]#

Hollenbach 1991 dust temperature method

Type:: int

COOLANT_WARM[source]#

Warm restart mode - initialize LTE, rescale on density change (default)

Type:: int

COOLANT_FORCE_LTE[source]#

Always reset to LTE before SE iteration (original behavior)

Type:: int

COOLANT_FORCE_GROUND[source]#

Always reset to ground state before SE iteration

Type:: int

Examples

>>> from uclchem.advanced import HeatingSettings
>>> settings = HeatingSettings()
>>> settings.print_configuration()
...
>>> # Switch photoelectric method (auto-disables Bakes when enabling Weingartner)
>>> settings.set_heating_mechanism(settings.PHOTOELECTRIC['WEINGARTNER'], True)
>>> # Disable H2 formation
>>> settings.set_heating_mechanism(settings.H2_FORMATION, False)

Initialize the HeatingSettings wrapper.

This connects to the Fortran heating module and provides access to its configuration parameters. Captures the current state as the default configuration for reset_to_defaults().

get_coolant_active() → dict[str, bool][source]#

Get the active state of all line coolant species.

Returns:: Dictionary mapping coolant names to their enabled state
Return type:: dict[str, bool]

Examples

>>> settings = HeatingSettings()
>>> state = settings.get_coolant_active()
>>> print(state)
{'H': True, 'C+': True, 'O': True, ...}

get_coolant_directory() → str[source]#

Get the current collisional rate data directory.

Returns:: Directory path as string (stripped of trailing spaces)
Return type:: str

get_coolant_restart_mode() → int[source]#

Get the current coolant population restart mode.

Returns:: Current restart mode (0=WARM, 1=FORCE_LTE, 2=FORCE_GROUND)
Return type:: int

get_cooling_modules() → dict[str, bool][source]#

Obtain the state (on/off) of all cooling mechanisms.

Returns:: Dictionary mapping mechanism names to their enabled state
Return type:: dict[str, bool]

Examples

>>> settings = HeatingSettings()
>>> state = settings.get_cooling_modules()
>>> print(state['AtomicLineEmission'])
True

get_dust_gas_coupling_method() → int[source]#

Get the current dust-gas temperature coupling method.

Returns:: Current method (1=Hocuk, 2=Hollenbach)
Return type:: int

get_heating_modules() → dict[str, bool][source]#

Obtain the state (on/off) of all heating mechanisms.

Returns:: Dictionary mapping mechanism names to their enabled state
Return type:: dict[str, bool]

Examples

>>> settings = HeatingSettings()
>>> state = settings.get_heating_modules()
>>> print(state['H2Formation'])
False

get_line_solver_attempts() → int[source]#

Get the current number of line cooling solver attempts.

Returns:: Number of solver attempts
Return type:: int

get_pah_abundance() → float[source]#

Get the current PAH abundance.

Returns:: PAH abundance
Return type:: float

print_configuration() → None[source]#

Print the current heating and cooling configuration.

Examples

>>> settings = HeatingSettings()
>>> settings.print_configuration()
...

reset_to_defaults() → None[source]#

Reset all heating and cooling mechanisms to their initial values.

Restores the configuration that was present when this HeatingSettings instance was first initialized. This allows reverting any changes made during the session back to the starting state.

Examples

>>> settings = HeatingSettings()
>>> settings.set_heating_mechanism(settings.H2_FORMATION, False)
>>> settings.reset_to_defaults()  # Restores original state

set_coolant_active(coolant_name: str, enabled: bool = True) → None[source]#

Enable or disable a specific line coolant species.

This controls individual coolant species within the molecular line cooling mechanism (cooling_modules index 5). When a coolant is disabled, its level population calculation is skipped entirely and its cooling contribution is set to zero.

Parameters:

coolant_name (str) – Name of the coolant species (e.g. “CO”, “C+”, “p-H2”). Use get_coolant_active() to see available names.
enabled (bool) – True to enable, False to disable. Default: True

Raises:

ValueError – If coolant_name is not found in the network.

Examples

>>> settings = HeatingSettings()
>>> settings.set_coolant_active("CO", False)
>>> settings.set_coolant_active("p-H2", False)

set_coolant_directory(directory: str | pathlib.Path) → None[source]#

Set the directory containing collisional rate data files.

This directory must contain the LAMDA-format collisional rate files (e.g., co.dat, o-h2.dat, etc.) used for molecular line cooling calculations.

Parameters:

directory (str | Path) – Path to directory containing LAMDA-format rate files. Must end with ‘/’. Max 255 characters.

Raises:

ValueError – If path is too long or doesn’t end with ‘/’
FileNotFoundError – If directory doesn’t exist

Examples

>>> settings = HeatingSettings()
>>> settings.set_coolant_directory("/custom/rates/")

set_coolant_restart_mode(mode: int) → None[source]#

Set the coolant population restart mode.

Parameters:

mode (int) – Restart mode (0=WARM, 1=FORCE_LTE, 2=FORCE_GROUND)

Raises:

ValueError – If mode is not one of [0, 1, 2].
AssertionError – If the mode could not be set in the Fortran module.

Examples

>>> settings = HeatingSettings()
>>> settings.set_coolant_restart_mode(settings.COOLANT_WARM)

set_cooling_mechanism(mechanism_id: int, enabled: bool = True) → None[source]#

Enable or disable a specific cooling mechanism.

Parameters:

mechanism_id (int) – Index of the cooling mechanism (1-5). Use class constants (e.g., self.ATOMIC_LINE_COOLING)
enabled (bool) – True to enable, False to disable. Default: True

Raises:

ValueError – If mechanism_id is not between 1 and the number of cooling mechanisms.

Examples

>>> settings = HeatingSettings()
>>> settings.set_cooling_mechanism(settings.MOLECULAR_LINE_COOLING, False)

set_dust_gas_coupling_method(method: int) → None[source]#

Set the dust-gas temperature coupling method.

Parameters:: method (int) – Coupling method to use: - 1 (DUST_TEMP_HOCUK): Hocuk et al. 2017 - 2 (DUST_TEMP_HOLLENBACH): Hollenbach 1991
Raises:: ValueError – If method is not one of [1, 2].

Examples

>>> settings = HeatingSettings()
>>> settings.set_dust_gas_coupling_method(settings.DUST_TEMP_HOLLENBACH)

set_heating_mechanism(mechanism_id: int, enabled: bool = True) → None[source]#

Enable or disable a specific heating mechanism.

For mechanisms with multiple implementations (like PHOTOELECTRIC), enabling one automatically disables others in the same group.

Parameters:

mechanism_id (int) – Index of the heating mechanism (1-9). Use class constants (e.g., self.PHOTOELECTRIC[‘BAKES’], self.H2_FORMATION)
enabled (bool) – True to enable, False to disable. Default: True

Raises:

ValueError – If mechanism_id is not between 1 and the number of heating mechanisms.

Examples

>>> settings = HeatingSettings()
>>> # Enable Weingartner photoelectric (auto-disables Bakes)
>>> settings.set_heating_mechanism(settings.PHOTOELECTRIC['WEINGARTNER'], True)
>>> # Or disable H2 formation
>>> settings.set_heating_mechanism(settings.H2_FORMATION, False)

set_line_solver_attempts(attempts: int) → None[source]#

Set the number of line cooling solver iterations.

The line cooling is computed multiple times and the median is used.

Parameters:: attempts (int) – Number of solver attempts (odd number recommended). Default is 5. Recommended range: 3-11.
Raises:: ValueError – If attempts is less than 1.

Examples

>>> settings = HeatingSettings()
>>> settings.set_line_solver_attempts(7)

set_pah_abundance(abundance: float) → None[source]#

Set the PAH (Polycyclic Aromatic Hydrocarbon) abundance.

Parameters:: abundance (float) – PAH abundance relative to hydrogen. Default: 6e-7
Raises:: ValueError – if abundance is smaller than 0

Examples

>>> settings = HeatingSettings()
>>> settings.set_pah_abundance(1e-6)

ATOMIC_LINE_COOLING = 1[source]#

CARBON_IONIZATION = 6[source]#

COMPTON_COOLING = 3[source]#

CONTINUUM_EMISSION = 4[source]#

COOLANT_FORCE_GROUND = 2[source]#

COOLANT_FORCE_LTE = 1[source]#

COOLANT_WARM = 0[source]#

COSMIC_RAY = 7[source]#

DUST_TEMP_HOCUK = 1[source]#

DUST_TEMP_HOLLENBACH = 2[source]#

GAS_GRAIN_COLLISIONS = 9[source]#

H2_COLLISIONALLY_INDUCED = 2[source]#

H2_FORMATION = 3[source]#

H2_FUV_PUMPING = 5[source]#

H2_PHOTODISSOCIATION = 4[source]#

MOLECULAR_LINE_COOLING = 5[source]#

PHOTOELECTRIC[source]#

TURBULENT = 8[source]#

uclchem.advanced.advanced_heating.auto_initialize_coolant_directory() → bool[source]#

Automatically initialize the coolant data directory for the Fortran module.

This is a convenience wrapper around initialize_coolant_directory() that: - Attempts to locate coolant data files - Sets the coolant directory in the Fortran module if found - Logs warnings instead of raising exceptions if initialization fails

This function is called automatically when the uclchem module is imported.

Returns:: True if initialization succeeded, False if it failed
Return type:: bool

Examples

>>> from uclchem.advanced.advanced_heating import auto_initialize_coolant_directory
>>> if auto_initialize_coolant_directory():
...     print("Coolant data initialized successfully")
...
Coolant data initialized successfully

uclchem.advanced.advanced_heating.initialize_coolant_directory() → str[source]#

Locate and return the collisional rate data directory.

This function searches for coolant data files in the following order: 1. UCLCHEM_COOLANT_DATA environment variable (if set) 2. Installed package data via importlib.resources (normal installation) 3. Development mode: Makerates/data/collisional_rates/ (relative to project root)

Returns:

Absolute path to the coolant data directory (with trailing slash)

Return type:

str

Raises:

RuntimeError – If the Fortran heating module is not available (not compiled)
FileNotFoundError – If coolant data directory cannot be found in any location

Examples

>>> from uclchem.advanced.advanced_heating import initialize_coolant_directory
>>> coolant_dir = initialize_coolant_directory()
>>> print(f"Coolant data at: {coolant_dir}")
Coolant data at: ...

uclchem.advanced.advanced_heating.logger[source]#