gnome.environment.environment_objects

Module Contents

Classes

SteadyUniformCurrent	Simple current: the same at all time and places
VelocityTS	Base class for multiple data sources aligned along the same single time dimension
VelocityGrid	A class for assigning a unique ID for an object
WindTS	Base class for multiple data sources aligned along the same single time dimension
CurrentTS	Base class for multiple data sources aligned along the same single time dimension
TemperatureTS	Base class for data with a single dimension: time
GridTemperature	Variable object: represents a field of values associated with the grid.
SalinityTS	Base class for data with a single dimension: time
GridSalinity	Variable object: represents a field of values associated with the grid.
WaterDensityTS	Base class for data with a single dimension: time
GridSediment	Variable object: represents a field of values associated with the grid.
IceConcentration	Variable object: represents a field of values associated with the grid.
Bathymetry	Variable object: represents a field of values associated with the grid.
GridCurrent	GridCurrent is VelocityGrid that adds specific stuff for currents:
GridWind	Gridded winds -- usually from netcdf files from meteorological models.
LandMask	This class depends on gridded features not yet finalized so it likely non-functional
IceVelocity	A class for assigning a unique ID for an object
IceAwareCurrent	IceAwareCurrent is a GridCurrent that modulates the usual water velocity field
IceAwareWind	Gridded winds -- usually from netcdf files from meteorological models.
FileGridCurrent	class that presents an interface for GridCurrent loaded from

class gnome.environment.environment_objects.SteadyUniformCurrent(speed, direction, units='m/s', name='Steady Uniform Current')

Bases: gnome.environment.environment.Environment

Simple current: the same at all time and places

Create a steady, uniform current (same at all time and places)

Parameters:

• speed – speed of the current

• direction – direction of the current (direction to, not from), in degrees from north

• units="m/s" – units of speed: defaults to “m/s”

• Current" (name="Steady Uniform) – optional name for the current

property speed

property direction

property u

property v

_ref_as = 'current'

_schema

data_start

data_stop

__repr__()

Return repr(self).

_set_uv()

at(points, time, units=None)

Find the value of the property at positions of points at time T

Parameters:

• points – will be ignored

• time – will be ignored

• units='m/s' – units the values will be returned in (or converted to) if None, the default units for the environment type will be used.

Returns:

returns an Nx2 arrary is points is Nx2, Nx3 is points is Nx3

class gnome.environment.environment_objects.VelocityTS(variables=None, time=None, units=None, *args, **kwargs)

Bases: gnome.environment.timeseries_objects_base.TimeseriesVector

Base class for multiple data sources aligned along the same single time dimension

A class that represents a vector natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time.

Parameters:

• name (string) – Name of the Property

• units (string) – Unit of the underlying data

• time ([] of datetime.datetime, netCDF4.Variable, or Time object) – Time axis of the data

• variables ([] of TimeseriesData or numpy.array (Max len=2)) – component data arrays

property timeseries

_gnome_unit = 'm/s'

classmethod constant(name='', speed=0, direction=0, units='m/s')

utility to create a constant wind “timeseries”

Parameters:

• speed – speed of wind

• direction – direction – degrees True, direction wind is from (degrees True)

• units='m/s' – units for speed, as a string, i.e. “knots”, “m/s”, “cm/s”, etc.

Note

The time for a constant wind timeseries is irrelevant. This function simply sets it to datetime.now() accurate to hours.

class gnome.environment.environment_objects.VelocityGrid(angle=None, **kwargs)

Bases: gnome.environment.gridded_objects_base.VectorVariable

A class for assigning a unique ID for an object

Parameters:

angle – scalar field of cell rotation angles (for rotated/distorted grids)

_gnome_unit = 'm/s'

comp_order = ['u', 'v', 'w']

get_data_vectors()

return array of shape (2, time_slices, len_linearized_data) first is magnitude, second is direction

class gnome.environment.environment_objects.WindTS(name=None, units=None, time=None, variables=None, **kwargs)

