gnome.environment¶

environment module

Submodules¶

Attributes¶

`base_classes`
`helper_functions`
`env_objs`
`schemas`
`ts_property`

Classes¶

`Environment`	A base class for all classes in environment module.
`WindTS`	Base class for multiple data sources aligned along the same single time dimension
`GridCurrent`	GridCurrent is VelocityGrid that adds specific stuff for currents:
`GridWind`	Gridded winds -- usually from netcdf files from meteorological models.
`IceVelocity`	A base class for all classes in environment module.
`IceConcentration`	Variable object: represents a field of values associated with the grid.
`GridTemperature`	Variable object: represents a field of values associated with the grid.
`IceAwareCurrent`	IceAwareCurrent is a GridCurrent that modulates the usual water velocity field
`IceAwareWind`	Gridded winds -- usually from netcdf files from meteorological models.
`TemperatureTS`	Base class for data with a single dimension: time
`FileGridCurrent`	class that presents an interface for GridCurrent loaded from
`SteadyUniformCurrent`	Simple current: the same at all time and places
`Water`	Define the environmental conditions for a spill, like water_temperature,
`Waves`	class to compute the wave height for a time series
`Tide`	todo: baseclass called ScaleTimeseries (or something like that)
`Wind`	Provides a "point wind" -- uniform wind over all space
`RunningAverage`	Defines a running average time series for a wind or tide
`TimeseriesData`	Base class for data with a single dimension: time
`TimeseriesVector`	Base class for multiple data sources aligned along the same single time dimension
`PyGrid`	Factory class that generates grid objects. Also handles common
`VectorVariable`	A base class for all classes in environment module.
`Variable`	Variable object: represents a field of values associated with the grid.
`Grid`	Defines a grid for a current or wind

Functions¶

`env_from_netCDF`([filename, dataset, grid_file, ...])	Returns a list of instances of environment objects that can be produced
`ice_env_from_netCDF`([filename])	A short function to generate a list of all the 'ice_aware' classes
`from_gridcur`(filename[, extrapolation_is_allowed])	factory function to make a GridCurrent from a gridcur file
`constant_wind`(speed, direction[, units])	utility to create a constant wind "timeseries"
`wind_from_values`(values[, units])	Creates a Wind object directly from data.

Package Contents¶

class gnome.environment.Environment(make_default_refs=True, *, timezone_offset=TZOffset(), **kwargs)¶

Bases: gnome.gnomeobject.GnomeId

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.

base class for environment objects

Parameters:: name=None

make_default_refs = True¶

array_types¶

property timezone_offset¶

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

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

Parameters:

points (Nx3 numpy array) – Coordinates to be queried (lon, lat, depth)
time (datetime.datetime object) – The time at which to query these points (T)
units=None – units the values will be returned in (or converted to) if None, the default units for the environment type will be used.
extrapolate=False – if True, extrapolation will be supported

Returns:

returns a Nx2 or Nx3 array of interpolated values

Return type:

Nx2 or Nx3 numpy array of values

abstract property data_start¶

abstract property data_stop¶

prepare_for_model_run(model_time)¶: Override this method if a derived environment class needs to perform any actions prior to a model run

prepare_for_model_step(model_time)¶: Override this method if a derived environment class needs to perform any actions prior to a model run

post_model_run()¶: Override this method if a derived environment class needs to perform any actions after a model run is complete (StopIteration triggered)

gnome.environment.env_from_netCDF(filename=None, dataset=None, grid_file=None, data_file=None, _cls_list=None, **kwargs)¶

Returns a list of instances of environment objects that can be produced from a file or dataset. These instances will be created with a common underlying grid, and will interconnect when possible. For example, if an IceAwareWind can find an existing IceConcentration, it will use it instead of instantiating another. This function tries ALL gridded types by default. This means if a particular subclass of object is possible to be built, it is likely that all it’s parents will be built and included as well.

If you wish to limit the types of environment objects that will be used, pass a list of the types using “_cls_list” kwarg

gnome.environment.ice_env_from_netCDF(filename=None, **kwargs)¶: A short function to generate a list of all the ‘ice_aware’ classes for use in env_from_netCDF (this excludes GridCurrent, GridWind, GridTemperature, etc.)

class gnome.environment.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.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 – 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.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 – 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) – 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.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 – scalar field of cell rotation angles (for rotated/distorted grids)

default_names¶

cf_names¶

class gnome.environment.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.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.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.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)

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

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

