pycif.plugins.models.chimere — API reference

Configuration reference: chimere plugin

pycif.plugins.models.chimere.compile.compile(self)

Compile (or copy) the CHIMERE forward, TL, and adjoint executables.

Follows a two-strategy approach:

1. Copy pre-compiled executables (default) — copies fwdchimere.e, tlchimere.e, and achimere.e from self.direxec into $workdir/model/. Skipped when force-recompile = True.

2. Compile from sources — triggered when auto-recompile = True (or when the pre-compiled executables are not found). Clones the source tree from self.dir_sources (or self.direxec), patches the Makefiles for the configured compiler and library paths (NetCDF, GRIB, LDFLAGS), and runs make for each of the three build variants (forward, TL, adjoint) in PROD or DEBUG mode.

Parameters:

self (Plugin) – CHIMERE model plugin instance (carries workdir, direxec, dir_sources, compiler flags, and force-recompile / auto-recompile flags).

Raises:

RuntimeError – if auto-recompile is False and the executables cannot be found.

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

Cleaning the simulation directories to limit space usage

pycif.plugins.models.chimere.flushrun.flush_rundir(runsubdir, mode, final=False, full_flush=True)

Remove large temporary CHIMERE files from one sub-simulation directory.

Deletes the bulky input/output NetCDF files that are no longer needed once a sub-simulation period has completed (or once the full run is done).

Files always removed: AEMISSIONS, BEMISSIONS, BOUN_CONCS, INI_CONCS, METEO, chimere.nml, deposition, end, output files.

Additionally for adjoint runs: .txt files.

Additionally when final=True: aout, aini, aend files.

Additionally when full_flush=True: end.*.nc concentration restart files.

Parameters:

• runsubdir (str) – path to the sub-simulation directory to clean.

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

• final (bool) – if True, also remove aout, aini, aend files (called at end of full run, not between chained periods).

• full_flush (bool) – if True, also remove end.*.nc restart files (disables period chaining restart capability).

pycif.plugins.models.chimere.ini_mapper.ini_mapper(model, general_mapper={}, backup_comps={}, transforms_order=[], ref_transform='', transform_name='', **kwargs)

Build the data-flow mapper for the CHIMERE chemistry-transport model.

Defines input and output tracer IDs and their associated domain and date-window metadata. CHIMERE requires the following input streams:

• AEMISSIONS — anthropogenic emissions (nlevemis surface levels).

• BEMISSIONS — biogenic emissions (surface level only).

• Lateral boundary conditions — boundlat_north/south/east/west.

• Top boundary conditions — boundtop.

• Initial conditions — inicond (at datei only).

• End concentrations — endconcs chained from the previous period.

• Meteorology — wind, temperature, humidity, layer heights, etc.

Output streams are the simulated concentrations for each active species plus diagnostic meteorological fields (pressure, temperature, air mass, layer heights).

Also populates outputs2inputs linking each concentration output to the corresponding emission input to guide adjoint sensitivity routing.

Parameters:

• model – CHIMERE model plugin instance.

• general_mapper (dict) – unused.

• backup_comps (dict) – unused.

• transforms_order (list) – unused.

• ref_transform (str) – unused.

• transform_name (str) – unused.

• **kwargs – unused.

Returns:

mapper with inputs, outputs, and outputs2inputs.

Return type:

dict

Raises:

PluginError – if required input components are missing from the datavect.

pycif.plugins.models.chimere.ini_periods.ini_periods(self, **kwargs)

Initialise sub-simulation periods and time-step grids for CHIMERE.

Partitions the full simulation window into sub-periods of length self.periods (typically 1 day) and determines the number of physical time steps per hour (nphour) for each sub-period.

When a METEO.nc file is present, nphour is read from the NetCDF nphourm variable, which may vary through the simulation window (CFL-adaptive time stepping). Otherwise it defaults to self.nphour_ref.

Sets the following attributes on self:

• subsimu_dates — boundary dates of all sub-periods.

• tstep_dates — dict mapping each sub-period start to its time-step array.

• input_dates — same structure, used to schedule data reads.

• tstep_all — flat array of all time steps.

• nhour — dict of nphour per sub-period.

• subtstep — dict of sub-time-step counts per sub-period.

• iniobs — whether to dump observations for each sub-period.

• reset_obs — whether to reset the observation accumulator.

• runsimu — whether to actually run each sub-period (False for stop-or-more periods already computed).

• chain — whether each sub-period has a successor.

Parameters:

• self (Plugin) – CHIMERE model plugin instance (carries datei, datef, periods, nphour_ref, nho, nhours, workdir, and stopORmore).

• **kwargs – unused; accepted for interface consistency.

Raises:

Exception – if sub-periods are not all of the same length.

pycif.plugins.models.chimere.perturb_model.perturb_model(self, nsamples, transf_mapper)

Extend the CHIMERE chemistry scheme to accommodate ensemble members.

Creates nsamples copies of each active species (acspecies), output species (outspecies), emitted species (emis_species), and biogenic species (bio_species) in the chemistry plugin, then removes the original un-suffixed species. The copies are named with a numeric suffix (e.g. CH4000, CH4001, …). Also records a perturbed_species mapping from sample name back to original name.

Note

Reactions in the chemical scheme are not yet supported with perturbations; an exception is raised if self.reactions is set.

Parameters:

• self (Plugin) – CHIMERE model plugin instance.

• nsamples (int) – number of ensemble members.

• transf_mapper (dict) – transform mapper (unused; kept for API consistency with other model plugins).

Raises:

Exception – if the chemical scheme contains reactions.

pycif.plugins.models.chimere.run.run(self, runsubdir, mode, workdir, ddi, nbproc=1, do_simu=True, approx_transf=False, ref_fwd_dir='', overlap=False, **kwargs)

Run the CHIMERE model in forward mode

Parameters:

• self – the model Plugin

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

• mode (str) – forward or backward

• workdir (str) – pyCIF working directory

• do_simu (bool) – re-run or not existing simulation

pycif.plugins.models.chimere.utils.check_inputs(self, runsubdir, mode)

Verify that all required CHIMERE input files exist in the run directory.

Checks for the presence of the mandatory input files before launching the CHIMERE executable. The list of required files depends on whether biogenic emissions are active (self.useemisb).

Mandatory files: METEO.nc, BOUN_CONCS.nc, AEMISSIONS.nc, INI_CONCS.0.nc, chimere.nml, chimere.e, and (if useemisb) BEMISSIONS.nc.

Parameters:

• self (Plugin) – CHIMERE model plugin instance.

• runsubdir (str) – sub-simulation run directory to check.

• mode (str) – execution mode ('fwd', 'tl', or 'adj'); currently unused but kept for API consistency.

Raises:

Exception – if any required file is missing from runsubdir.