uclchem.makerates.io_functions#

Functions to read in the species and reaction files and write output files.

Module Contents#

Functions#

array_to_string(→ str)

Write an array to fortran source code.

build_ode_string(→ str)

Build the ODE string.

check_reaction(→ bool)

Check a row parsed from a reaction file and checks it only contains acceptable things.

copy_coolant_files(→ None)

Copy coolant data files to the package data directory for installation.

find_reactant(→ int)

Try to find a reactant in the species list.

get_default_coolant_directory(→ str)

Get the collisional rates directory path for use during makerates.

get_default_coolants(→ list[dict[str, str]])

Get the default coolant configuration for UCLCHEM.

get_desorption_freeze_partners(→ list[int])

Every desorption has a corresponding freeze out eg desorption of #CO and freeze of CO.

kida_parser(→ list[list[str | int | float]])

Parse rows of a KIDA file.

output_drops(→ None)

Write the reactions that are dropped to disk/logs.

read_coolants_file(→ list[dict])

Read a YAML file specifying coolants.

read_grain_assisted_recombination_file(→ dict[str, ...)

Read a grain assisted recombination file.

read_reaction_file(...)

Read in a reaction file of any kind (UCL, UMIST, KIDA), and.

read_species_file(...)

Read in a Makerates species file.

replace_value_with_name(→ str)

Replace all instances of value with a string replace_string.

species_ode_string(→ str)

Build the string of Fortran code for a species once it's loss and gains.

strip_comments_from_row(→ list[str])

Strip comments from a separated line.

truncate_line(→ str)

Take a string and adds line endings at regular intervals.

write_evap_lists(→ int)

Write evaporation list to network file.

write_f90_constants(→ None)

Write the physical reactions to the f2py_constants.f90 file after every.

write_jacobian(→ None)

Write jacobian in Modern Fortran. This has never improved UCLCHEM's speed.

write_network_file(→ None)

Write the Fortran code file that contains all network information for UCLCHEM.

write_odes_f90(→ None)

Write the ODEs in Modern Fortran. This is an actual code file.

write_outputs(→ None)

Write the ODE and Network fortran source files to the fortran source.

write_python_constants(→ None)

Write the python constants to the constants.py file (deprecated).

write_reactions(→ None)

Write the human readable reaction file.

write_species(→ None)

Write the human readable species file. Note UCLCHEM doesn't use this file.

Attributes#

FORTRAN_LINE_LENGTH

logger

uclchem.makerates.io_functions.array_to_string(name: str, array: list | numpy.ndarray, type: str = 'int', parameter: bool = True) → str[source]#

Write an array to fortran source code.

Parameters:

  • name (str) – Variable name of array in Fortran

  • array (list | np.ndarray) – List of values of array

  • type (str) – The array’s type. Must be one of “int”, “float”, “string” or “logical”. Defaults to “int”.

  • parameter (bool) – Whether the array is a Fortran PARAMETER (constant). Defaults to True.

Returns:

outString – String containing the Fortran code to declare this array.

Return type:

str

Raises:

ValueError – Raises an error if type isn’t “int”, “float”, “string” or “logical”.

uclchem.makerates.io_functions.build_ode_string(species_list: list[uclchem.makerates.species.Species], reaction_list: list[uclchem.makerates.reaction.Reaction], enable_rates_storage: bool = False) → str[source]#

Build the ODE string.

A long, complex function that does the messy work of creating the actual ODE code to calculate the rate of change of each species. Test any change to this code thoroughly because ODE mistakes are very hard to spot.

Parameters:

  • species_list (list[Species]) – List of species in network

  • reaction_list (list[Reaction]) – List of reactions in network

  • enable_rates_storage (bool) – Enable the writing of the rates to the disk. Default = False.

Returns:

ode_string – One long string containing the entire ODE fortran code.

Return type:

str

uclchem.makerates.io_functions.check_reaction(reaction_row: list[Any], keep_list: list[str]) → bool[source]#

Check a row parsed from a reaction file and checks it only contains acceptable things.

It checks if all species in the reaction are present, and adds the temperature range is none is specified.

Parameters:

  • reaction_row (list[Any]) – List parsed from a reaction file and formatted to be able to called Reaction(reaction_row)

  • keep_list (list[str]) – list of species strings that are acceptable in the reactant or product bits of row

Returns:

Whether the row contains acceptable entries.

Return type:

bool

Raises:

ValueError – If custom desorb or freeze reactions contain species not in the species list.

uclchem.makerates.io_functions.copy_coolant_files(source_dir: str | pathlib.Path | None = None) → None[source]#

Copy coolant data files to the package data directory for installation.

This function copies .dat files from the source coolant directory (typically Makerates/data/collisional_rates/) to src/uclchem/data/collisional_rates/ so they can be installed with the package via meson.

Parameters:

source_dir (str | Path | None) – Optional source directory. If None, uses get_default_coolant_directory(). Default = None.

Raises:

FileNotFoundError – If source directory doesn’t exist or contains no .dat files.

uclchem.makerates.io_functions.find_reactant(species_list: list[str], reactant: str) → int[source]#

Try to find a reactant in the species list.

Parameters:

  • species_list (list[str]) – A list of species in the network

  • reactant (str) – The reactant to be indexed

Returns:

The index of the reactant, if it is not found, 9999

Return type:

int

uclchem.makerates.io_functions.get_default_coolant_directory(user_specified: str | pathlib.Path = '') → str[source]#

Get the collisional rates directory path for use during makerates.

Parameters:

user_specified (str | Path) – User-specified directory from config. If empty, searches standard locations relative to CWD. (Default value = ‘’)

Returns:

Absolute directory path to collisional rate data files.

Return type:

str

uclchem.makerates.io_functions.get_default_coolants() → list[dict[str, str]][source]#

Get the default coolant configuration for UCLCHEM.

Returns:

List of coolant dictionaries with ‘file’ and ‘name’ keys.

Return type:

list[dict[str, str]]

uclchem.makerates.io_functions.get_desorption_freeze_partners(reaction_list: list[uclchem.makerates.reaction.Reaction]) → list[int][source]#

Every desorption has a corresponding freeze out eg desorption of #CO and freeze of CO.

This find the corresponding freeze out for every desorb so that when desorb>>freeze we can turn off freeze out in UCLCHEM.

Parameters:

reaction_list (list[Reaction]) – Reactions in network

Returns:

partners – list of indices of freeze out reactions matching order of desorptions.

Return type:

list[int]

uclchem.makerates.io_functions.kida_parser(kida_file: str | pathlib.Path) → list[list[str | int | float]][source]#

Parse rows of a KIDA file.

KIDA used a fixed format file so we read each line in the chunks they specify and use python built in classes to convert to the necessary types. NOTE KIDA defines some of the same reaction types to UMIST but with different names and coefficients. We fix that by converting them here.

Parameters:

kida_file (str | Path) – path to KIDA file

Returns:

rows (list[list[Any]])

Return type:

list[list[str | int | float]]

uclchem.makerates.io_functions.output_drops(dropped_reactions: list[list[str]], output_dir: str | pathlib.Path | None = None, write_files: bool = True) → None[source]#

Write the reactions that are dropped to disk/logs.

Parameters:

  • dropped_reactions (list[list[str]]) – The reactions that were dropped

  • output_dir (str | Path | None) – The directory that dropped_reactions.csv will be written to. Default = None (writes to current directory).

  • write_files (bool) – Whether or not to write the file. Defaults to True.

uclchem.makerates.io_functions.read_coolants_file(file_name: str | pathlib.Path) → list[dict][source]#

Read a YAML file specifying coolants.

The file should contain either a single mapping or a list of mappings where each mapping contains ‘file’ and ‘name’ keys. ‘file’ must be a bare filename (no path).

Parameters:

file_name (str | Path) – Path to coolants file.

Returns:

Normalized list of coolant dicts.

Return type:

list[dict]

Raises:

  • ValueError – If the yaml-parsed data is not a dictionary, or list of dictionaries.

  • ValueError – If the “file” entries in coolants_file are not bare filenames.

uclchem.makerates.io_functions.read_grain_assisted_recombination_file(file_name: str | pathlib.Path) → dict[str, numpy.ndarray][source]#

Read a grain assisted recombination file.

Parameters:

file_name (str | Path) – file path of grain assisted recombination data

Returns:

gar_parameters – Database for grain-activated recombination reactions.

Return type:

dict[str, np.ndarray]

uclchem.makerates.io_functions.read_reaction_file(file_name: str | pathlib.Path, species_list: list[uclchem.makerates.species.Species], ftype: Literal['UMIST', 'KIDA', 'UCL']) → tuple[list[uclchem.makerates.reaction.Reaction], list[list[str]]][source]#

Read in a reaction file of any kind (UCL, UMIST, KIDA), and.

produces a list of reactions for the network, filtered by species_list.

Parameters:

  • file_name (str | Path) – A file name for the reaction file to read.

  • species_list (list[Species]) – A list of chemical species to be used in the reading.

  • ftype (Literal['UMIST', 'KIDA', 'UCL']) – ‘UMIST’,’UCL’, or ‘KIDA’ to describe format of file_name

Returns:

  • reactions (list[Reaction]) – List of kept reactions.

  • dropped_reactions (list[list[str]]) – List of raw CSV rows for dropped reactions.

Raises:

ValueError – If reaction file type is not one of [“UMIST”, “UCL”, “KIDA”].

uclchem.makerates.io_functions.read_species_file(file_name: str | pathlib.Path) → tuple[list[uclchem.makerates.species.Species], list[uclchem.makerates.species.Species]][source]#

Read in a Makerates species file.

Parameters:

file_name (str | Path) – path to file containing the species list

Returns:

  • species_list (list[Species]) – List of Species objects

  • user_defined_bulk (list[Species]) – List of user defined bulk species

Raises:

IndexError – If there is an error parsing a line in the file.

uclchem.makerates.io_functions.replace_value_with_name(string: str, value: int | float, replace_string: str, truncate: bool = True) → str[source]#

Replace all instances of value with a string replace_string.

Uses func:array_to_string to determine how value would be formatted as a string.

Parameters:

  • string (str) – string to reformat

  • value (int | float) – value to replace

  • replace_string (str) – string to put instead of value

  • truncate (bool) – Whether to truncate the line using func:truncate_line. Default = True.

Returns:

replaced_string – string with value replaced.

Return type:

str

Raises:

TypeError – If value is not an instance of int or float.

Examples

>>> replace_value_with_name("(/0,1,2/)", 2, "X")
'(/0,1,X/)'

>>> replace_value_with_name("(/0.0000e+00,1.0000e+00,2.0000e+00/)", 2.0, "X")
'(/0.0000e+00,1.0000e+00,X/)'

>>> # Replaces all instances of 'value'
>>> replace_value_with_name("(/0.0000e+00,1.0000e+00,2.0000e+00,1.0000e+00/)", 1.0, "X")
'(/0.0000e+00,X,2.0000e+00,X/)'
uclchem.makerates.io_functions.species_ode_string(n: int, species: uclchem.makerates.species.Species) → str[source]#

Build the string of Fortran code for a species once it’s loss and gains.

strings have been produced.

Parameters:

  • n (int) – Index of species in python format

  • species (Species) – species object

Returns:

the fortran code for the rate of change of the species

Return type:

str

uclchem.makerates.io_functions.strip_comments_from_row(row: list[str], comment_char: str = '!') → list[str][source]#

Strip comments from a separated line.

Parameters:

  • row (list[str]) – List of strings.

  • comment_char (str) – Character indicating the beginning of a comment. Default = “!”.

Returns:

row – List of strings, with the final string adjusted by removing everything after comment_char (and any whitespace).

Return type:

list[str]

uclchem.makerates.io_functions.truncate_line(input_string: str, line_length: int = 72) → str[source]#

Take a string and adds line endings at regular intervals.

Keeps us from overshooting fortran’s line limits and, frankly, makes for nicer ode.f90 even if human readability isn’t very important

Parameters:

  • input_string (str) – Line of code to be truncated

  • line_length (int) – rough line length. Default = 72.

Returns:

result – Code string with line endings at regular intervals

Return type:

str

uclchem.makerates.io_functions.write_evap_lists(network_file: IO[str], species_list: list[uclchem.makerates.species.Species]) → int[source]#

Write evaporation list to network file.

Two phase networks mimic episodic thermal desorption seen in lab (see Viti et al. 2004) by desorbing fixed fractions of material at specific temperatures. Three phase networks just use binding energy and that fact we set binding energies in bulk to water by default. This function writes all necessary arrays to the network file so these processes work.

Parameters:

  • network_file (IO[str]) – Open file handle to which the network code is being written

  • species_list (list[Species]) – List of species in network

Returns:

number of ice species

Return type:

int

Raises:

NameError – If a species desorbs as another species that is not in the species list.

uclchem.makerates.io_functions.write_f90_constants(replace_dict: dict[str, Any], output_file_name: pathlib.Path, template_file_path: str | pathlib.Path = 'fortran_templates') → None[source]#

Write the physical reactions to the f2py_constants.f90 file after every.

run of makerates, this ensures the Fortran and Python bits are compatible.

Parameters:

  • replace_dict (dict[str, Any]) – The dictionary with keys to replace

  • output_file_name (Path) – The path to target f2py_constants.f90 file

  • template_file_path (str | Path) – The file to use as the template. (Default value = ‘fortran_templates’)

uclchem.makerates.io_functions.write_jacobian(file_name: pathlib.Path, species_list: list[uclchem.makerates.species.Species]) → None[source]#

Write jacobian in Modern Fortran. This has never improved UCLCHEM’s speed.

and so is not used in the code as it stands. Current only works for three phase model.

Parameters:

  • file_name (Path) – Path to jacobian file

  • species_list (list[Species]) – List of species AFTER being processed by build_ode_string

uclchem.makerates.io_functions.write_network_file(file_name: pathlib.Path, network: uclchem.makerates.network.Network, enable_rates_storage: bool = False, gar_database: dict[str, numpy.ndarray] | None = None) → None[source]#

Write the Fortran code file that contains all network information for UCLCHEM.

This includes lists of reactants, products, binding energies, formationEnthalpies and so on.

Parameters:

  • file_name (Path) – The file name where the code will be written.

  • network (Network) – A Network object built from lists of species and reactions.

  • enable_rates_storage (bool) – Enable storage of writing rates to files. Default = False.

  • gar_database (dict[str, np.ndarray] | None) – Database for grain-activated recombination reactions. Default = None.

Raises:

AssertionError – If exothermicity is non-zero but enable_rates_storage is False.

uclchem.makerates.io_functions.write_odes_f90(file_name: pathlib.Path, species_list: list[uclchem.makerates.species.Species], reaction_list: list[uclchem.makerates.reaction.Reaction], enable_rates_storage: bool = False) → None[source]#

Write the ODEs in Modern Fortran. This is an actual code file.

Parameters:

  • file_name (Path) – Path to file where code will be written

  • species_list (list[Species]) – List of species describing network

  • reaction_list (list[Reaction]) – List of reactions describing network

  • enable_rates_storage (bool) – Enable storage of writing rates to files. Default = False.

uclchem.makerates.io_functions.write_outputs(network: uclchem.makerates.network.Network, python_src_dir: pathlib.Path, fortran_src_dir: pathlib.Path, enable_rates_storage: bool = False, gar_database: dict[str, numpy.ndarray] | None = None, coolants: list[dict] | None = None, coolant_data_dir: str | pathlib.Path | None = '') → None[source]#

Write the ODE and Network fortran source files to the fortran source.

Parameters:

  • network (Network) – The makerates Network class

  • python_src_dir (Path) – Directory to write Python source files (species.csv, reactions.csv).

  • fortran_src_dir (Path) – Directory to write Fortran source files (odes.f90, network.f90, f2py_constants.f90).

  • enable_rates_storage (bool) – Enable storage of writing rates to files. Default = False.

  • gar_database (dict[str, np.ndarray] | None) – Database for grain-activated recombination reactions. Default = None.

  • coolants (list[dict] | None) – List of coolants or None. If None, use default list of coolants. See get_default_coolants().

  • coolant_data_dir (str | Path | None) – User-specified directory from config. If empty, searches standard locations relative to CWD. (Default value = ‘’)

Raises:

  • ValueError – If coolants entries do not have a key “file” or the file names are not bare file names.

  • ValueError – If coolants start with “o-” or “p-” for ortho and para, but no conversion_factor is given in the dictionary.

  • ValueError – If coolants have parent species specified that are not in the network.

uclchem.makerates.io_functions.write_python_constants(replace_dict: dict[str, int], python_constants_file: pathlib.Path) → None[source]#

Write the python constants to the constants.py file (deprecated).

As of the latest version, constants.py reads directly from the f2py_constants module, so this function is no longer needed. It’s kept for backward compatibility but does nothing.

Parameters:

  • replace_dict (dict[str, int]) – Dict with keys to replace and their values (ignored)

  • python_constants_file (Path) – Path to the target constant files (ignored)

uclchem.makerates.io_functions.write_reactions(file_name: pathlib.Path, reaction_list: list[uclchem.makerates.reaction.Reaction]) → None[source]#

Write the human readable reaction file.

Parameters:

  • file_name (Path) – path to output file

  • reaction_list (list[Reaction]) – List of reaction objects for network

uclchem.makerates.io_functions.write_species(file_name: str | pathlib.Path, species_list: list[uclchem.makerates.species.Species]) → None[source]#

Write the human readable species file. Note UCLCHEM doesn’t use this file.

Parameters:

  • file_name (str | Path) – path to output file

  • species_list (list[Species]) – List of species objects for network

uclchem.makerates.io_functions.FORTRAN_LINE_LENGTH = 72[source]#
uclchem.makerates.io_functions.logger[source]#