pycif.plugins.datastreams.fields.chimere_icbc — API reference

Configuration reference: chimere_icbc plugin

pycif.plugins.datastreams.fields.chimere_icbc.fetch.fetch(ref_dir, ref_file, input_interval, target_dir, tracer=None, component=None)

Link CHIMERE INI_CONCS/BOUN_CONCS files and build the date/file maps.

For component.orig_name == "inicond", links the single initial condition file matching the start of input_interval. Otherwise (lateral/top boundary conditions), iterates over dates spaced by tracer.file_freq across input_interval, links each existing BOUN_CONCS-style file found, and builds hourly sub-intervals covering the period spanned by each file.

Parameters:

• ref_dir – Directory where the original files are found.

• ref_file – Date-format pattern for the original file names.

• input_interval – List of two dates, the beginning and end of the period to fetch.

• target_dir – Directory where links to the original files are created.

• tracer – Tracer/component configuration; tracer.file_freq gives the frequency at which BOUN_CONCS files are available.

• component – Component being fetched; component.orig_name is used to distinguish initial conditions from boundary conditions.

Returns:

A tuple (list_files, list_dates). For initial conditions, both dictionaries have a single key (the start date). For boundary conditions, each key is a file date mapping to the list of hourly files/sub-intervals covered by that file.

pycif.plugins.datastreams.fields.chimere_icbc.read.read(self, name, varnames, dates, files, interpol_flx=False, comp_type=None, ddi=None, **kwargs)

Read CHIMERE INI_CONCS/BOUN_CONCS data and load it into a pyCIF DataArray.

For comp_type == "inicond", reads the variable from the single INI_CONCS-style file in files. For "latcond"/"topcond", reads the lat_conc/top_conc variable from each BOUN_CONCS file in turn, looks up the matching species and date index (falling back to an index derived from ddi if the exact date string is not found), and fills the corresponding slice with zeros if the species is absent from the file.

Parameters:

• self – The field/tracer Plugin.

• name – Name of the component (used as fallback variable name).

• varnames – Name of the variable/species to read; if empty, name is used instead.

• dates – List of dates to extract, matching files.

• files – List of files matching dates.

• interpol_flx – Unused.

• comp_type – Type of boundary condition to read: "inicond", "latcond" or "topcond".

• ddi – Reference date used to compute a fallback time index when the exact date string cannot be found in a BOUN_CONCS file.

• **kwargs – Unused.

Returns:

A 4-dimensional (time, lev, lat, lon) array.

Return type:

xarray.DataArray

Raises:

CifError – If comp_type is None, unrecognized, or if ddi is needed but not given while a date cannot be matched exactly.

pycif.plugins.datastreams.fields.chimere_icbc.write.write(self, name, lbc_file, data, mode='a', metadata=None, comp_type=None, **kwargs)

Write data to CHIMERE INI_CONCS or BOUN_CONCS compatible files.

Resolves the domain (from self.domain or metadata["domain"]) and the comp_type (from the argument, or self.comp_type), then dispatches to write_iniconcs() for comp_type == "inicond" (choosing ppb or molecules/cm3 units depending on the magnitude of the data) or to write_bounconcs() otherwise.

Parameters:

• self – The field/tracer Plugin.

• name – Name (or list of names) of the species/component to write.

• lbc_file – Path to the output NetCDF file.

• data – Data to write, either a single array-like or a dict mapping species names to their data.

• mode – NetCDF write mode, "a" to append (falls back to "w" if the file does not yet exist) or "w" to overwrite.

• metadata – Optional dict with a "domain" entry, used when self.domain is not available.

• comp_type – Type of conditions to write: "inicond", "latcond" or "topcond". Falls back to self.comp_type if not given.

• **kwargs – Unused.

Raises:

• CifAttributeError – If no domain information can be found.

• CifError – If comp_type cannot be determined.

pycif.plugins.datastreams.fields.chimere_icbc.write.write_iniconcs(name, lbc_file, data, lon, lat, mode='a', units_in='ppb')

Create or update a CHIMERE INI_CONCS.nc-style file.

Validates that data has a horizontal shape matching lon, then either appends the new species to an existing file (updating the species/Times character arrays and rewriting the file) or creates the file from scratch with the lon/lat/Times/ species variables plus one data variable per species.

Parameters:

• name – Name, or list of names, of the species being written.

• lbc_file – Path to the output INI_CONCS-style NetCDF file.

• data – Data to write, either a single array-like (if name is a single string) or a dict mapping species names to their time-indexed data.

• lon – 2D array of grid-cell center longitudes.

• lat – 2D array of grid-cell center latitudes.

• mode – NetCDF write mode, "a" to append or "w" to overwrite.

• units_in – Units attribute to attach to the written data variables.

Raises:

CifError – If the data has the shape of boundary conditions instead of initial conditions, or has an incorrect horizontal shape.

pycif.plugins.datastreams.fields.chimere_icbc.write.write_bounconcs(name, lbc_file, data, lon, lat, lon_side, lat_side, nlev, mode='a', comp_type=None)

Create or update a CHIMERE BOUN_CONCS.nc-style file.

Either appends new species (or overwrites existing species’ slices) of the lat_conc/top_conc arrays in an existing file, or creates the file from scratch with lon/lat/Times/species variables plus the lat_conc/top_conc data arrays (the array not being written, top_conc for comp_type == "latcond" or vice versa, is filled with zeros).

Parameters:

• name – Name, or list of names, of the species being written.

• lbc_file – Path to the output BOUN_CONCS-style NetCDF file.

• data – Dict mapping species names to their time-indexed data (or a single array-like if name is a single string).

• lon – 2D array of grid-cell center longitudes.

• lat – 2D array of grid-cell center latitudes.

• lon_side – Array of perimeter-cell longitudes (lateral boundary).

• lat_side – Array of perimeter-cell latitudes (lateral boundary).

• nlev – Number of vertical levels.

• mode – NetCDF write mode, "a" to append or "w" to overwrite.

• comp_type – "latcond" to write the lat_conc array, or "topcond" to write the top_conc array.