Bases: VelocityTS, gnome.environment.environment.Environment

Base class for multiple data sources aligned along the same single time dimension

A class that represents a vector natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time.

Parameters:

• name (string) – Name of the Property

• units (string) – Unit of the underlying data

• time ([] of datetime.datetime, netCDF4.Variable, or Time object) – Time axis of the data

• variables ([] of TimeseriesData or numpy.array (Max len=2)) – component data arrays

_ref_as = 'wind'

classmethod constant_wind(name='Constant Wind', speed=None, direction=None, units='m/s')

Parameters:

• speed – speed of wind

• direction – direction – degrees True, direction wind is from (degrees True)

• unit='m/s' – units for speed, as a string, i.e. “knots”, “m/s”, “cm/s”, etc.

class gnome.environment.environment_objects.CurrentTS(name=None, units=None, time=None, variables=None, **kwargs)

Bases: VelocityTS, gnome.environment.environment.Environment

Base class for multiple data sources aligned along the same single time dimension

A class that represents a vector natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time.

Parameters:

• name (string) – Name of the Property

• units (string) – Unit of the underlying data

• time ([] of datetime.datetime, netCDF4.Variable, or Time object) – Time axis of the data

• variables ([] of TimeseriesData or numpy.array (Max len=2)) – component data arrays

classmethod constant_current(name='Constant Current', speed=None, direction=None, units='m/s')

Parameters:

• speed – speed of current

• direction – direction – degrees True, direction current is going (degrees True)

• unit='m/s' – units for speed, as a string, i.e. “knots”, “m/s”, “cm/s”, etc.

class gnome.environment.environment_objects.TemperatureTS(name=None, units='K', time=None, data=None, **kwargs)

Bases: gnome.environment.timeseries_objects_base.TimeseriesData, gnome.environment.environment.Environment

Base class for data with a single dimension: time

A class that represents a natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. EnvProp is the base class, and returns only a single value regardless of the time.

Parameters:

• name (string) – Name

• units (string) – Units

• time ([] of datetime.datetime, netCDF4.Variable, or Time object) – Time axis of the data

• data (array-like) – Value of the property

_gnome_unit = 'K'

classmethod constant_temperature(name='Constant Temperature', temperature=None, units='K')

class gnome.environment.environment_objects.GridTemperature(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs)

Bases: gnome.environment.gridded_objects_base.Variable, gnome.environment.environment.Environment

Variable object: represents a field of values associated with the grid.

Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model.

This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid.

It holds a reference to its own grid object, and its data.

This class represents a value defined on a grid

Parameters:

• name (string) – Name

• units (string) – Units

• time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source

• grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

• varname (string) – Name of the variable in the data source file

• fill_value – the fill value used for undefined data

• location (str) – location on the grid – possible values depend on the grid type

• attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

default_names

cf_names

_gnome_unit = 'K'

_default_unit_type = 'Temperature'

class gnome.environment.environment_objects.SalinityTS(data=None, time=None, units=None, extrapolate=True, *args, **kwargs)

Bases: gnome.environment.timeseries_objects_base.TimeseriesData, gnome.environment.environment.Environment

Base class for data with a single dimension: time

A class that represents a natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. EnvProp is the base class, and returns only a single value regardless of the time.

Parameters:

• name (string) – Name

• units (string) – Units

• time ([] of datetime.datetime, netCDF4.Variable, or Time object) – Time axis of the data

• data (array-like) – Value of the property

_gnome_unit = 'ppt'

classmethod constant_salinity(name='Constant Salinity', salinity=None, units='ppt')

class gnome.environment.environment_objects.GridSalinity(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs)

Bases: gnome.environment.gridded_objects_base.Variable, gnome.environment.environment.Environment

Variable object: represents a field of values associated with the grid.

Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model.

This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid.

It holds a reference to its own grid object, and its data.

This class represents a value defined on a grid

Parameters:

