pycif.plugins.models.lmdz_ico — API reference

Configuration reference: lmdz_ico plugin

pycif.plugins.models.lmdz_ico.compile.run_command(*args: str | PathLike, cwd: str | PathLike | None = None, logfile: TextIO | None = None) → None

pycif.plugins.models.lmdz_ico.compile.get_make_command(self) → list[str]

pycif.plugins.models.lmdz_ico.compile.compile(self) → None

Compile or copy the LMDZ executable into the CIF work directory

pycif.plugins.models.lmdz_ico.flushrun.to_output(path: Path) → Path

pycif.plugins.models.lmdz_ico.flushrun.remove_file(runsubdir: Path, filename: str, input_only: bool = True) → None

Remove a file (and optionally its _out counterpart) from runsubdir.

pycif.plugins.models.lmdz_ico.flushrun.remove_spec_files(runsubdir: Path, filename: str, species: list[str], input_only: bool = True) → None

Remove a file and its per-species variants from runsubdir.

pycif.plugins.models.lmdz_ico.flushrun.flush(self, runsubdir: Path, input_only: bool = True) → None

Clean a simulation sub directory

Parameters

runsubdirPath

Path to the simulation sub directory

input_onlybool, optional

Only remove input files and not output files, by default True

pycif.plugins.models.lmdz_ico.flushrun.flushrun(self, rundir, mode, transform_id, full_flush=True)

Cleaning the simulation directories to limit space usage

pycif.plugins.models.lmdz_ico.ini_mapper.get_input_intervals(self, input_dates: dict[datetime, ndarray]) → dict[datetime, ndarray]

pycif.plugins.models.lmdz_ico.ini_mapper.ini_mapper(self, transform_type, general_mapper={}, backup_comps={}, transforms_order=[], ref_transform='', transform_name='', **kwargs) → dict[str, dict[tuple[str, str], dict[str, Any] | list[str] | list[tuple[str, str]]]]

pycif.plugins.models.lmdz_ico.ini_periods.is_month_start(datetime: Timestamp) → bool

pycif.plugins.models.lmdz_ico.ini_periods.ini_periods(self, **kwargs) → None

pycif.plugins.models.lmdz_ico.perturb_model.append_attribute(plugin: Any, key: str, attr: Any) → None

pycif.plugins.models.lmdz_ico.perturb_model.remove_attribute(plugin: Any, key: str) → None

pycif.plugins.models.lmdz_ico.perturb_model.perturb_model(self, nsamples: int, transf_mapper)

pycif.plugins.models.lmdz_ico.run.run_dispersion(self, runsubdir: Path) → None

Launch the LMDZ-ico dispersion executable