class gnome.environment.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

gnome.environment.from_gridcur(filename, extrapolation_is_allowed=False, **kwargs)¶

factory function to make a GridCurrent from a gridcur file

Parameters:

filename – name (full path) of the gridcur file to load
extrapolation_is_allowed=False

passes other keyword arguments on to GridCurrent initilizer

class gnome.environment.Water(temperature=300.0, salinity=35.0, sediment=0.005, wave_height=None, fetch=None, units=None, name='Water', **kwargs)¶

Bases: gnome.environment.environment.Environment

Define the environmental conditions for a spill, like water_temperature,

Single values for all all time and space

Defined in a Serializable class since user will need to set/get some of these properties through the client

Includes attributes with a Environment interface:

Temperature Salinity Sediment WaveHeight

Example: water.Temperature.at(points, time, unit)

Assume units are SI for all properties. ‘units’ attribute assumes SI by default. This can be changed, but initialization takes SI.

Units is dict, with some subset of these keys:

{
'temperature': 'K',
'salinity': 'psu',
'sediment': 'kg/m^3',
'wave_height': 'm',
'fetch': 'm',
}

So to set units of temperature to F:

units = {'temperature': 'F'}

temperature = 300.0¶

salinity = 35.0¶

sediment = 0.005¶

wave_height = None¶

fetch = None¶

kinematic_viscosity = 1e-06¶

name = 'Water'¶: define as property in base class so all objects will have a name by default

property units¶

Temperature¶

Salinity¶

Sediment¶

WaveHeight¶

property data_start¶: The Water object doesn’t directly manage a time series of data, so it will not have a data range. We will just return an infinite range for Water.

property data_stop¶

get(attr, unit=None)¶: return value in desired unit. If None, then return the value in SI units. The user_unit are given in ‘units’ attribute and each attribute carries the value in as given in these user_units.

set(attr, value, unit)¶: provide a corresponding set method that requires value and units The attributes can be directly set. This function just sets the desired property and also updates the units dict

property density¶: return the density based on water salinity and temperature. The salinity is in ‘psu’; it is not being converted to absolute salinity units - for our purposes, this is sufficient. Using gsw.rho() internally which expects salinity in absolute units.

class gnome.environment.Waves(wind=None, water=None, **kwargs)¶

Bases: gnome.environment.environment.Environment

class to compute the wave height for a time series

At the moment, it only does a single point, non spatially variable, but may be extended in the future

wind and water must be set before running the model; however, these can be set after object construction

Parameters:

wind (A Wind type, or equivelent) – A wind object to get the wind speed. This should be a moving average wind object.
water (environment.Water object.) – water properties, specifically fetch and wave height

Note

must take **kwargs since base class supports more inputs like ‘name’. The new_from_dict() alternate constructor will invoke __init__ will arguments that supported by baseclass

wind = None¶

water = None¶

validate()¶

All pygnome objects should be able to validate themselves. Many py_gnome objects reference other objects like wind, water, waves. These may not be defined when object is created so they can be None at construction time; however, they should reference valid objects when running in the model. If make_default_refs is True, then object is valid because the model will set these up at runtime. To raise an exception for missing references at runtime, directly call validate_refs(level=’error’)

‘wind’, ‘water’, ‘waves’ attributes also have special meaning. An object containing this attribute references the corresponding object.

Logs warnings:

Returns:: a tuple of length two containing: (a list of messages that were logged, isvalid bool) If any references are missing and make_default_refs is False, object is not valid

property data_start¶: The Waves object doesn’t directly manage a time series of data, so it will not have a data range itself. But it depends upon a Wind and a Water object. The Water won’t have a data range either, but the Wind will. So its data range will be that of the Wind it is associated with.

property data_stop¶

get_value(points, time)¶

return the rms wave height, peak period and percent wave breaking at a given time. Does not currently support location-variable waves.

Parameters:: time (datetime.datetime object) – the time you want the wave data for
Returns:: wave_height, peak_period, whitecap_fraction, dissipation_energy

Units:: wave_height: meters (RMS height) peak_period: seconds whitecap_fraction: unit-less fraction dissipation_energy: not sure!! # fixme!

get_wind_speed(points, model_time, coord_sys='r', fill_value=1.0)¶: Wrapper for the weatherers so they can extrapolate

get_emulsification_wind(points, time)¶

Return the right wind for the wave climate

If a wave height was specified, then you need the greater of the real or pseudo wind.

If not, then you need the actual wind.

