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

Run an external command and raise on failure.

Parameters:

• *args – command and arguments.

• cwd – working directory for the subprocess.

• logfile – optional writable file object for stdout; if None, output is captured and included in any raised exception.

Raises:

subprocess.CalledProcessError – on non-zero exit code.

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

Build the make command list for compiling LMDZ-ico.

Assembles arguments from plugin attributes: compile mode, grid, compiler, and optional NetCDF paths.

Parameters:

self – LMDZ-ico model plugin instance.

Returns:

make command and arguments.

Return type:

list[str]

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

Compile or copy the LMDZ-ico executable into the CIF work directory.

Attempts to copy a pre-compiled dispersion.e from self.executable (unless force-recompile is set), then falls back to running get_make_command() in the source tree.

Parameters:

self – LMDZ-ico model plugin instance.

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

Return the output-file counterpart of an input file path.

Appends _out before the suffix: foo.nc → foo_out.nc.

Parameters:

path – input file path.

Returns:

derived output file path.

Return type:

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.

Parameters:

• runsubdir – period run directory.

• filename – file name relative to runsubdir.

• input_only – if False, also delete the _out variant.

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.

Deletes filename and {stem}_{spec}{suffix} for each species. When input_only=False, also deletes the corresponding _out output files.

Parameters:

• runsubdir – period run directory.

• filename – base file name.

• species – list of species suffixes to also remove.

• input_only – if False, also delete output-file counterparts.

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]

Convert per-period date arrays to [start, end] interval pairs.

Filters pairs to only those that overlap with the full simulation window [self.datei, self.datef].

Parameters:

• self – LMDZ-ico model plugin instance.

• input_dates – mapping of period-start to sorted date arrays.

Returns:

mapping of period-start to (N, 2) arrays of date pairs.

Return type:

dict

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]]]]

Build the data-flow mapper for the LMDZ-ico (icosahedral-grid) model.

Registers:

• Flux inputs per active species at the configured flux frequency.

• Meteo inputs (mass fluxes) for transport.

• Chemical field inputs for prescribed species.

• Initial-condition and end-concentration inputs for period chaining.

• Outputs — sampled concentrations per output species.

• outputs2inputs linking each output tracer to its source inputs.

The surface-only domain variant (domain_surface) is used for 2-D flux inputs.

Parameters:

• self – LMDZ-ico model plugin instance with all date arrays already set by ini_periods().

• transform_type (str) – unused; kept for API compatibility.

• general_mapper (dict) – unused.

• backup_comps (dict) – updated in-place with fallback components.

• transforms_order (list) – unused.

• ref_transform (str) – unused.

• transform_name (str) – unused.

• **kwargs – unused.

Returns:

mapper with inputs, outputs, and outputs2inputs.

Return type:

dict

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

Return True if datetime falls exactly at the start of a calendar month (midnight).

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

Compute temporal discretisation for the LMDZ-ico model.

Splits the full window into sub-periods capped at one calendar month each, then builds per-period date arrays for time steps, inputs, fluxes, chemistry fields, and meteo mass fluxes.

Sets on self:

• subsimu_dates — period boundary datetimes.

• subsimu_intervals — dict mapping period start to (start, end) tuple.

• tstep_dates — per-period full-month time-step arrays.

• input_dates — per-period daily initial/end-concentration dates.

• flux_input_dates — per-period flux input dates.

• chem_input_dates — per-period chemistry field dates.

• meteo_input_dates — per-period mass-flux dates.

• iniobs, reset_obs — per-period obs bookkeeping flags.

• chunk_indexes — per-period per-component per-species index cache.

• runsimu — per-period flag controlling whether to run or use cached output.

• chain — per-period flag for adjoint restart chaining.

Parameters:

• self – LMDZ-ico plugin instance with datei, datef, period_freq, dt, flux_freq, chem_freq, mass_fluxes_freq, and chemistry.active_species set.

• **kwargs – unused.

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

Set attr as attribute key on plugin and append key to plugin.attributes.

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

Delete attribute key from plugin and remove it from plugin.attributes.

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

Extend the LMDZ-ico chemistry scheme to accommodate ensemble members.

Creates nsamples copies of each active and output species using the __sample#NNN naming convention. Records self.perturbed_species mapping sample names back to originals.

Parameters:

• self – LMDZ-ico model plugin instance.

• nsamples (int) – number of ensemble members.

• transf_mapper (dict) – unused; kept for API consistency.

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

Launch the LMDZ-ico dispersion executable for one sub-simulation period.

Runs the LMDZ-ico binary, setting ACC_NUM_CORES when using nvfortran. Output is redirected to dispersion.log. Raises on non-zero exit.

Parameters:

• self – LMDZ-ico model plugin instance.

• runsubdir – path to the period run directory.

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 LMDZ model in forward or adjoint mode

Parameters:

• runsubdir (str) – working directory for the current run

• mode (str) – forward or backward

• workdir (str) – pycif working directory

• do_simu (bool) – if False, considers that the simulation was already run

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

Write the LMDZ-ico trajectory-flux (trajq) binary file for the adjoint.

Reads forward concentration trajectories from the restart file in runsubdir and writes a Fortran-binary trajq.bin that the LMDZ-ico adjoint uses to back-propagate sensitivities through advection.

Parameters:

• self – LMDZ-ico model plugin instance.

• runsubdir – path to the period run directory.

• ddi – period start date.

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

Decide whether to skip LMDZ-ico transport and use linear chemistry.

If forward concentrations exceed self.approx_thresholds, marks the period to use the approximate linear-chemistry operator instead of the full LMDZ-ico transport.

Parameters:

• self – LMDZ-ico model plugin instance.

• ddi (datetime) – period start date.

• mode (str) – 'fwd', 'tl', or 'adj'.

• runsubdir – path to the period run directory.