LocStream

class esmpy.api.locstream.LocStream(location_count, coord_sys=None, name=None, esmf=True)

The LocStream class is a Python wrapper object for the ESMF LocStream. LocStream is a derived type of a Python dictionary.

The individual values of all key arrays are referenced to those of the underlying Fortran ESMF object.

A LocStream is used to represent the locations of a set of data points. The values of the data points are stored within a Field created using the LocStream.

In the data assimilation world, location streams can be thought of as a set of observations. Their locations are generally described using Cartesian (x, y, z), or (lat, lon, height) coordinates. There is no assumption of any regularity in the positions of the points. To make the concept more general, the locations for each data point are represented using a construct called keys. Keys can include other descriptors besides location, including a second set of coordinates.

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

LocStream follows standard dictionary syntax. For example:

>>> locstream["ESMF:X"] = [1, 2, 3]
>>> x = locstream["ESMF:X"]
>>> locstream["ESMF:Y"] = [1, 2, 3]
>>> y = locstream["ESMF:Y"]
>>> locstream["ESMF:Mask"] = [0, 1, 0]
>>> mask = locstream["ESMF:Mask"]

Note

Setting keys of lists of mixed types can result in errors due to type mismatches from the ESMF library.

Note

Mask must be of type I4, and coordinates must by of type R8.

For ESMF to be able to recognize coordinates specified in a LocStream key they need to be named with the appropriate identifiers. The particular identifiers depend on the coordinate system (i.e. coord_sys argument) used to create the LocStream.

The valid values are:

Coordinate System	dimension 1	dimension 2	dimension 3
SPH_DEG	ESMF:Lon	ESMF:Lat	ESMF:Radius
SPH_RAD	ESMF:Lon	ESMF:Lat	ESMF:Radius
CART	ESMF:X	ESMF:Y	ESMF:Z

Parameters:

• location_count (int) – The number of points in this stream.

• coord_sys (CoordSys) – Coordinate system for the location stream. If None, defaults to SPH_DEG.

• name (str) – Optional name for the location stream.

• esmf (bool) – Internal parameter controlling shallow copying by esmpy.

property lower_bounds

Return type:

int

Returns:

The lower bounds of the LocStream.

property name

Return type:

str

Returns:

The name of the LocStream.

property rank

Return type:

int

Returns:

The rank of the LocStream.

property size

Return type:

int

Returns:

The size of the LocStream.

property upper_bounds

Return type:

int

Returns:

The upper bounds of the LocStream.

copy()

Copy a LocStream in an ESMF-safe manner.

Returns:

A LocStream shallow copy.

destroy()

Release the memory associated with a LocStream.