The idea here is that if there is a low wind, but the user specified waves, we really want emulsification that makes sense for the waves. But if the actual wind is stronger than that for the wave height give, we should use the actual wind.

fixme: I’m not sure this is right – if we stick with the wave energy: given by the user for dispersion, why not for emulsification?

compute_H(U)¶

pseudo_wind(H)¶

whitecap_fraction(U)¶

mean_wave_period(U)¶

peak_wave_period(points, time)¶

Parameters:: time (datetime.datetime object) – the time you want the wave data for
Returns:: peak wave period (s)

dissipative_wave_energy(H)¶

energy_dissipation_rate(H, U)¶

c_ub = 100 = dimensionless empirical coefficient to correct for non-Law-of-the-Wall results (Umlauf and Burchard, 2003)

u_c = water friction velocity (m/s) sqrt(rho_air / rho_w) * u_a ~ .03 * u_a u_a = air friction velocity (m/s) z_0 = surface roughness (m) (Taylor and Yelland) c_p = peak wave speed for Pierson-Moskowitz spectrum w_p = peak angular frequency for Pierson-Moskowitz spectrum (1/s)

TODO: This implementation should be in a utility function. It should not be part of the Waves management object itself.

class gnome.environment.Tide(filename, yeardata=os.path.join(os.path.dirname(gnome.__file__), 'data', 'yeardata'), scale_factor=None, **kwargs)¶

Bases: gnome.environment.environment.Environment

todo: baseclass called ScaleTimeseries (or something like that) ScaleCurrent Define the tide for a spill

Currently, this internally defines and uses the CyShioTime object, which is a cython wrapper around the C++ Shio object

Tide information can be obtained from a filename or set as a timeseries (timeseries is NOT TESTED YET)

It requires one of the following to initialize:

‘timeseries’ assumed to be in ‘uv’ format (NOT TESTED/IMPLEMENTED OR USED YET)

a ‘filename’ containing a header that defines units amongst other meta data

Parameters:

timeseries (numpy.ndarray with dtype=datetime_value_1d) – numpy array containing tide data
units – units associated with the timeseries data. If ‘filename’ is given, then units are read in from the filename. unit conversion - NOT IMPLEMENTED YET
filename – path to a long wind filename from which to read wind data
yeardata='gnome/data/yeardata/' – path to yeardata used for Shio data.

filename¶

cy_obj¶

property yeardata¶

name¶: define as property in base class so all objects will have a name by default

scale_factor¶

property extrapolation_is_allowed¶

property data_start¶

property data_stop¶

class gnome.environment.Wind(timeseries=None, units=None, filename=None, coord_sys='r-theta', latitude=None, longitude=None, speed_uncertainty_scale=0.0, extrapolation_is_allowed=False, **kwargs)¶

Bases: gnome.utilities.timeseries.Timeseries, gnome.environment.environment.Environment

Provides a “point wind” – uniform wind over all space

Create a uniform Wind object, representing a time series of wind at a single location, applied over all space.

Parameters:

timeseries=None
units=None
filename=None
coord_sys='r-theta'
latitude=None
longitude=None
speed_uncertainty_scale=0.0
extrapolation_is_allowed=False

valid_vel_units¶

updated_at¶

source_id¶

longitude = None¶

latitude = None¶

description¶

speed_uncertainty_scale = 0.0¶

extrapolation_is_allowed = False¶

update_from_dict(dict_, refs=None)¶

property time¶

property timeseries¶: returns entire timeseries in ‘r-theta’ coordinate system in the units in which the data was entered or as specified by units attribute

new_set_timeseries(value, coord_sys)¶

property data_start¶: The start time of the valid data for this wind timeseries

property data_stop¶: The stop time of the valid data for this wind timeseries

property units¶: define units in which wind data is input/output

get_wind_data(datetime=None, units=None, coord_sys='r-theta')¶

Returns the timeseries in the requested coordinate system. If datetime=None, then the original timeseries that was entered is returned. If datetime is a list containing datetime objects, then the value for each of those date times is determined by the underlying C++ object and the timeseries is returned.

The output coordinate system is defined by the strings ‘r-theta’, ‘uv’

Parameters:

datetime (datetime object) – [optional] datetime object or list of datetime objects for which the value is desired
units (string. Uses the nucos module.) – [optional] outputs data in these units. Default is to output data without unit conversion
coord_sys (either string or integer value defined by basic_types.ts_format.* (see cy_basic_types.pyx)) – output coordinate system for the times series: either ‘r-theta’ or ‘uv’