• name (string) – Name

• units (string) – Units

• time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source

• grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

• varname (string) – Name of the variable in the data source file

• fill_value – the fill value used for undefined data

• location (str) – location on the grid – possible values depend on the grid type

• attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

default_names

cf_names

_gnome_unit = 'ppt'

class gnome.environment.environment_objects.WaterDensityTS(name=None, units='kg/m^3', temperature=None, salinity=None)

Bases: gnome.environment.timeseries_objects_base.TimeseriesData, gnome.environment.environment.Environment

Base class for data with a single dimension: time

A class that represents a natural phenomenon and provides an interface to get the value of the phenomenon at a position in space and time. EnvProp is the base class, and returns only a single value regardless of the time.

Parameters:

• name (string) – Name

• units (string) – Units

• time ([] of datetime.datetime, netCDF4.Variable, or Time object) – Time axis of the data

• data (array-like) – Value of the property

_gnome_unit = 'kg/m^3'

class gnome.environment.environment_objects.GridSediment(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs)

Bases: gnome.environment.gridded_objects_base.Variable, gnome.environment.environment.Environment

Variable object: represents a field of values associated with the grid.

Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model.

This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid.

It holds a reference to its own grid object, and its data.

This class represents a value defined on a grid

Parameters:

• name (string) – Name

• units (string) – Units

• time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source

• grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

• varname (string) – Name of the variable in the data source file

• fill_value – the fill value used for undefined data

• location (str) – location on the grid – possible values depend on the grid type

• attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

_gnome_unit = 'ppt'

default_names

class gnome.environment.environment_objects.IceConcentration(*args, **kwargs)

Bases: gnome.environment.gridded_objects_base.Variable, gnome.environment.environment.Environment

Variable object: represents a field of values associated with the grid.

Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model.

This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid.

It holds a reference to its own grid object, and its data.

This class represents a value defined on a grid

Parameters:

• name (string) – Name

• units (string) – Units

• time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source

• grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

• varname (string) – Name of the variable in the data source file

• fill_value – the fill value used for undefined data

• location (str) – location on the grid – possible values depend on the grid type

• attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

_ref_as = ['ice_concentration', 'ice_aware']

default_names

cf_names

_gnome_unit = 'fraction'

class gnome.environment.environment_objects.Bathymetry(extrapolation_is_allowed=False, surface_boundary_condition='extrapolate', bottom_boundary_condition='mask', *args, **kwargs)

Bases: gnome.environment.gridded_objects_base.Variable

Variable object: represents a field of values associated with the grid.

Abstractly, it is usually a scalar physical property such a temperature, salinity that varies over a the domain of the model.

This more or less maps to a variable in a netcdf file, but does not have to come form a netcdf file, and this provides and abstraction where the user can access the value in world coordinates, interpolated from the grid.

It holds a reference to its own grid object, and its data.

This class represents a value defined on a grid

Parameters:

• name (string) – Name

• units (string) – Units

• time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source

• grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

• varname (string) – Name of the variable in the data source file

• fill_value – the fill value used for undefined data

• location (str) – location on the grid – possible values depend on the grid type

• attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

_gnome_unit = 'm'

default_names

cf_names

class gnome.environment.environment_objects.GridCurrent(angle=None, **kwargs)

Bases: VelocityGrid, gnome.environment.environment.Environment

GridCurrent is VelocityGrid that adds specific stuff for currents:

• Information about how to find currents in netCDF file

• Ability to apply an angle adjustment of grid-aligned currents

• overloading the memorization to memoize the angle-adjusted current.

• add a get_data_vectors() provides magnitude, direction – used to draw the currents in a GUI

loading code for netcdf files for gridded currents, and an interpolation (.at), function that provides caching

Parameters:

angle – scalar field of cell rotation angles (for rotated/distorted grids)

_ref_as = 'current'

_gnome_unit = 'm/s'

default_names

cf_names

at(points, time, *args, **kwargs)

