.. role:: bash(code) :language: bash ######################## Domains (:bash:`domain`) ######################## .. contents:: Contents :local: Available Domains (:bash:`domain`) =================================== The following :bash:`domains` are implemented in pyCIF so far: .. toctree:: chimere flexpart gridded_NetCDF iconart lmdz dummy wrfchem Description ============= The :bash:`domain` loads and stores information about domains. Domains in pyCIF include all geographical information about models and datastreams grids, both in the horizontal and vertical direction. Required parameters, dependencies and functions =============================================== The following attributes, dependencies and functions should be defined for any :bash:`domain`, as they are called by other plugins. They can be parameters to define at the set-up step, functions to implement in the corresponding module, or dependencies to be attached to the :bash:`domain` class. Parameters and attributes +++++++++++++++++++++++++ Domains in pyCIF are defined with the following data: Initialization parameters ------------------------- The following parameters/data are defined at the initialization of the domain, either in the function :bash:`create_domain` or :bash:`read_grid`: :``unstructured_domain``: (optional) this parameter is set to :bash:`True` when the domain cannot be defined with a regular 2D array; instead, it is stored as a flat list of grid cells; .. warning:: In the case of unstructured domains, the expected dimensions (``nlon`` / ``nlat``) should ALWAYS be set to: ``nlon`` = number of grid cells ``nlat`` = 1 :``regular_degrees``: (optional) this parameter goes in tandem with ``unstructured_domain``; it set to ``True`` for unstructured domains, the grid cells of which are regular rectangles in degrees. Setting to ``True`` speeds up the computation of grid cell areas :``nlon`` / ``nlat`` / ``nlev``: dimensions of the domain in horizontal and vertical directions :``zlon`` / ``zlat``: arrays of grid cell centers; for unstructured domains, the expected dimension is 1 / ``ncells`` :``zlonc`` / ``zlatc``: arrays of grid cell corners; for structured domains, it is arrays of dimensions ``nlon + 1`` / ``nlat + 1``; for unstructured domains, the expected dimension is ``nvertices`` / ``ncells`` :``sigma_a`` / ``sigma_b``: alpha/beta sigma pressure levels :``pressure_unit``: (optional) pressure units: should be one of ``hPa`` and ``Pa``; ``Pa`` is assumed if not specied :``heights``: heights above ground level of the domain levels .. warning:: if both ``sigma_a`` / ``sigma_b`` and ``heights`` are specified, only sigma levels are considered :``lon_cyclic``: (optional) set to ``True`` if the domain is cyclic in the zonal direction; this is the case for, e.g., global domains :``projection``: (optional) can be set to ``xy`` if the longitudes and latitudes are not in GPS standard coordinates; in that case, values are assumed to be meters from a reference point The horizontal definition of the domain is used to determine and compute horizontal regridding (see details in the corresponding transform documentation :doc:`here `) The vertical definition of the domain is used for vertical interpolations in the corresponding transform (see details :doc:`here `). Online parameters ----------------- The following parameters/data are computed online during the computation of pyCIF depending on the computation needs and the other domain parameters: :``zlon_side`` / ``zlat_side``: longitudes / latitudes of the sides of the domain; they can simply be the outer border of the domain, or a buffer region in some cases :``zlonc_side`` / ``zlatc_side``: same as ``zlon_side`` / ``zlat_side`` for corners :``nlon_side`` / ``nlat_side``: number of grids in the sides; for domain for which sides are the 1D border of the domain, ``nlon_side = nb of side grids`` and ``nlat_side = 1``; for domains with a buffer region, ``nlat_side`` can be different from 1 :``areas``: grid cell areas Functions +++++++++ The following functions need to be implemented in any domain to make it interact with other classes. They must be imported at the root level of the corresponding python package, i.e. in the ``__init__.py`` file: .. code-block:: python from XXXXX import ini_periods from XXXXX import run from XXXXX import native2inputs from XXXXX import native2inputs_adj from XXXXX import outputs2native from XXXXX import outputs2native_adj from XXXXX import compile from XXXXX import ini_mapper read_grid ----------- This function is called by default during the initialization of any domain. It is expected to initialize the above-mentioned parameters. If fails with a ``IoError`` or ``AttributeError``, the function ``create_domain`` is automatically called. This function is designed for reading a domain that was already computed from existing coordinate files and auxiliary information. :bash:`read_grid` is a class method that applies to the :bash:`domain` plugin itself. Therefore, the only expected argument is :bash:`self`. .. code-block:: python def read_grid(self, **kwargs): self.zlon = XXXX self.zlat = XXXXX self.zlonc = XXXXX self.zlatc = XXXXX self.nlon = XXXXX self.nlat = XXXXX self.nlev = XXXXX self.sigma_a = XXXXX self.sigma_b = XXXXX self.nlev = XXXXX Click below to see an example of the :bash:`read_grid` function for the model CHIMERE. .. module:: pycif.plugins.domains.chimere :noindex: .. function:: read_grid create_domain --------------- This function is called when ``read_grid`` fails for some reason. It is similar to ``read_grid``, but instead of reading an existing domain, it will create it from the information given in the Yaml configuration file. Click below to see an example of the :bash:`create_domain` function for the model CHIMERE. .. function:: create_domain get_sides (optional) ------------------------ This function defines the domain sides variables ``zlon_side``, ``zlat_side``, ``zlonc_side``, ``zlatc_side``, ``nlon_side``, ``nlat_side``. Similarly to ``read_grid`` and ``create_domain``, ``get_sides`` has a single argument ``self``. It is not necessary to define this function. By default, the border of the domain is taken using the default function below: .. autoclass:: pycif.utils.classes.domains.Domain .. automethod:: get_sides