Returns:

numpy array containing dtype=basic_types.datetime_value_2d. Contains user specified datetime and the corresponding values in user specified ts_format

Note

Invokes self._convert_units() to do the unit conversion. Override this method to define the derived object’s unit conversion functionality

todo: return data in appropriate significant digits

set_wind_data(wind_data, units, coord_sys='r-theta')¶

Sets the timeseries of the Wind object to the new value given by a numpy array. The coordinate system for the input data defaults to basic_types.format.magnitude_direction but can be changed by the user. Units are also required with the data.

Parameters:

datetime_value_2d (numpy array of dtype basic_types.datetime_value_2d) – timeseries of wind data defined in a numpy array
units – units associated with the data. Valid units defined in Wind.valid_vel_units list
coord_sys (either string or integer value defined by basic_types.format.* (see cy_basic_types.pyx)) – output coordinate system for the times series, as defined by basic_types.format.

get_value(time)¶

Return the value at specified time and location. Wind timeseries are independent of location; however, a gridded datafile may require location so this interface may get refactored if it needs to support different types of wind data. It returns the data in SI units (m/s) in ‘r-theta’ coordinate system (speed, direction)

Parameters:: time (datetime object or sequence of datetime objects.) – the time(s) you want the data for

Note

It invokes get_wind_data(..) function

at(points, time, *, units=None, extrapolate=None, coord_sys='uv', _auto_align=True, **kwargs)¶

Returns the value of the wind at the specified points at the specified time. Valid coordinate systems include ‘r-theta’, ‘r’, ‘theta’, ‘uv’, ‘u’ or ‘v’. This function is for API compatibility with the new environment objects.

Parameters:

points – Nx2 or Nx3 array of positions (lon, lat, [z]). This may be None: this is a spatially independent wind - value is the same for all points.
time – Datetime of the time to be queried
coord_sys – String describing the coordinate system.

set_speed_uncertainty(up_or_down=None)¶

This function shifts the wind speed values in our time series based on a single parameter Rayleigh distribution method, and scaled by a value in the range [0.0 … 0.5]. This range represents a plus-or-minus percent of uncertainty that the distribution function should calculate

For each wind value in our time series:

We assume it to be the average speed for that sample time
We calculate its respective Rayleigh distribution mode (sigma).
We determine either an upper percent uncertainty or a lower percent uncertainty based on a passed in parameter.
Using the Rayleigh Quantile method and our calculated percent, we determine the wind speed that is just at or above the fractional area under the Probability distribution.
We assign the wind speed to its new calculated value.

Since we are irreversibly changing the wind speed values, we should probably do this only once.

validate()¶: only issues warning - object is always valid

gnome.environment.constant_wind(speed, direction, units='m/s')¶

utility to create a constant wind “timeseries”

Parameters:

speed – speed of wind
direction – direction – direction wind is from (degrees True)
unit='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.

gnome.environment.wind_from_values(values, units='m/s')¶

Creates a Wind object directly from data.

Parameters:

values – list of (datetime, speed, direction) tuples
units='m/s' – speed units.

Direction is the where the wind is coming from in degrees from North

Returns:: A Wind timeseries object that can be used for a wind mover, etc.

class gnome.environment.RunningAverage(wind=None, timeseries=None, past_hours_to_average=3, **kwargs)¶

Bases: gnome.environment.environment.Environment

Defines a running average time series for a wind or tide

Initializes a running average object from a wind and past hours to average

If no wind is given, timeseries gets initialized as:

timeseries = np.zeros((1,), dtype=basic_types.datetime_value_2d)

(note: probably should be an error)

All other keywords are optional. Optional parameters (kwargs):

Parameters:: past_hours_to_average=3 – duration of time average window

Units are always ‘mps’

units = 'mps'¶

format = 'uv'¶

wind = None¶

ossm¶

property past_hours_to_average¶

property timeseries¶

get_timeseries(datetime=None)¶

Returns the timeseries in the requested format. If datetime=None, then the original timeseries that was entered is returned. If datetime is a list containing datetime objects, then the wind value for each of those date times is determined by the underlying CyOSSMTime object and the timeseries is returned.

The output format is defined by the strings ‘r-theta’, ‘uv’

Parameters:: datetime (datetime object) – [optional] datetime object or list of datetime objects for which the value is desired
Returns:: numpy array containing dtype=basic_types.datetime_value_2d. Contains user specified datetime and the corresponding values in ‘m/s’ and ‘uv’ format

