pycif.plugins.chemistries.chimere — API reference

pycif.plugins.chemistries.chimere — API reference#

Configuration reference: chimere plugin

pycif.plugins.chemistries.chimere.make_chemistry.create_chemicalscheme(self)[source]#

Generate CHIMERE chemical-scheme files from the YAML configuration.

Counts all species categories (active, emitted, prescribed, …) and delegates to create_mandchem() and create_optchem() to write the full set of CHIMERE scheme files:

  • REACTIONS / CHEMISTRY / STOICHIOMETRY / REACTION_RATES

  • ACTIVE_SPECIES / ALL_SPECIES / OUTPUT_SPECIES

  • ANTHROPIC / BIOGENIC / DEPO_SPEC

  • PHOTO_PARAMETERS / PHOTO_RATES / FAMILIES

  • chemical_scheme.nml — Fortran namelist consumed by LMDZ executables.

Also builds inout_reaction_graph via make_inout_react_graph().

Parameters:

self – CHIMERE chemistry plugin instance with all species lists and schemeid / dirchem_ref set.

pycif.plugins.chemistries.chimere.read_chemistry.read_chemicalscheme(chemistry, **kwargs)[source]#

Read the CHIMERE chemical scheme from pre-computed files.

Parses the scheme files in {workdir}/chemical_scheme/{schemeid}/ and populates the chemistry plugin with species lists and reaction counts:

  • acspecies — active species with transport flags.

  • outspecies — output species with wet/dry conversion flags.

  • emis_species / nemisspec — anthropogenic emission species.

  • bio_species / nemisspec_interp — biogenic emission species.

  • dep_species / ndepspecies — depositing species.

  • nreacs — number of chemical reactions.

  • nfamilies — number of species families.

  • inout_reaction_graph — transitively-closed reactant → product mapping (built by make_inout_react_graph()).

Parameters:

  • chemistry – CHIMERE chemistry plugin instance with workdir and schemeid set.

  • **kwargs – unused.

pycif.plugins.chemistries.chimere.utils.create_mandchem(chemistry, mandatory_files)[source]#

Write the four mandatory CHIMERE chemistry text files from the YAML config.

Writes (in order):

  1. REACTIONS.{schemeid} — one reaction string per line.

  2. PRESCRIBED_SPECIES.{schemeid} — prescribed species names.

  3. PRODLOSS_SPECIES.{schemeid} — production/loss species names.

  4. DEPO_SPEC.{schemeid} — depositing species names.

Files are created empty when the corresponding species list is absent from the chemistry plugin.

Parameters:

  • chemistry – CHIMERE / TM5 chemistry plugin instance.

  • mandatory_files (list[str]) – four file paths in the order described above.

pycif.plugins.chemistries.chimere.utils.create_optchem(chemistry, filer, fileps)[source]#

Build the derived CHIMERE scheme files from reactions and species lists.

Reads REACTIONS and PRESCRIBED_SPECIES text files, parses stoichiometry and rate-coefficient strings, then writes:

  • STOICHIOMETRY — product stoichiometric coefficients.

  • CHEMISTRY — parsed reaction matrix (loss + product columns).

  • REACTION_RATES — reaction-rate type and parameter table.

  • PHOTO_RATES — photolysis reaction index ↔ J-rate name mapping.

  • PHOTO_PARAMETERS — photolysis altitude / zenith-angle table.

  • FAMILIES — empty (families not yet implemented).

  • DEPO_PARS / WETD_SPEC — empty deposition files.

  • ALL_SPECIES / ACTIVE_SPECIES / OUTPUT_SPECIES — species lists with type ('ac' / 'pr') and transport flags.

  • ANTHROPIC / BIOGENIC — emission species lists.

Parameters:

  • chemistry – CHIMERE chemistry plugin instance.

  • filer (str) – path to the REACTIONS text file.

  • fileps (str) – path to the PRESCRIBED_SPECIES text file.

Returns:

(nallqmax, nphoto_rates) — total number of species and number of photolysis reactions.

Return type:

tuple[int, int]

Raises:

Exception – if any emitted / biogenic / output species is not in acspecies, or if chemical families are requested.

pycif.plugins.chemistries.chimere.utils.read_react(reactions, filej)[source]#

Parse reaction-rate strings and write the PHOTO_RATES file.

Classifies each reaction into one of five CHIMERE rate types:

  1. k=<value> — constant rate.

  2. k(T)=Aexp(-B/T) — simplified Arrhenius (2 parameters).

  3. k(T)=Aexp(-B/T)(300/T)**N — full Arrhenius (3 parameters).

  4. k(P)=A(B+C*P/Pref) — pressure-dependent (3 parameters).

  5. J=<name> — photolysis (index written to filej).

Parameters:

  • reactions (np.ndarray) – 1-D array of rate-formula strings, one per reaction.

  • filej (str) – path to the PHOTO_RATES output file.

Returns:

(reactions_rates, nphoto_rates, photo_rates) where reactions_rates is a (nreac, 10) float array with type code in column 0 and parameters in columns 1–9, nphoto_rates is the number of photolysis reactions, and photo_rates is a DataFrame of (reaction_index, J-rate_name) pairs.

Return type:

tuple

pycif.plugins.chemistries.chimere.utils.make_inout_react_graph(filer)[source]#

Build a transitively-closed reactant → product graph from a CHEMISTRY file.

Reads the CHIMERE CHEMISTRY.{schemeid} text file (columns: nloss, loss_1, …, loss_nloss, nprod, prod_1, …), constructs a direct reactant → product mapping, then propagates the graph recursively until no new connections are added.

The result maps each reactant to every species it can eventually produce through any chain of reactions in the scheme. This graph is used by the adjoint mapper to route sensitivities from outputs back to all relevant emission inputs.

Parameters:

filer (str) – path to the CHEMISTRY.{schemeid} text file.

Returns:

mapping of reactant name → sorted unique list of all (direct and indirect) product names. Returns {} when the file is empty.

Return type:

dict[str, list[str]]