pycif.plugins.models.lmdz_ico.run.run(self, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'], workdir: str | PathLike, ddi: datetime, do_simu: bool = True, approx_transf: bool = False, ref_fwd_dir: str | PathLike | None = None, overlap: bool = False, **kwargs)

Run the LMDZ model

pycif.plugins.models.lmdz_ico.run.dump_trajq(self, runsubdir: str | PathLike, ddi: datetime) → None

Dumps binary trajectory-flux (trajq) as NetCDF files

pycif.plugins.models.lmdz_ico.run.check_approx_threshold(self, ddi, mode, runsubdir)

class pycif.plugins.models.lmdz_ico.chemistry.chemical_scheme.Reaction(active_reactants: List[Species], prescribed_reactants: List[Species], active_products: List[Species], active_product_stoi: List[int], reac_type: Literal['constant', 'simplified_arrhenius', 'arrhenius', 'pressure'], rate_constants: List[float])

Bases: object

A class representing a chemical reaction

Parameters:

• active_reactants (list of Species) – Active reactants

• prescribed_reactants (list of Species) – Prescribed reactants

• active_products (list of Species) – Active products

• active_product_stoi (list of int) – Active product stoichiometric numbers

• reac_type (int) – Reaction type

• rate_constants (list of float)

active_reactants: List[Species]

prescribed_reactants: List[Species]

active_products: List[Species]

active_product_stoi: List[int]

reac_type: Literal['constant', 'simplified_arrhenius', 'arrhenius', 'pressure']

rate_constants: List[float]

rates(temp: DataArray, pmid: DataArray) → DataArray

Compute reaction rates

Parameters:

• temp (xr.DataArray) – temperature field [K]

• pmid (xr.DataArray) – pressure field [Pa]

Returns:

rates [molec/cm2/s2]

Return type:

xr.DataArray

pycif.plugins.models.lmdz_ico.chemistry.chemical_scheme.parse_chemical_scheme(self: Any) → Tuple[List[Reaction], DataArray]

Parse the chemical scheme, partial reimplementation of LMDZ’s “read_chemical_scheme” subroutine

Parameters:

self (Model)

Returns:

list of reactions, molar masses

Return type:

(list of Reaction, xr.DataArray)

pycif.plugins.models.lmdz_ico.chemistry.compute_chemistry.compute_chemistry_step(reaction_list: List[Reaction], molar_masses: DataArray, dt: float, mmr: DataArray, mmr_tl: DataArray, prescr: DataArray, prescr_tl: DataArray, pmid: DataArray, temp: DataArray) → Tuple[DataArray, DataArray]

Reimplementation of LMDZ’s “compute_chem_tl” subroutine.

Parameters:

• reaction_list (list of Reaction) – list of reactions

• molar_masses (xr.DataArray) – molar masses of active species

• dt (float) – time step [s]

• mmr (xr.DataArray) – mass ratio (forward) [kg/kg]

• mmr_tl (xr.DataArray) – mass ratio (tangent) [kg/kg]

• prescr (xr.DataArray) – prescribed species concentrations (forward) [molec/cm3]

• prescr_tl (xr.DataArray) – prescribed species concentrations (tangent) [molec/cm3]

• pmid (xr.DataArray) – pressure field [Pa]

• temp (xr.DataArray) – temperature field [K]

Returns:

losses [kg/kg] xr.DataArray: losses_tl [kg/kg]

Return type:

xr.DataArray

pycif.plugins.models.lmdz_ico.chemistry.compute_chemistry.compute_chemistry_step_ad(reaction_list: List[Reaction], molar_masses: DataArray, dt: float, mmr: DataArray, mmr_ad: DataArray, prescr: DataArray, pmid: DataArray, temp: DataArray) → DataArray

Reimplementation of LMDZ’s “compute_chem_ad” subroutine.

Parameters:

• reaction_list (list of Reaction) – list of reactions

• molar_masses (xr.DataArray) – molar masses of active species

• dt (float) – time step [s]

• mmr (xr.DataArray) – mass ratio (forward) [kg/kg]

• mmr_ad (xr.DataArray) – mass ratio (tangent) [kg/kg]

• prescr (xr.DataArray) – prescribed species concentrations (forward) [molec/cm3]

• prescr_ad (xr.DataArray) – prescribed species concentrations (tangent) [molec/cm3]

• pmid (xr.DataArray) – pressure field [Pa]

• temp (xr.DataArray) – temperature field [K]

Returns:

losses [kg/kg] xr.DataArray: losses_ad [kg/kg]

Return type:

xr.DataArray

pycif.plugins.models.lmdz_ico.io.native2inputs.native2inputs(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]] | None, input_type: str, datei: datetime, datef: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'] = 'fwd', onlyinit: bool = False, do_simu: bool = True, check_transforms: bool = False, **kwargs) → None

Converts data at the model data resolution to model compatible input files.

Parameters:

• self – the model Plugin

• input_type (str) – one of ‘fluxes’, ‘obs’

• datastore – data to convert if input_type == ‘fluxes’, a dictionary with flux maps if input_type == ‘obs’, a pandas dataframe with the observations

• datei – date interval of the sub-simulation

• datef – date interval of the sub-simulation

• mode (str) – running mode: one of ‘fwd’, ‘adj’ and ‘tl’

• runsubdir (str) – sub-directory for the current simulation

• workdir (str) – the directory of the whole pycif simulation

Notes

• LMDZ expects daily inputs; if the periods in the control vector are

longer than one day, period values are uniformly de-aggregated to the daily scale; this is done with pandas function ‘asfreq’ and the option ‘ffill’ as ‘forward-filling’ See Pandas page for details: https://pandas.pydata.org/pandas-docs/stable/generated/pandas .DataFrame.asfreq.html

pycif.plugins.models.lmdz_ico.io.native2inputs_adj.native2inputs_adj(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], input_type: str, datei: datetime, datef: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'] = 'fwd', onlyinit: bool = False, do_simu: bool = True, check_transforms: bool = False, **kwargs) → dict[tuple[str, str], dict[str | datetime, Any]]

Converts data at the model data resolution to model compatible input files.

Parameters:

• self – the model Plugin

• input_type (str) – one of ‘fluxes’, ‘obs’