prepare_for_model_run(model_time)¶: Make sure we are up to date with the referenced time series

prepare_for_model_step(model_time)¶: Make sure we are up to date with the referenced time series

create_running_average_timeseries(past_hours_to_average, model_time=0)¶

Creates the timeseries of the RunningAverage object

Parameters:: past_hours_to_average – amount of data to use in the averaging

get_value(time)¶: Return the value at specified time and location. Timeseries are independent of location; however, a gridded datafile may require location so this interface may get refactored if it needs to support different types of data. It assumes the data in SI units (m/s) and ‘uv’ format

Note

It invokes get_timeseries(..) function

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

Bases: gnome.gnomeobject.GnomeId

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

units = None¶

property data¶

property time¶

extrapolate = True¶

classmethod constant(name=None, units=None, data=None)¶

property timeseries¶

Creates a representation of the time series

Return type:: list of (datetime, double) tuples

at(points, time, *, units=None, extrapolate=False, auto_align=True, **kwargs)¶

Interpolates this property to the given points at the given time with the units specified.

Parameters:

points – A Nx2 array of lon,lat points
time – A datetime object. May be None; if this is so, the variable is assumed to be gridded but time-invariant
units – The units that the result would be converted to

in_units(unit)¶

Returns a full cpy of this property in the units specified. WARNING: This will cpy the data of the original property!

Parameters:: units (string) – Units to convert to
Returns:: Copy of self converted to new units
Return type:: Same as self

is_constant()¶

class gnome.environment.TimeseriesVector(variables=None, time=None, units=None, *args, **kwargs)¶

Bases: gnome.gnomeobject.GnomeId

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

variables = None¶

property units¶

Units of underlying data

Return type:: string

property time¶

Time axis of data. I

Return type:: gnome.environment.property.Time

property varnames¶

Names of underlying variables

Return type:: [] of strings

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

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

TODO: What are the argument names for time and time level really?

Parameters:

points (Nx2 array of double) – Coordinates to be queried (P)
time (integer) – The time at which to query these points (T)
time – Specifies the time 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

Returns:

returns a Nx2 array of interpolated values

Return type:

double

class gnome.environment.PyGrid¶

Bases: gridded.grids.Grid

Factory class that generates grid objects. Also handles common loading and parsing operations

Init common to all Grid types. This constructor will take all the kwargs of both pyugrid.UGrid and pysgrid.SGrid. See their documentation for details

Parameters:: filename – Name of the file this grid was constructed from, if available.

static from_netCDF(*args, **kwargs)¶

Parameters:

filename – File containing a grid
dataset – Takes precedence over filename, if provided.
grid_type – Must be provided if Dataset does not have a ‘grid_type’ attribute, or valid topology variable
grid_topology – A dictionary mapping of grid attribute to variable name. Takes precedence over discovered attributes
kwargs – All kwargs to SGrid, UGrid, or RGrid are valid, and take precedence over all.

Returns:

Instance of Grid_U, Grid_S, or Grid_R

static new_from_dict(dict_)¶

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

Bases: gridded.VectorVariable, gnome.environment.environment.Environment

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.

base class for environment objects

Parameters:: name=None

property extrapolation_is_allowed¶

