pycif.plugins.datastreams.fluxes.tm5 — API reference

Configuration reference: tm5 plugin

pycif.plugins.datastreams.fluxes.tm5.fetch.fetch(ref_dir, ref_file, date_interval, target_dir, tracer=None, **kwargs)

Fetch TM5 flux files and derive the validity time intervals they cover.

Lists candidate files at tracer.file_freq; for each existing file, reads the time_start array of every emission source under the glb600x400 region/species group (using tracer.varname or tracer.orig_name), builds [start, end] intervals between consecutive time_start values (the last interval extended to the end of date_interval), and links the file into target_dir.

Parameters:

• ref_dir (str) – Directory containing the reference input files.

• ref_file (str) – Filename pattern of the input files (a strftime format string).

• date_interval (list[datetime.datetime]) – [date_i, date_f] simulation interval to cover.

• target_dir (str) – Directory where the resolved files are linked.

• tracer – The flux tracer plugin, providing file_freq and varname/orig_name (used to locate the species group in the file).

Returns:

(list_files, list_dates), each keyed by the candidate file date, mapping to the list of resolved file paths and the list of [start, end] date-interval pairs found in those files.

Return type:

tuple[dict, dict]

pycif.plugins.datastreams.fluxes.tm5.read.read_AB(self, name, tracdir, tracfile, varnames, dates, interpol_flx=False, tracer=None, model=None, **kwargs)

Original/legacy reader; NOT wired into the plugin (superseded by read below).

Despite scanning tracdir for files matching tracfile, this function does not actually read flux data from them: it fills the output with random values (numpy.random.rand) for every requested date, making it effectively a stub/placeholder. Kept for reference only.

Parameters:

• self – the fluxes Plugin, providing domain (for the output shape).

• name – the name of the component

• tracdir – flux directory and file format

• tracfile – flux directory and file format

• varnames – Unused, kept for interface consistency.

• dates – list of dates to extract

• interpol_flx (bool) – Unused, kept for interface consistency.

• tracer – Unused, kept for interface consistency.

• model – Used only as a fallback for tracfile if the latter is empty (via model.flux.file).

Returns:

An array of random values with dimensions (time, lev, lat, lon) – not real flux data.

Return type:

xr.DataArray

pycif.plugins.datastreams.fluxes.tm5.read.read(self, name, varnames, dates, files, interpol_flx=False, tracer=None, model=None, ddi=None, **kwargs)

PURPOSE Active reader. Get fluxes from TM5 emission NetCDF-4 files and load them into a pyCIF variable. For each requested date/file pair, opens the file’s glb600x400 (or glb300x200) region group, validates the grid shape and that the time arrays are consistent across all emission sources (biomass-burning, rice, wetlands, other), sums the sources’ emission fields, and selects the value at the matching time_start index. Optionally applies an exponential transform if tracer.exp_conversion is set.

ARGS self = the fluxes Plugin name = the name of the component (used as the species group

name in the file)

varnames = original name(s) of the variable(s) to read; unused

directly here (the species group name is used instead)

dates = list of [start, end] date intervals to extract; only

the start of each interval is matched against the file’s time_start values

files = list of files matching dates interpol_flx = (bool): Unused, kept for interface consistency with

other flux plugins.

tracer = the flux tracer plugin, providing exp_conversion model = Unused, kept for interface consistency. ddi = Unused, kept for interface consistency.

KWARGS **kwargs = Unused, kept for interface consistency.

RETURNS xr.DataArray with dimensions (time, lev, lat, lon): the summed, optionally exponential-converted, emission field for each requested date.

RAISES CifRuntimeError: if a file has an unexpected number of NetCDF-4 groups,

an unknown region, an inconsistent emission array shape, mismatched time arrays across sources, or a requested date not present in the file’s time_start values.

VERSION HISTORY 2.0 09-06-2021 by J.C.A. van Peet

Adapted for TM5.

1.0 ??-??-???? by A. Berchet

See original code above.

pycif.plugins.datastreams.fluxes.tm5.read_adj.read_adj(filename)

PURPOSE Standalone helper (not part of the plugin’s read/write interface, and not called with self). Read adjoint emission-factor fluxes from an adjoint TM5 run, generally saved to a file called adj_emissions.nc4: opens the glb600x400 region group, validates the grid shape and the units/long_name attributes of the adj_emis variable under the total source, and returns the raw array.

ARGS filename = the full name of the file, including path

KWARGS None

RETURNS numpy.ndarray with shape (nt, n_lat, n_lon): the raw adj_emis values read from the total source group.

RAISES CifRuntimeError: if the file does not have exactly one NetCDF-4 group,

the region is unknown, the emission array shape is inconsistent with the grid, more than one source is present, or the units/long_name attributes of adj_emis are unexpected.

VERSION HISTORY 1.0 26-10-2021 by J.C.A. van Peet

Original code

pycif.plugins.datastreams.fluxes.tm5.write.write_AB(self, name, flx_file, flx, mode='a')

Original/legacy writer; NOT wired into the plugin (superseded by write below).

Only prints debug information about flx_file, name and flx to stdout; does not actually write anything to disk. Kept for reference only.

Parameters:

• self (Fluxes) – the Fluxes plugin

• name (str) – name of the flux variable

• flx_file (str) – the file that would be written

• flx (xarray.DataArray) – fluxes data that would be written

• mode (str) – ‘w’ to overwrite, ‘a’ to append

pycif.plugins.datastreams.fluxes.tm5.write.write(self, name, flx_file, flx, mode='w', **kwargs)

PURPOSE Active writer. Write flux to a TM5 emission compatible NetCDF-4 file. Builds the glb600x400 grid, validates that flx’s spatial shape matches it and that mode is 'w', computes time_start/ time_mid/time_end (assuming monthly resolution), deletes any pre-existing file at flx_file, and creates a new file with nested glb600x400/CH4/total groups holding the emission, time_start, time_mid and time_end variables.

ARGS self (Fluxes) = the Fluxes plugin name (str) = name of the flux variable (unused directly;

kept for interface consistency)

flx_file (str) = the file where to write fluxes flx (xarray.DataArray) = fluxes data to write, with dimensions

(time, lev, lat, lon) and a single level

mode (str) = must be ‘w’; ‘a’ (append) is not supported

KWARGS **kwargs = Unused, kept for interface consistency.

RAISES CifRuntimeError: if flx’s spatial shape does not match the

glb600x400 grid, or if mode is not 'w'.

VERSION HISTORY 2.0 09-06-2021 by J.C.A. van Peet

Adapted for TM5.

1.0 ??-??-???? by A. Berchet

See original code above.