# Domains `domain`

#

## Available Domains `domain`

#

The following `domains`

are implemented in pyCIF so far:

## Documentation#

### Description#

The `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 `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 `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 `create_domain`

or `read_grid`

:

`unstructured_domain`

:(optional) this parameter is set to

`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 here)

The vertical definition of the domain is used for vertical interpolations in the corresponding transform (see details 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:

```
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.

`read_grid`

is a class method that applies to the `domain`

plugin itself.
Therefore, the only expected argument is `self`

.

```
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 `read_grid`

function for the model CHIMERE.

##### 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 `create_domain`

function for the model CHIMERE.

##### 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: