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

Configuration reference: bc_plugin_template plugin

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

Template showing how to retrieve BC files and build the date/file maps.

Illustrates how a real fetch implementation should locate the original data files matching input_interval, link them into target_dir, and build the list_dates/list_files dictionaries consumed by read. The body below is placeholder print(...) statements only; it returns empty structures and must be replaced with real logic in any plugin derived from this template.

Choosing the keys for both dictionaries: the most efficient options are either (i) the dates at which the data files begin, or (ii) dates matching the typical use of this data. Example: if the data is typically used for generating BCs per day, use the dates of the days to simulate as keys. The idea is to avoid listing the same file under several keys, since read is called once per key.

Examples for a simulation from 01-01-2001 00H00 to 01-02-2001 00H00 for which input BC files cover 24 hours at an hourly resolution:

• data = annual data for 2001:

  list_dates = { '01-01-2001': [[01-01-2001 00H00, 31-12-2001 23H59]] }
  list_files = { '01-01-2001': [[yearly_data_file]] }
  

• data = hourly data in daily files:

  list_dates = { '01-01-2001 00H00': [[01-01-2001 00H00, 01-01-2001 01H00],
                                        [01-01-2001 01H00, 01-01-2001 02H00],
                                        ...
                                        [01-01-2001 23H00, 01-02-2001 00H00]] }
  list_files = { '01-01-2001 00H00': [daily_data_file_for_01/01/2001, ...] }
  

Parameters:

• ref_dir – Directory where the original files are found.

• ref_file – (template) Name of the original files.

• input_interval – List of two dates, the beginning and end of the simulation.

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

• tracer – Tracer/component configuration; tracer.file_freq is used here (and only here) to list the dates matching file availability.

• component – Unused in this template.

Returns:

A tuple (list_files, list_dates) of dictionaries. list_dates maps each key to a list of [date_beginning, date_end] intervals, each covered by one value taken from the matching file stored in list_files; list_files maps each key to the list of files covering those intervals. The intervals listed in list_dates must be the smallest intervals during which the values are constant (e.g. if time profiles are applied to yearly data, the intervals must be those obtained after applying the profiles, not the whole year). Decumulation of fields, if needed, is handled in read, not here.

Retrieves the characteristics of the spatial domain on which the data is provided.

Args:

• ref_dir: directory where the original data files are found

• ref_file: (template) name of the original files

• input_interval: XX???XXX

• target_dir: directory where the links to the orginal files are created

Returns:

• the setup of the domain, done in section “Initializes domain”

pycif.plugins.datastreams.fields.bc_plugin_template.get_domain.get_domain(ref_dir, ref_file, input_interval, target_dir, tracer=None)

Template showing how to build the domain object for BC fields.

Illustrates locating a domain reference file, deriving the horizontal grid (center and/or corner longitudes/latitudes, ordered increasingly, without overlap) and the vertical sigma coefficients, and assembling them into a Setup-based domain object. The body below is placeholder print(...) statements and references undefined variables (lon_min, zlon, etc.); it must be replaced with real logic in any plugin derived from this template.

Parameters:

• ref_dir – Directory where the original data files are found.

• ref_file – (template) Name of the original files.

• input_interval – List of two dates, the beginning and end of the simulation.

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

• tracer – Tracer/component configuration.

Returns:

The domain object attached to the Setup built above (setup.domain).

Raises:

CifError – If no domain reference file could be found.

Reads the data in the orignal files. Is called for each key in dictionary list_dates/list_files provided by fetch.

Args:

• name: name of the component

• dates: list of the dates matching the files

• files: list of the files matching the dates

-> dates and files as provided by fetch.py

• varnames: original names of variables to read

• comp_type: type of boundary conditions to generate. Useful to distinguish lateral from top from initial conditions.

Returns:

• a DataArray with the actual data: 4 dimensional (time, vertical levels, latitude, longitude) with coordinates in increasing order (see also get_domain).

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

Template showing how to read BCs from raw files into a pyCIF DataArray.

Illustrates looping over the dates/files pairs produced by fetch (one pair per key), reading the requested variable(s) from each file, and assembling the result into a 4-dimensional DataArray. The body below is placeholder print(...) statements only; data is never actually built, so this function would fail if run as-is and must be replaced with real logic in any plugin derived from this template.

Parameters:

• self – The field/tracer object.

• name – Name of the component.

• varnames – Original name(s) of the variable(s) to read.

• dates – List of dates matching files, as provided by fetch.

• files – List of files matching dates, as provided by fetch.

• interpol_flx – Unused in this template.

• comp_type – Type of boundary conditions to generate; useful to distinguish lateral from top from initial conditions.

• **kwargs – Unused in this template.

Returns:

A 4-dimensional (time, lev, lat, lon) array with coordinates in increasing order (see also get_domain).

Return type:

xarray.DataArray