Find the value of the property at positions P at time T

Parameters:

• points (Nx2 or Nx3 array of double) – Coordinates to be queried (P)

• time (datetime.datetime object) – The time at which to query these points (T)

• units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)

• extrapolate (boolean (True or False)) – if True, extrapolation will be supported

Returns:

returns a Nx2 array of interpolated values

Return type:

double

class gnome.environment.environment_objects.GridWind(wet_dry_mask=None, *args, **kwargs)

Bases: VelocityGrid, gnome.environment.environment.Environment

Gridded winds – usually from netcdf files from meteorological models.

This will most often be initialized from netcdf files as:

wind = GridWind.from_netCDF(filename=”a/path/to/a/netcdf_file.nc”)

filename can be:

• An already open netCDF4 Dataset

• A single path to a netcdf file

• A list of paths to a set of netcdf files with timeseries

Parameters:

angle – scalar field of cell rotation angles (for rotated/distorted grids)

_ref_as = 'wind'

_gnome_unit = 'm/s'

default_names

cf_names

at(points, time, coord_sys='uv', _auto_align=True, **kwargs)

Find the value of the property at positions P at time T

Parameters:

• points (Nx2 array of double) – Coordinates to be queried (P)

• time (datetime.datetime object) – The time at which to query these points (T)

• depth (integer) – Specifies the depth level of the variable

• units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)

• extrapolate (boolean (True or False)) – if True, extrapolation will be supported

• coord_sys (string, one of ('uv','u','v','r-theta','r','theta')) – String describing the coordinate system to be used.

Returns:

returns a Nx2 array of interpolated values

Return type:

double

transform_result(value, coord_sys)

get_start_time()

get_end_time()

class gnome.environment.environment_objects.LandMask(*args, **kwargs)

Bases: gnome.environment.gridded_objects_base.Variable

This class depends on gridded features not yet finalized so it likely non-functional

This class represents a value defined on a grid

Parameters:

• name (string) – Name

• units (string) – Units

• time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source

• grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

• varname (string) – Name of the variable in the data source file

• fill_value – the fill value used for undefined data

• location (str) – location on the grid – possible values depend on the grid type

• attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

at(points, time, units=None, extrapolate=False, _hash=None, _mem=True, **kwargs)

Find the value of the property at positions P at time T

Parameters:

• points (Nx3 array of double) – Cartesian coordinates to be queried (P). Lon, Lat required, Depth (Z) is optional Coordinates must be organized as a 2D array or list, one coordinate per row or list element. [[Lon1, Lat1, Z1], [Lon2, Lat2, Z2], [Lon3, Lat3, Z3], ...] Failure to provide point data in this format may cause unexpected behavior If you wish to provide point data using separate longitude and latitude arrays, use the lons= and lats= kwargs.

• time (datetime.datetime object) – The time at which to query these points (T)

• units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)

• extrapolate (boolean (default False)) – if True, extrapolation will be supported

• unmask (boolean (default False)) – if True and return array is a masked array, returns filled array

• surface_boundary_condition (string ('extrapolate' or 'mask', default 'extrapolate')) – specifies how to evaluate points above the depth interval

• bottom_boundary_condition (string ('extrapolate' or 'mask', default 'extrapolate')) – specifies how to evaluate points below the depth interval

• lons (iterable) – 1D iterable of longitude values. This is ignored if points is provided

:param lats 1D iterable of latitude values. This is ignored if points is provided :type lons: iterable

Returns:

returns a Nx1 array of interpolated values

Return type:

double

If time is out of bounds of the time series, and extrapolate is False, a gridded.time.OutOfTimeRangeError is raised.

class gnome.environment.environment_objects.IceVelocity(angle=None, **kwargs)

Bases: VelocityGrid, gnome.environment.environment.Environment

A class for assigning a unique ID for an object

Parameters:

angle – scalar field of cell rotation angles (for rotated/distorted grids)

