Field

class esmpy.api.field.Field(grid, name=None, typekind=None, staggerloc=None, meshloc=None, ndbounds=None, grid_to_field_map=None)

The Field class is a Python wrapper object for the ESMF Field. The individual values of all data arrays are referenced to those of the underlying Fortran ESMF object.

A Field represents a physical field, such as temperature. The Field class contains distributed and discretized field data, a reference to its associated grid, and metadata. The Field class stores the grid staggering for that physical field. This is the relationship of how the data array of a field maps onto a grid (e.g. one item per cell located at the cell center, one item per cell located at the NW corner, one item per cell vertex, etc.). This means that different Fields which are on the same underlying Grid but have different staggerings can share the same Grid object without needing to replicate it multiple times.

Refer to the Field Class of the ESMF Reference Manual for more information.

The following parameters are used to create a Field from a Grid, Mesh or LocStream.

REQUIRED:

:param Grid/Mesh/LocStream grid: A Grid,

Mesh or LocStream with coordinates allocated on at least one stagger location.

OPTIONAL:

Parameters:

• name (str) – An optional user friendly name for the Field.

• typekind (TypeKind) – Type of the Field data. If None, defaults to R8.

• staggerloc (StaggerLoc) – The stagger location of the Field data, only specify this argument when using a Grid. If None, defaults to CENTER in 2D and CENTER_VCENTER in 3D.

• meshloc (MeshLoc) – The mesh location of the Field data, only specify this argument when using a Mesh if None, defaults to NODE.

• ndbounds (tuple) – The number of entries in an extra Field dimension. This is represented as a single value, a list or a tuple containing the number of entries for each desired extra dimension of the Field. The time dimension must be last, following Fortran indexing conventions.

• grid_to_field_map (ndarray) – numpy array mapping the grid dimension Field index to the field dimension index. Array length must be equal to the grid rank; uses 1-based indexing. If None, defaults to mapping grid indices to the first available field indices.

property all_data

Return type:

A list of ndarrays with an entry for each local DE. (In the typical case of 1 DE per PET, this is a single-element list containing a single ndarray. For this case, see also data.)

Returns:

The data of the Field

property all_lower_bounds

Return type:

A list of ndarrays with an entry for each local DE. (In the typical case of 1 DE per PET, this is a single-element list containing a single ndarray. For this case, see also lower_bounds.)

Returns:

The lower bounds of the Field.

property all_upper_bounds

Return type:

A list of ndarrays with an entry for each local DE. (In the typical case of 1 DE per PET, this is a single-element list containing a single ndarray. For this case, see also upper_bounds.)

Returns:

The upper bounds of the Field.

property data

Return type:

ndarray

Returns:

The data of the Field. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_data.)

property finalized

Return type:

bool

Returns:

Indicate if the underlying ESMF memory for this object has been deallocated.

property grid

Return type:

Grid, Mesh, or LocStream

Returns:

The discretization object upon which the Field is built.

property local_de_count

Return type:

int

Returns:

The number of DEs in the Field on this PET.

property lower_bounds

Return type:

ndarray

Returns:

The lower bounds of the Field. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_lower_bounds.)

property name

Return type:

str

Returns:

the name of the Field.

property ndbounds

Return type:

list

Returns:

The bounds of the extra dimensions in the Field.

property rank

Return type:

int

Returns:

The rank of the Field.

property staggerloc

Return type:

StaggerLoc or MeshLoc

Returns:

The location upon which the Field is built.

property type

Return type:

TypeKind

Returns:

The type of the data in the Field.

property upper_bounds

Return type:

ndarray

Returns:

The upper bounds of the Field. (It is an error to use this property in the uncommon case where there is something other than 1 DE per PET; in that case, use all_upper_bounds.)

property xd

Return type:

int

Returns:

The number of extra (ungridded) dimensions of the Field.

copy()

Copy a Field in an ESMF-safe manner.

Returns:

A Field shallow copy.

destroy()

Release the memory associated with a Field.

get_area()

Initialize an existing Field with the areas of the cells of the underlying Grid or Mesh.

read(filename, variable, timeslice=None)

Read data into an existing Field from a CF-compliant NetCDF file.

Note:

This interface does not currently support reading ungridded dimensions.

REQUIRED:

Parameters:

• filename (str) – The name of the NetCDF file.

• variable (str) – The name of the data variable to read from file.

OPTIONAL:

Parameters:

timeslice (int) – The number of timeslices to read.