gnome.environment.environment_objects

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 base class for all classes in environment module.
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 base class for all classes in environment module.
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

Module Contents

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

data_start

data_stop

units = 'm/s'

property speed

property direction

property u

property v

at(points, time, *, units=None, extrapolate=None, **kwargs)

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

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.

property timeseries

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

Bases: gnome.environment.gridded_objects_base.VectorVariable

A base class for all classes in environment module. This is primarily to define a dtype such that the OrderedCollection defined in the Model object requires it.

Parameters:

angle (gridded_objects_base.Variable or None) – scalar field of cell rotation angles (for rotated/distorted grids)

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

get_data_vectors()

return array of shape (2, time_slices, len_linearized_data)

get_bounds()

Return a bounding box surrounding the grid data.

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

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

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 = ['water_t', 'temp']

cf_names = ['sea_water_temperature', 'sea_surface_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

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 = ['salt']

cf_names = ['sea_water_salinity', 'sea_surface_salinity']

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

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

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 = ['sand_06']

class gnome.environment.environment_objects.IceConcentration(*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)

default_names = ['ice_fraction', 'aice']

cf_names = ['sea_ice_area_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)

default_names = ['h']

cf_names = ['depth']

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

Bases: VelocityGrid

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 (gridded_objects_base.Variable or None) – scalar field of cell rotation angles (for rotated/distorted grids)

default_names

cf_names

at(points, time, *, units=None, extrapolate=None, **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

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 (gridded_objects_base.Variable or None) – scalar field of cell rotation angles (for rotated/distorted grids)

default_names

cf_names

wet_dry_mask = None

at(points, time, *, units=None, extrapolate=None, 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) – Array of coordinates [(lon0, lat0), (lon1, lat1), …] 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=None, _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.

  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.

  [[Lon1, Lat1, Z1],
   [Lon2, Lat2, Z2],
   [Lon3, Lat3, Z3],
   ...]
  

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

• lats – 1D iterable of latitude values. This is ignored if points is provided

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

A base class for all classes in environment module. This is primarily to define a dtype such that the OrderedCollection defined in the Model object requires it.

Parameters:

angle (gridded_objects_base.Variable or None) – scalar field of cell rotation angles (for rotated/distorted grids)

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

ice_velocity = None

ice_concentration = None

classmethod from_netCDF(*args, **kwargs)

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

Parameters:

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

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

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

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

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

• varnames ([] of string. Order of the names in the list would be order of vector components) – Names of the variables in the data source file

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

• name (string) – Name of property

• units (string) – Units

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

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

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

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

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

• varnames ([] of string. Order of the names in the list would be order of vector components) – Names of the variables in the data source file

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

• name (string) – Name of property

• units (string) – Units

at(points, time, *, units=None, extrapolate=None, **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 (gridded_objects_base.Variable or None) – scalar field of cell rotation angles (for rotated/distorted grids)

ice_concentration = None

classmethod from_netCDF(ice_concentration=None, **kwargs)

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

Parameters:

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

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

• data_file (string) – Name of data source file

• grid_file (string) – Name of grid source file

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

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

• varnames ([] of string. Order of the names in the list would be order of vector components) – Names of the variables in the data source file

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

• name (string) – Name of property

• units (string) – Units

at(points, time, *, units=None, extrapolate=None, min_val=0, **kwargs)

Parameters:

min_val (float) – Minimum value for wind speed. If computed wind speed is less than this value, it will be set to this value.

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 (gridded_objects_base.Variable or None) – scalar field of cell rotation angles (for rotated/distorted grids)

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