gnome.environment

environment module

Submodules

• gnome.environment.environment
• gnome.environment.environment_objects
• gnome.environment.grid
• gnome.environment.gridcur
• gnome.environment.gridded_objects_base
• gnome.environment.names
• gnome.environment.running_average
• gnome.environment.tide
• gnome.environment.timeseries_objects_base
• gnome.environment.water
• gnome.environment.waves
• gnome.environment.wind

Package Contents

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 class for assigning a unique ID for an object
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 class for assigning a unique ID for an object
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.

Attributes

base_classes
helper_functions
env_objs
schemas
ts_property
__all__

class gnome.environment.Environment(make_default_refs=True, **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 –

abstract property data_start

abstract property data_stop

_subclasses = []

_ref_as = 'environment'

__metaclass__

abstract at(points, time, units=None)

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

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

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

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

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

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'}

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

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.

property units

_ref_as = 'water'

_field_descr

_schema

_units_type

_gnome_units

__str__

__repr__()

Return repr(self).

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

static _get_density(salinity, temp, temp_units)

use lru cache so we don’t recompute if temp is not changing

_convert_sediment_units(from_, to)

used internally to convert to/from sediment 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

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

_ref_as = 'waves'

_req_refs = ['wind', 'water']

_schema

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

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:

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

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

property extrapolation_is_allowed

property data_start

property data_stop

property yeardata

_ref_as = 'tide'

_schema

scale_factor

_obj_to_create(filename)

open file, read a few lines to determine if it is an ossm file or a shio file

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 –

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

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

_ref_as = 'wind'

_gnome_unit = 'm/s'

_schema

valid_vel_units

update_from_dict(dict_, refs=None)

_check_units(units)

Checks the user provided units are in list Wind.valid_vel_units

__repr__()

Return repr(self).

new_set_timeseries(value, coord_sys)

_convert_units(data, coord_sys, from_unit, to_unit)

method to convert units for the ‘value’ stored in the date/time value pair

_write_timeseries_to_zip(saveloc, ts_name)

use a StringIO type of file descriptor and write directly to zipfile

_write_timeseries_to_file(datafile)

write timeseries data to file

_write_timeseries_to_fd(fd)

Takes a general file descriptor as input and writes data to it.

Writes the “OSSM format” with the full header

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, coord_sys='uv', units=None, extrapolate=False, _auto_align=True)

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.

__eq__(other)

invoke super to check equality for all ‘save’ parameters. Also invoke __eq__ for Timeseries object to check equality of timeseries. Super is not used in any of the __eq__ methods

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’

property past_hours_to_average

property timeseries

_schema

__repr__()

Return repr(self).

__str__()

Return str(self).

_convert_to_time_value_pair(datetime_value_2d)

fmt datetime_value_2d so it is a numpy array with dtype=basic_types.time_value_pair as the C++ code expects

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

property timeseries

Creates a representation of the time series

Return type:

list of (datetime, double) tuples

property data

property time

_schema

_gnome_unit

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

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

property time

Time axis of data. I

Return type:

gnome.environment.property.Time

property units

Units of underlying data

Return type:

string

property varnames

Names of underlying variables

Return type:

[] of strings

_schema

_gnome_unit

abstract _check_consistency()

Checks that the attributes of each GriddedProp in varlist are the same as the GridVectorProp

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

static _get_grid_type(*args, **kwargs)

class gnome.environment.VectorVariable(extrapolation_is_allowed=False, *args, **kwargs)

Bases: gridded.VectorVariable, gnome.gnomeobject.GnomeId

A class for assigning a unique ID for an object

property extrapolation_is_allowed

property data_start

property data_stop

_schema

_default_component_types

_gnome_unit

__repr__()

Return repr(self).

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

• 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

classmethod from_netCDF(*args, **kwargs)

create a new VectorVariable object from a netcdf file

See init_from_netcdf for signature

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, *args, **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()

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

classmethod _get_shared_vars(*sh_args)

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

Bases: gridded.Variable, gnome.gnomeobject.GnomeId

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)

property extrapolation_is_allowed

property data_start

property data_stop

_schema

default_names = []

cf_names = []

_default_component_types

_gnome_unit

__repr__()

Return repr(self).

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, *args, **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)

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)

property grid_type

_schema

extrapolate

time_offset

__repr__()

Return repr(self).

__str__()

Return str(self).

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

gnome.environment.__all__