Source code for pycif.plugins.datastreams.fluxes.flux_plugin_template.get_domain

import numpy as np
from logging import debug

from .....utils.classes.setup import Setup
from .....utils.classes.domains import Domain


def get_domain(ref_dir, ref_file, input_dates, target_dir, tracer=None):
    """Read information to define the data horizontal and, if relevant, vertical domain.

    There are several possible approaches:

      - read a reference file that is necessary in :bash:`ref_dir`
      - read a file among the available data files
      - read a file specified in the yaml,
        by using the corresponding variable name; for instance, tracer.my_file

    From the chosen file, obtain the coordinates of the centers and/or the corners
    of the grid cells. If corners or centers are not available, deduce them from
    the available information.

    Warning:
        the grid must not be overlapping: e.g for a global grid,
        the last grid cell must not be the same as the first

    Warning:
        Longitudes must be in the range [-180, 180].
        For dataset with longitudes beyond -180 or 180, please shift them.
        and adapt the ``read`` function accordingly

    Warning:
        Order the centers and corners latitudes and longitudes in increasing order
    
    Note:
        If the domain information need to be read from one of the files returned by the
        fetch function, one should use the variable :bash:`tracer.input_files` as follow:
        
        .. code-block:: python
            
            ref_file = list(itertools.chain.from_iterable(tracer.input_files.values()))[0]
    
    Args:
        ref_dir (str): the path to the input files
        ref_file (str): format of the input files
        input_dates (list): simulation interval (start and end dates)
        target_dir (str): where to copy
        tracer: the tracer Plugin, corresponding to the paragraph
            :bash:`datavect/components/fluxes/parameters/my_species` in the
            configuration yaml; can be needed to fetch extra information
            given by the user

    Return:
        Domain: a domain class object, with the definition of the center grid
            cells coordinates, as well as corners


    """
    # Print some explanation
    debug(__doc__)

    # For the purpose of demonstration, the domain dimensions are specified by default
    # in input_arguments.
    # Individual arguments can be modified manually in the yaml
    lon_min = tracer.lon_min
    lon_max = tracer.lon_max
    lat_min = tracer.lat_min
    lat_max = tracer.lat_max
    nlon = tracer.nlon
    nlat = tracer.nlat

    debug("if lon and lat are flat vectors in the definition, "
          "convert into a grid with:\n"
          "zlon, zlat = np.meshgrid(lon, lat)\n")

    # Some explanations
    debug(
        'Here, read the vertical information, from the same file as the horizontal '
        'information or from another.\n'
        'Get the number of vertical levels.\n'
        'Get or deduce the sigma_a/sigma_b coefficients from bottom to top if the '
        'vertical '
        'extension is in pressure.\n'
        'It is possible to specify the vertical extension in m a.g.l. as well by '
        'defining the variable heights'
    )
    nlev = tracer.nlev
    punit = "Pa"
    sigma_a = np.linspace(0, 1, nlev)
    sigma_b = np.linspace(1, 0, nlev)

    # Initializes domain
    setup = Setup.from_dict(
        {
            "domain": {
                "plugin": {
                    "name": "dummy",
                    "version": "std",
                    "type": "domain",
                },
                "xmin": lon_min,    # minimum longitude for centers
                "xmax": lon_max,    # maximum longitude for centers
                "ymin": lat_min,    # minimum latitude for centers
                "ymax": lat_max,    # maximum latitude for centers
                "nlon": nlon,       # number of longitudinal cells
                "nlat": nlat,       # number of latitudinal cells
                "nlev": nlev,      # number of vertical levels
                "sigma_a": sigma_a,
                "sigma_b": sigma_b,
                "pressure_unit": "Pa" # adapted to sigmas
            }
        }
    )

    Setup.load_setup(setup, level=1)

    return setup.domain