init_from_netCDF(filename=None, varnames=None, grid_topology=None, name=None, units=None, time=None, time_origin=None, grid=None, depth=None, data_file=None, grid_file=None, dataset=None, load_all=False, variables=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

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

classmethod new_from_dict(dict_, **kwargs)¶

creates a new object from dictionary

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

classmethod constant(values, name=None, units=None)¶

Sets a VectorVariable up to represent a constant vector field. The result will return a constant value for all times and places.

Parameters:: values (array-like) – vector of values

at(points, time, *, units=None, extrapolate=None, unmask=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
zero_ref (string 'absolute' or 'relative') – Specifies whether the zero datum moves with zeta or not. Only applicable if depth dimension is present with full sigma layers
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:: NxM array of interpolated values N = len(points) M = len(self.variables)
Return type:: np.array or np.ma.MaskedArray

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

get_grid_lines()¶

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

get_metadata()¶

property data_start¶

property data_stop¶

save(saveloc='.', refs=None, overwrite=True)¶

Save the variable object to a netcdf file.

Parameters:: filepath (string) – path to file you want o save to. or a writable netCDF4 Dataset An existing one If a path, an existing file will be clobbered.

Follows the convention established by the netcdf UGRID working group:

http://ugrid-conventions.github.io/ugrid-conventions

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

Bases: gridded.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 = []¶

property extrapolation_is_allowed¶

init_from_netCDF(filename=None, dataset=None, data_file=None, grid_file=None, varname=None, grid_topology=None, name=None, units=None, time=None, time_origin=None, grid=None, depth_index=None, depth=None, location=None, load_all=False, fill_value=0, **kwargs)¶

Initialize a Variable from a netcdf file.

This is use in subclasses, to it can be done after object creation

Parameters:

filename (string) – Default data source. Has lowest priority. If dataset, grid_file, or data_file are provided, this function uses them first
varname (string) – Explicit name of the data in the data source file. Equivalent to the key used to look the item up directly eg ‘ds[“lon_u”]’ for a netCDF4 Dataset.
grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names that hold the grid.
name (string) – Name of this object (GNome Object name)
units (string) – string such as ‘m/s’
time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data. May be a constructed gridded.Time object, or collection of datetime.datetime objects
data (netCDF4.Variable or numpy.array) – Underlying data object. May be any array-like, including netCDF4 Variable, etc
grid (pysgrid or pyugrid) – Grid that the data corresponds to
location (string) – The feature where the data aligns with the grid. e.g. “node”, “face”
depth (Depth, S_Depth or L_Depth) – Depth axis object from gridded.depth
dataset (netCDF4.Dataset) – Instance of open netCDF4.Dataset
data_file (string) – Name of data source file, if data and grid files are separate
grid_file (string) – Name of grid source file, if data and grid files are separate
extrapolation_is_allowed

classmethod from_netCDF(*args, **kwargs)¶

create a new variable object from a netcdf file

See init_from_netcdf for signature

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

classmethod new_from_dict(dict_)¶

creates a new object from dictionary

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

classmethod constant(value, **kwargs)¶

property data_start¶

property data_stop¶

save(saveloc='.', refs=None, overwrite=True)¶

Save object state as json to user specified saveloc

Parameters:

saveloc –
A directory, file path, open zipfile.ZipFile, or None. If a directory, it will place the zip file there, overwriting if specified.

If a file path, it will write the file there as follows:

If the file does not exist, it will create the zip archive there. If the saveloc is a zip file or zipfile.Zipfile object and overwrite is False, it will append there. Otherwise, it will overwrite the file if allowed.

If set to None, this function will instead return an open zipfile.Zipfile object linked to a temporary file. The zip file will be named [object.name].zip if a directory is specified
refs – dictionary of references to objects
overwrite – If True, overwrites the file at the saveloc

Returns (obj_json, saveloc, refs):

obj_json is the json that is written to this object’s file in the zipfile. For example if saving a Model named Model1, obj_json will contain the contents of the Model1.json in the save file.

saveloc will be the string path passed in EXCEPT if None was passed in. In this case, it will be an open zipfile.ZipFile based on a temporary file.

refs will be a dict containing all the objects that were saved in the save file, keyed by object id. It will also contain the reference to the object that called .save itself.

class gnome.environment.Grid(filename, topology_file=None, grid_type=1, extrapolate=False, time_offset=0, **kwargs)¶

Bases: gnome.environment.environment.Environment

Defines a grid for a current or wind

Initializes a grid object from a file and a grid type.

Maybe allow a grid to be passed in eventually, otherwise filename required

All other keywords are optional. Optional parameters (kwargs):

Parameters:: grid_type – default is 1 - regular grid (eventually figure this out from file)

filename¶

topology_file = None¶

property grid_type¶

extrapolate¶

time_offset¶

prepare_for_model_run(model_time)¶: Not sure we need to do anything here

prepare_for_model_step(model_time)¶: Make sure we have the right data loaded

get_value(time, location)¶: Return the value at specified time and location.

get_values(model_time, positions, velocities)¶: Return the values for the given positions

serialize(json_='webapi')¶: Returns a json serialization of this object (“webapi” mode only)

classmethod deserialize(json_)¶

classmethod takes json structure as input, deserializes it using a colander schema then invokes the new_from_dict method to create an instance of the object described by the json schema.

We also need to accept sparse json objects, in which case we will not treat them, but just send them back.

gnome.environment.base_classes¶

gnome.environment.helper_functions¶

gnome.environment.env_objs¶

gnome.environment.schemas¶

gnome.environment.ts_property¶