LocStream

class ESMF.api.locstream.LocStream(*args, **kwargs)

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 location stream (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.

For more information about the ESMF LocStream class, please see the ESMF LocStream documentation.

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 ESMF.
lower_bounds
Return type:int
Returns:The lower bounds of the LocStream.
name
Return type:str
Returns:The name of the LocStream.
rank
Return type:int
Returns:The rank of the LocStream.
size
Return type:int
Returns:The size of the LocStream.
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.