• datastore – data to convert if input_type == ‘fluxes’, a dictionary with flux maps if input_type == ‘obs’, a pandas dataframe with the observations

• datei – date interval of the sub-simulation

• datef – date interval of the sub-simulation

• mode (str) – running mode: one of ‘fwd’, ‘adj’ and ‘tl’

• runsubdir (str) – sub-directory for the current simulation

• workdir (str) – the directory of the whole pycif simulation

Notes

• LMDZ expects daily inputs; if the periods in the control vector are

longer than one day, period values are uniformly de-aggregated to the daily scale; this is done with pandas function ‘asfreq’ and the option ‘ffill’ as ‘forward-filling’ See Pandas page for details: https://pandas.pydata.org/pandas-docs/stable/generated/pandas .DataFrame.asfreq.html

pycif.plugins.models.lmdz_ico.io.outputs2native.outputs2native(self, data2dump: dict[tuple[str, str], dict[str | datetime, Any]], input_type: str, datei: datetime, datef: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'] = 'fwd', onlyinit: bool = False, check_transforms: bool = False, **kwargs) → dict[tuple[str, str], dict[str | datetime, Any]]

Reads outputs to pycif objects.

If the mode is ‘fwd’ or ‘tl’, only observation-like outputs are extracted. For the ‘adj’ mode, all outputs relative to model sensitivity are extracted.

Dumps to a NetCDF file with output concentrations if needed

Parameters:

• self (pycif.utils.classes.models.Model) – Model object

• runsubdir (str) – current sub-sumilation directory

• mode (str) – running mode; one of: ‘fwd’, ‘tl’, ‘adj’; default is ‘fwd’

• dump (bool) – dumping outputs or not; default is True

Returns:

dict

pycif.plugins.models.lmdz_ico.io.outputs2native_adj.outputs2native_adj(self, data2dump: dict[tuple[str, str], dict[str | datetime, Any]], input_type: str, datei: datetime, datef: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'] = 'fwd', dump: bool = True, onlyinit: bool = False, do_simu: bool = True, check_transforms: bool = False, **kwargs) → None

Reads outputs to pycif objects.

If the mode is ‘fwd’ or ‘tl’, only observation-like outputs are extracted. For the ‘adj’ mode, all outputs relative to model sensitivity are extracted.

Dumps to a NetCDF file with output concentrations if needed

Parameters:

• self (pycif.utils.classes.models.Model) – Model object

• runsubdir (str) – current sub-sumilation directory

• mode (str) – running mode; one of: ‘fwd’, ‘tl’, ‘adj’; default is ‘fwd’

• dump (bool) – dumping outputs or not; default is True

Returns:

dict

pycif.plugins.models.lmdz_ico.io.inputs.chemfields.get_species(self, input_type: str) → list[str]

Return the species list for a given chemistry input type

pycif.plugins.models.lmdz_ico.io.inputs.chemfields.make_chemfields(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], input_type: Literal['prodloss3d', 'prescrconcs', 'deposition', 'photorates'], ddi: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj']) → None

Write chemistry concentration fields (prescribed, deposition, etc.) for LMDZ-ico

pycif.plugins.models.lmdz_ico.io.inputs.chemfields.make_kinetic(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], ddi: datetime, runsubdir: str | PathLike) → None

Write the kinetic (pressure/temperature) field for one period

pycif.plugins.models.lmdz_ico.io.inputs.ensemble.ensemble_trid(self, trid: tuple[str, str], datastore: dict[tuple[str, str], Any]) → tuple[str, str]

Replace ‘spec’ in the tracer id ‘trid’ (component, spec) by the suitable species name when in ensemble mode or do nothing when not in ensemble mode

Parameters:

• self – Model

• trid (str, str) – Tracer id (component, species)

• datastore (dict (str, str) -> Any) – Datastore

Returns:

New tracer id

Return type:

(str, str)

pycif.plugins.models.lmdz_ico.io.inputs.fluxes.make_fluxes(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], datei: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj']) → None

Write flux input files for one sub-simulation period

pycif.plugins.models.lmdz_ico.io.inputs.inicond.make_inicond(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], input_type: Literal['inicond', 'restart_inicond'], datei: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'], onlyinit: bool) → None

Write or symlink the initial-condition restart file

pycif.plugins.models.lmdz_ico.io.inputs.make_auxiliary.make_parameters_file(self, datei: Timestamp | datetime, datef: Timestamp | datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj']) → None

Write the LMDZ-ico Fortran parameters namelist for one sub-period.

Generates the parameters.nml file inside runsubdir containing domain dimensions, time-step counts, and I/O paths needed by the LMDZ icosahedral-grid executable.

Parameters:

• self – LMDZ-ico model plugin instance.

• datei – period start date.

• datef – period end date.

• runsubdir – path to the period run directory.

• mode – 'fwd', 'tl', or 'adj'.

pycif.plugins.models.lmdz_ico.io.inputs.make_auxiliary.make_auxiliary(self, ddi: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'] = 'fwd', onlyinit: bool = False, do_simu: bool = True, **kwargs) → None

Write auxiliary files for one sub-simulation period

pycif.plugins.models.lmdz_ico.io.inputs.make_endconcs.make_endconcs(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], datei: datetime, datef: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'], onlyinit: bool) → None

Link LMDZ-ico restart files into the period run directory for chaining

pycif.plugins.models.lmdz_ico.io.inputs.meteo.make_meteo(self, datastore: dict[tuple[str, str], dict[str | datetime, Any]], datei: datetime, runsubdir: str | PathLike) → None

Link mass-flux input files into the period run directory

pycif.plugins.models.lmdz_ico.io.inputs.obs.make_obs(self, dict_datastores: dict[tuple[str, str], DataFrame], ddi: datetime, input_type: str, runsubdir: str | PathLike, mode: Literal['fwd', 'adj']) → None

Write observation input file for one sub-period

pycif.plugins.models.lmdz_ico.io.outputs.fake_end.read_obs(self, runsubdir: str | PathLike) → tuple[int, ndarray, ndarray]

Reads time step and species index columns from ‘obs.nc

pycif.plugins.models.lmdz_ico.io.outputs.fake_end.read_air_mass(self, ddi: datetime, runsubdir: str | PathLike) → DataArray

Read the LMDZ-ico air-mass field from the run directory

pycif.plugins.models.lmdz_ico.io.outputs.fake_end.read_emissions(self, ddi: datetime, runsubdir: str | PathLike) → tuple[DataArray, DataArray]

Reads emissions “mod_*.bin” binary files

pycif.plugins.models.lmdz_ico.io.outputs.fake_end.time_slice(da: DataArray, di: datetime64, df: datetime64, agg_method: Literal['mean', 'sum'] = 'mean') → DataArray

Pick the values of a DataArray between ‘di’ and ‘df’ and aggregate along the time dimension

Parameters:

• da (xr.DataArray) – input DataArray with ‘time’ dimension and coordinate

• di (np.datetime64) – slice start

• df (np.datetime64) – slice end (NOT included)

• agg_method ("mean" or "sum", optional) – aggregation method. Defaults to “mean”.

Returns:

sliced and aggregated DataArray

Return type:

xr.DataArray

pycif.plugins.models.lmdz_ico.io.outputs.fake_end.perturb_ref_restart(self, restart_file: str | PathLike, ref_restart: str | PathLike) → None

Write a perturbed LMDZ-ico restart file by copying from a reference.

Copies ref_restart to restart_file and overwrites active-species mass mixing ratios with CIF-modified concentrations.

Parameters:

• self – LMDZ-ico model plugin instance.

• restart_file – output restart path.

• ref_restart – reference restart path to copy from.

pycif.plugins.models.lmdz_ico.io.outputs.fake_end.make_end(self, runsubdir: str | PathLike, ddi: datetime, ref_fwd_dir: str | PathLike) → None

TODO

Parameters:

• self (Model)

• ddi (datetime.datetime) – sub simulation start datetime

• runsubdir (str) – sub simulation run directory

• ref_fwd_dir (str) – reference forward run directory

pycif.plugins.models.lmdz_ico.io.outputs.fetch_end.fetch_end(self, data2dump: dict[tuple[str, str], dict[str | datetime, Any]], ddi: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj'], onlyinit: bool = False, check_transforms: bool = False) → dict[tuple[str, str], dict[str | datetime, Any]]

pycif.plugins.models.lmdz_ico.io.outputs.make_adjoint_out.make_adjoint_out(self, runsubdir, ddi, ref_fwd_dir)

pycif.plugins.models.lmdz_ico.io.outputs.read_sim.read_sim(self, data2dump: dict[tuple[str, str], dict[str | datetime, Any]], ddi: datetime, runsubdir: str | PathLike, mode: Literal['fwd', 'tl', 'adj']) → dict[tuple[str, str], Any]

Extract simulated concentrations