_ref_as = ['ice_velocity', 'ice_aware']

_gnome_unit = 'm/s'

default_names

cf_names

class gnome.environment.environment_objects.IceAwareCurrent(ice_velocity=None, ice_concentration=None, *args, **kwargs)

Bases: GridCurrent

IceAwareCurrent is a GridCurrent that modulates the usual water velocity field using ice velocity and concentration information.

While under 20% ice coverage, queries will return water velocity. Between 20% and 80% coverage, queries will interpolate linearly between water and ice velocity Above 80% coverage, queries will return the ice velocity.

Parameters:

• ice_velocity (VectorVariable or compatible object) – VectorVariable representing surface ice velocity

• ice_concentration (Variable or compatible object) – Variable representing surface ice concentration

_ref_as = ['current', 'ice_aware']

_req_refs

_schema

classmethod from_netCDF(*args, **kwargs)

create a new VectorVariable object from a netcdf file

See init_from_netcdf for signature

init_from_netCDF(ice_file=None, ice_concentration=None, ice_velocity=None, *args, **kwargs)

Allows one-function initialization of a VectorVariable from a file.

Parameters:

• filename (string) – Default data source. Parameters below take precedence

• varnames ([] of string) – Names of the variables in the data source file

• grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names.

• name (string) – Name of property

• units (string) – Units

• time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data

• data (netCDF4.Variable or numpy.array) – Underlying data source

• grid (pysgrid or pyugrid) – Grid that the data corresponds with

• dataset (netCDF4.Dataset) – Instance of open Dataset

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

at(points, time, *args, **kwargs)

Find the value of the property at positions P at time T

Parameters:

• points (Nx2 or Nx3 array of double) – Coordinates to be queried (P)

• time (datetime.datetime object) – The time at which to query these points (T)

• units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)

• extrapolate (boolean (True or False)) – if True, extrapolation will be supported

Returns:

returns a Nx2 array of interpolated values

Return type:

double

class gnome.environment.environment_objects.IceAwareWind(ice_concentration=None, *args, **kwargs)

Bases: GridWind

Gridded winds – usually from netcdf files from meteorological models.

This will most often be initialized from netcdf files as:

wind = GridWind.from_netCDF(filename=”a/path/to/a/netcdf_file.nc”)

filename can be:

• An already open netCDF4 Dataset

• A single path to a netcdf file

• A list of paths to a set of netcdf files with timeseries

Parameters:

angle – scalar field of cell rotation angles (for rotated/distorted grids)

_ref_as = ['wind', 'ice_aware']

_req_refs

_schema

classmethod from_netCDF(ice_concentration=None, ice_velocity=None, **kwargs)

create a new VectorVariable object from a netcdf file

See init_from_netcdf for signature

at(points, time, min_val=0, *args, **kwargs)

Find the value of the property at positions P at time T

Parameters:

• points (Nx2 array of double) – Coordinates to be queried (P)

• time (datetime.datetime object) – The time at which to query these points (T)

• depth (integer) – Specifies the depth level of the variable

• units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)

• extrapolate (boolean (True or False)) – if True, extrapolation will be supported

• coord_sys (string, one of ('uv','u','v','r-theta','r','theta')) – String describing the coordinate system to be used.

Returns:

returns a Nx2 array of interpolated values

Return type:

double

class gnome.environment.environment_objects.FileGridCurrent(filename=None, extrapolation_is_allowed=False, *args, **kwargs)

Bases: GridCurrent

class that presents an interface for GridCurrent loaded from files of various formats

Done as a class to provide a Schema for the persistence system

And to provide a simple interface to making a current from a file.

Parameters:

angle – scalar field of cell rotation angles (for rotated/distorted grids)

_schema

init_from_gridcur(filename, extrapolation_is_allowed, **kwargs)

Wrapper for external initalize function

classmethod new_from_dict(serial_dict)

creates a new object from dictionary

This is base implementation and can be over-ridden by classes using this mixin