gnome.scripting

Scripting package for GNOME with assorted utilities that make it easier to write scripts.

The ultimate goal is to be able to run py_gnome for the “common” use cases with only functionality available in this module

Classes and helper functions are imported from various py_gnome modules (spill, environment, movers etc).

we recommend that this module be used like so:

import gnome.scripting as gs

Then you will have easy access to most of the stuff you need to write py_gnome scripts with, e.g.:

model = gs.Model(start_time="2018-04-12T12:30",
                 duration=gs.days(2),
                 time_step=gs.minutes(15))

model.map = gs.MapFromBNA('coast.bna', refloat_halflife=0.0)

model.spills += gs.surface_point_line_spill(num_elements=1000,
                                            start_position=(-163.75,
                                                            69.75,
                                                            0.0),
                                            release_time="2018-04-12T12:30")

Submodules

• gnome.scripting.time_utils
• gnome.scripting.utilities

Attributes

oil_status_map
now
PointWind
PyCurrentMover
PyWindMover

Classes

Model	PyGnome Model Class
PrintFinder	class to capture stdout so that you can find print statements
MinusInfTime	class representing time from infinity in the past
InfTime	class representing time into infinity
Spill	Models a spill by combining Release and Substance objects
PointLineRelease	The primary spill source class -- a release of floating
PolygonRelease	A release of elements into a set of provided polygons.
NonWeatheringSubstance	A class for assigning a unique ID for an object
GnomeOil	Class to create an oil for use in Gnome
Wind	Provides a "point wind" -- uniform wind over all space
Renderer	Map Renderer
NetCDFOutput	A NetCDFOutput object is used to write the model's data to a NetCDF file.
KMZOutput	class that outputs GNOME results in a kmz format.
OilBudgetOutput	Outputter for the oil budget table
ShapeOutput	class that outputs GNOME results (particles) in a shapefile format.
WeatheringOutput	class that outputs GNOME weathering results on a time step by time step basis
MapFromBNA	A raster land-water map, created from file with polygons in it.
GnomeMap	The very simplest map for GNOME -- all water
FileGridCurrent	class that presents an interface for GridCurrent loaded from
GridCurrent	GridCurrent is VelocityGrid that adds specific stuff for currents:
SteadyUniformCurrent	Simple current: the same at all time and places
GridWind	Gridded winds -- usually from netcdf files from meteorological models.
IceAwareCurrent	IceAwareCurrent is a GridCurrent that modulates the usual water velocity field
IceAwareWind	Gridded winds -- usually from netcdf files from meteorological models.
Tide	todo: baseclass called ScaleTimeseries (or something like that)
Water	Define the environmental conditions for a spill, like water_temperature,
Waves	class to compute the wave height for a time series
IceVelocity	A base class for all classes in environment module.
IceConcentration	Variable object: represents a field of values associated with the grid.
RandomMover	"Random Walk" diffusion mover
RandomMover3D	This mover class inherits from CyMover and contains CyRandomMover3D
PointWindMover	Python wrapper around the Cython wind_mover module.
CatsMover	Base class from which all Python movers/weatherers can inherit
ComponentMover	Base class from which all Python movers/weatherers can inherit
RiseVelocityMover	This mover class inherits from CyMover and contains CyRiseVelocityMover
WindMover	WindMover implemented in Python. Uses the .wind attribute to move particles.
CurrentMover	CurrentMover implemented in Python. Uses the .current attribute to move particles.
IceAwareRandomMover	"Random Walk" diffusion mover
SimpleMover	simple_mover

Functions

make_images_dir([images_dir])	Create output directory for rendered images.
remove_netcdf(netcdf_file)	remove netcdf_file and associated uncertain netcdf file
set_verbose([log_level])	Set the logging system to dump to the console --
asdatetime(dt)	makes sure the input is a datetime.datetime object
seconds([seconds])	returns a datetime.timedelta object representing the specified number of seconds"
minutes([minutes])	returns a datetime.timedelta object representing the specified number of minutes
hours([hours])	returns a datetime.timedelta object representing the specified number of hours
days([days])	returns a datetime.timedelta object representing the specified number of hours"
weeks([weeks])	returns a datetime.timedelta object representing the specified number of weeks"
surface_point_line_spill(num_elements, start_position, ...)	Helper function for a surface spill at a point or over a line.
point_line_spill(num_elements, start_position, ...[, ...])	Helper function to create a spill from a point or line source.
subsurface_spill(num_elements, start_position, ...[, ...])	Helper function returns a Spill object
grid_spill(bounds, resolution, release_time[, ...])	Helper function returns a Grid Spill object
spatial_release_spill(start_positions, release_time[, ...])	Helper function returns a Spill object containing a spatial release
polygon_release_spill(filename[, release_time, ...])	Helper function returns a Spill object containing a polygon release
constant_wind(speed, direction[, units])	utility to create a constant wind "timeseries"
wind_from_values(values[, units])	Creates a Wind object directly from data.
constant_point_wind_mover(speed, direction[, units])	utility function to create a point wind mover with a constant wind
point_wind_mover_from_file(filename, **kwargs)	Creates a wind mover from a wind time-series file (OSM long wind format)
get_datafile(filename)	Looks to see if filename exists in local directory. If it exists,
load_model(filename)	load a model from an existing savefile

Package Contents

class gnome.scripting.Model(name='Model', time_step=timedelta(minutes=15), start_time=round_time(datetime.now(), 3600), duration=timedelta(days=1), weathering_substeps=1, map=None, uncertain=False, cache_enabled=False, mode=None, make_default_refs=True, location=[], environment=[], outputters=[], movers=[], weatherers=[], spills=[], uncertain_spills=[], weathering_activated=False, run_backwards=False, timezone_offset=TZOffset(), **kwargs)

Bases: gnome.gnomeobject.GnomeId

PyGnome Model Class

Initializes a model. All arguments have a default.

Parameters:

• time_step=timedelta(minutes=15) – model time step in seconds or as a timedelta object. NOTE: if you pass in a number, it WILL be interpreted as seconds

• start_time=datetime.now() – start time of model, datetime object. Rounded to the nearest hour.

• duration=timedelta(days=1) – How long to run the model, a timedelta object.

• weathering_substeps=1 – How many weathering substeps to run inside a single model time step.

• map=gnome.map.GnomeMap() – The land-water map.

• uncertain=False – Flag for setting uncertainty.

• cache_enabled=False – Flag for setting whether the model should cache results to disk.

• mode='Gnome' – The runtime ‘mode’ that the model should use. This is a value that the Web Client uses to decide which UI views it should present.

modes

classmethod load_savefile(filename)

Load a model instance from a save file

Parameters:

filename – the filename of the save file – usually a zip file, but can also be a directry with the full contents of a zip file

Returns:

a model instance all set up from the savefile.

environment

movers

weatherers

outputters

spills

property start_time

Start time of the simulation

timezone_offset

weathering_substeps = 1

zipsave = True

make_default_refs = True

location = []

weathering_activated = False

add_weathering(which='standard')

Add the weatherers

Parameters:

which='standard' –

which weatheres to add. Default is ‘standard’, which will add all the standard weathering algorithms if you don’t want them all, you can specify a list: [‘evaporation’, ‘dispersion’].

Options are:

• ’evaporation’

• ’dispersion’

• ’emulsification’

• ’dissolution’: Dissolution,

• ’half_life_weatherer’

see: gnome.weatherers.__init__.py for the full list

reset(**kwargs)

Resets model to defaults – Caution – clears all movers, spills, etc. Takes same keyword arguments as __init__()

rewind()

Rewinds the model to the beginning (start_time)

update_from_dict(dict_, refs=None)

functions in common_object.

property uncertain

Uncertainty attribute of the model. If flag is toggled, rewind model

property uncertain_spills

property run_backwards

Run backwards attribute of the model. If flag is toggled, rewind model

property cache_enabled

If True, then generated data is cached

property has_weathering_uncertainty

property has_weathering

property time_step

time step over which the dynamics is computed

property current_time_step

Current timestep of the simulation

property duration

total duration of the model run

property map

land water map used for simulation

property num_time_steps

Read only attribute computed number of timesteps based on py:attribute:duration and py:attribute:time_step

contains_object(obj_id)

find_by_class(obj, collection, ret_all=False)

Look for an object that isinstance() of obj in specified colleciton. By default, it will return the first object of this type. To get all obects of this type, set ret_all to True

find_by_attr(attr, value, collection, allitems=False)

find first object in collection where the ‘attr’ attribute matches ‘value’. This is primarily used to find ‘wind’, ‘water’, ‘waves’ objects in environment collection. Use the ‘_ref_as’ attribute to search.

# fixme: why don’t we look for wind, water or waves directly?

Ignore AttributeError since all objects in collection may not contain the attribute over which we are searching.

Parameters:

• attr (str) – attribute whose value must match

• value (str) – desired value of the attribute

• collection (OrderedCollection) – the ordered collection in which to search

setup_model_run()

Runs the setup procedure preceding a model run. When complete, the model should be ready to run to completion without additional prep Currently this function consists of the following operations:

1. Set up special objects.

   Some weatherers currently require other weatherers to exist. This step satisfies those requirements

2. Remake collections in case ordering constraints apply (weatherers)

3. Compile array_types and run setup procedure on spills

   array_types defines what data arrays are required by the various components of the model

4. Attach default references

5. Call prepare_for_model_run on all relevant objects

6. Conduct miscellaneous prep items. See section in code for details.

post_model_run()

A place where the model goes through all collections and calls post_model_run if the object has it.

setup_time_step()

sets up everything for the current time_step:

move_elements()

Moves elements:

• loops through all the movers. and moves the elements

• sets new_position array for each spill

• calls the beaching code to beach the elements that need beaching.

• sets the new position

weather_elements()

Weathers elements:

• loops through all the weatherers, passing in the spill_container and the time range

• a weatherer modifies the data arrays in the spill container, so a particular time range should not be run multiple times. It is expected that we are processing a sequence of contiguous time ranges.

• Note: If there are multiple sequential weathering processes, some inaccuracy could occur. A proposed solution is to ‘super-sample’ the model time step so that it will be replaced with many smaller time steps. We’ll have to see if this pans out in practice.

step_is_done()

Loop through movers and weatherers and call model_step_is_done

Remove elements that marked for removal

Output data

write_output(valid, messages=None)

step()

Steps the model forward in time.

NOTE: in theory, it could also go backward with a negative time step, for hindcasting, but that has not been tested.

output_step(isvalid)

release_elements(start_time, end_time)

release elements into the model

Parameters:

• start_time – – beginning of the release

• end_time – – end of the release.

compile_env()

Produces a dictionary of objects that describe the model environmental conditions

Currently, only works with the ‘water’ object because the other environmental phenomena are not compatible yet

next

full_run(rewind=True)

Do a full run of the model.

Parameters:

rewind=True – whether to rewind the model first – if set to false, model will be run from the current step to the end

Returns:

list of outputter info dicts

spills_update_from_dict(value)

invoke SpillContainerPair().update_from_dict

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

save the model state in saveloc. If self.zipsave is True, then a zip archive is created and model files are saved to the archive.

Parameters:

• saveloc="." –

  a directory or filename. If a directory, then either the model is saved into that dir, or a zip archive is created in that dir (with a .gnome extension).

  The file(s) are clobbered when save() is called.

• refs=None – dict of references mapping ‘id’ to a string used for the reference. The value could be a unique integer or it could be a filename. It is up to the creator of the reference list to decide how to reference a nested object.

• overwrite=True

Returns:

references

This overrides the base class save(). Model contains collections and model must invoke save for each object in the collection. It must also save the data in the SpillContainer’s if it is a mid-run save.

classmethod load(saveloc='.', filename=None, refs=None)

Load an instance of this class from an archive or folder

Parameters:

• saveloc – Can be an open zipfile.ZipFile archive, a folder, or a filename. If it is an open zipfile or folder, it must contain a .json file that describes an instance of this object type. If filename is not specified, it will load the first instance of this object discovered. If a filename, it must be a zip archive or a json file describing an object of this type.

• filename – If saveloc is an open zipfile or folder, this indicates the name of the file to be loaded. If saveloc is a filename, is parameter is ignored.

• refs – A dictionary of id -> object instances that will be used to complete references, if available.

merge(model)

merge ‘model’ into self

check_inputs()

check the user inputs before running the model raise an exception if user can’t run the model

todo: check if all spills start after model ends

fixme: This should probably be broken out into its

own module, class, something – with each test independent.

validate()

invoke validate for all gnome objects contained in model todo: should also check wind, water, waves are defined if weatherers are defined

set_make_default_refs(value)

make default refs for all items in (‘weatherers’, ‘movers’, ‘environment’) collections

list_spill_properties()

Convenience method to list properties of a spill that can be retrieved using get_spill_property

Returns:

list of spill simulation attributes

get_spill_property(prop_name, ucert=False)

Convenience method to allow user to look up properties of a spill.

Parameters:

• prop_name (str) – name of property: use model.list_properties() to see all the options.

• ucert (bool) – whether to get it from the uncertainty spill

Returns:

np.array

get_spill_data(target_properties, conditions, ucert=0)

Convenience method to allow user to write an expression to filter raw spill data

Example case:

get_spill_data('position && mass',
               'position > 50 && spill_num == 1 || status_codes == 1'
               )

WARNING: EXPENSIVE! USE AT YOUR OWN RISK ON LARGE num_elements!

Example spill element properties are below. This list may not contain all properties tracked by the model.

‘positions’, ‘next_positions’, ‘last_water_positions’, ‘status_codes’, ‘spill_num’, ‘id’, ‘mass’, ‘age’

add_env(env, quash=False)

gnome.scripting.oil_status_map

gnome.scripting.make_images_dir(images_dir=None)

Create output directory for rendered images. If it already exists, delete all old output files

gnome.scripting.remove_netcdf(netcdf_file)

remove netcdf_file and associated uncertain netcdf file

Give scripts control over deleting the netcdf file before instantiating a new NetCDFOutput object.

gnome.scripting.set_verbose(log_level='info')

Set the logging system to dump to the console – you can see much more what’s going on with the model as it runs

Parameters:

log_level='info' – the level you want your log to show. options are, in order of importance: “debug”, “info”, “warning”, “error”, “critical”.

You will only get the logging messages at or above the level you set. Set to “debug” for everything.

class gnome.scripting.PrintFinder

Bases: object

class to capture stdout so that you can find print statements

This will print the file, line number, and line after a print statement

To use, simply create an instance in your script

PrintFinder()

IF you want to be able to put it back, save it and call:

pf = PrintFinder()

pf.restore()

initialize a PrintFinder object

This captures stdout when it is initialized

stdout

write(content)

The stream write method – intercepts the write to stdout, writes to original stdout, then adds some traceback info.

restore()

sets stdout back to the original

flush()

forwards a flush call on to the original stdout

gnome.scripting.asdatetime(dt)

makes sure the input is a datetime.datetime object

if it already is, it will be passed through.

If not it will attempt to parse a string to make a datetime object.

None will also be passed through silently

gnome.scripting.seconds(seconds=1)

returns a datetime.timedelta object representing the specified number of seconds”

Parameters:

seconds=1

gnome.scripting.minutes(minutes=1)

returns a datetime.timedelta object representing the specified number of minutes

Parameters:

minutes=1

gnome.scripting.hours(hours=1)

returns a datetime.timedelta object representing the specified number of hours

Parameters:

hours=1

gnome.scripting.days(days=1)

returns a datetime.timedelta object representing the specified number of hours”

Parameters:

hours=1

gnome.scripting.weeks(weeks=1)

returns a datetime.timedelta object representing the specified number of weeks”

Parameters:

weeks=1

gnome.scripting.now

class gnome.scripting.MinusInfTime

Bases: object

class representing time from infinity in the past

compares as less than any datetime (or any other object)

isoformat()

class gnome.scripting.InfTime

Bases: object

class representing time into infinity

compares as greater than any datetime (or any other object..)

isoformat()

class gnome.scripting.Spill(on=True, num_elements=1000, amount=0, units='kg', substance=None, release=None, water=None, amount_uncertainty_scale=0.0, **kwargs)

Bases: BaseSpill

Models a spill by combining Release and Substance objects

Spills used by the gnome model. It contains a release object, which releases elements. It also contains a Substance which contains the type of substance spilled and it initializes data arrays to non-default values (non-zero).

Parameters:

• release (derived from Release) – an object defining how elements are to be released

• substance (derived from Substance) – an object defining the substance of this spill. Defaults to NonWeatheringSubstance

Optional parameters (kwargs):

Parameters:

• name (str) – Human-usable Name of this spill

• on=True – Toggles the spill on/off.

• amount=None – mass or volume of oil spilled.

• units=None – must provide units for amount spilled.

• amount_uncertainty_scale=0.0 – scale value in range 0-1 that adds uncertainty to the spill amount. Maximum uncertainty scale is (2/3) * spill_amount.

Note

Define either volume or mass in ‘amount’ attribute and provide appropriate ‘units’.

valid_vol_units

valid_mass_units

on = True

property substance

property num_elements

property units

Default units in which amount of oil spilled was entered by user. The ‘amount’ property is returned in these ‘units’

property amount

water = None

amount_uncertainty_scale = 0.0

frac_coverage = 1.0

property all_array_types

Need to add array types from Release and Substance

property release_time

property end_release_time

property release_duration

property start_position

property end_position

get_mass()

Return the total mass released during the spill.

uncertain_copy()

Returns a deepcopy of this spill for the uncertainty runs

The copy has everything the same, including the spill_num, but it is a new object with a new id.

Not much to this method, but it could be overridden to do something fancier in the future or a subclass.

There are a number of python objects that cannot be deepcopied. - Logger objects

So we copy them temporarily to local variables before we deepcopy our Spill object.

set_amount_uncertainty(up_or_down=None)

This function shifts the spill amount based on a scale value in the range [0.0 … 1.0]. The maximum uncertainty scale value is (2/3) * spill_amount. We determine either an upper uncertainty or a lower uncertainty multiplier. Then we shift our spill amount value based on it.

Since we are irreversibly changing the spill amount value, we should probably do this only once.

rewind()

rewinds the release to original status (before anything has been released).

prepare_for_model_run(timestep)

array_types comes from all the other objects above in the model such as movers, weatherers, etc. The ones from the substance still need to be added

release_elements(sc, start_time, end_time, environment=None)

Releases and partially initializes new LEs Note: this will have to be updated if we allow backwards runs for continuous spills

num_elements_to_release(current_time, time_step)

Determines the number of elements to be released during: current_time + time_step

It invokes the num_elements_to_release method for the the underlying release object: self.release.num_elements_to_release()

Parameters:

• current_time (datetime.datetime) – current time

• time_step (int) – the time step, sometimes used to decide how many should get released.

Returns:

the number of elements that will be released. This is taken by SpillContainer to initialize all data_arrays.

class gnome.scripting.PointLineRelease(release_time=None, start_position=None, num_elements=None, num_per_timestep=None, end_release_time=None, end_position=None, release_mass=0, **kwargs)

Bases: Release

The primary spill source class – a release of floating non-weathering particles, can be instantaneous or continuous, and be released at a single point, or over a line.

Required Arguments:

Parameters:

• release_time (datetime.datetime) – time the LEs are released (datetime object)

• start_position (3-tuple of floats (long, lat, z)) – initial location the elements are released

Optional arguments:

Note

Either num_elements or num_per_timestep must be given. If both are None, then it defaults to num_elements=1000. If both are given a TypeError is raised because user can only specify one or the other, not both.

Parameters:

• num_elements (integer) – total number of elements to be released

• num_per_timestep – fixed number of LEs released at each timestep

• end_release_time=None – optional – for a time varying release, the end release time. If None, then release is instantaneous

• end_position=None – optional. For moving source, the end position If None, then release from a point source

• release_mass=0 – optional. This is the mass released in kilograms.

property start_position

property end_position

property is_pointsource

if end_position - start_position == 0, point source otherwise it is a line source

Returns:

True if point source, false otherwise

property centroid

generate_release_timeseries(num_ts, max_release, ts)

Release timeseries describe release behavior as a function of time. _release_ts describes the number of LEs that should exist at time T _pos_ts describes the spill position at time T All use TimeseriesData objects.

rewind()

prepare_for_model_run(ts)

Parameters:

ts – timestep as integer seconds

initialize_LEs(to_rel, sc, start_time, end_time)

Initializes the mass and position for to_rel new LEs. :param data: spill container with data arrays :param to_rel: number of elements to initialize :param start_time: initial time of release :param end_time: final time of release

class gnome.scripting.PolygonRelease(filename=None, features=None, polygons=None, weights=None, thicknesses=None, **kwargs)

Bases: Release

A release of elements into a set of provided polygons.

When X particles are determined to be released, they are into the polygons randomly. For each LE, pick a polygon, weighted by it’s proportional area and place the LE randomly within it. By default the PolygonRelease uses simple area for polygon weighting. Other classes (NESDISRelease for example) may use other weighting functions.

Required Arguments:

Parameters:

• release_time (datetime.datetime) – time the LEs are released (datetime object)

• polygons (list of shapely.Polygon or shapely.MultiPolygon.) – polygons to use in this release

Optional arguments:

Parameters:

• filename (string name of a zip file. Polygons loaded are concatenated after polygons from kwarg) – (optional) shapefile

• weights – (optional) LE placement probability weighting for each polygon. Must be the same length as the polygons kwarg, and must sum to 1. If None, weights are generated at runtime based on area proportion.

• num_elements (integer) – total number of elements to be released

• num_per_timestep – fixed number of LEs released at each timestep

• end_release_time=None – optional – for a time varying release, the end release time. If None, then release is instantaneous

• release_mass=0 – optional. This is the mass released in kilograms.

property filename

property centroid

gen_fc_from_kwargs(kwargs)

property features

property polygons

property thicknesses

property weights

property areas

rewind()

get_polys_as_tris(polys, weights=None)

compute_distribution()

prepare_for_model_run(ts)

Parameters:

ts – timestep as integer seconds

initialize_LEs(to_rel, data, start_time, end_time)

set positions for new elements added by the SpillContainer

Note

this releases all the elements at their initial positions at the end_time

get_polygons()

Returns an array of lengths, and a list of line arrays. The first array sequentially indexes the second array. When the second array is split up using the first array and the resulting lines are drawn, you should end up with a picture of the polygons.

get_metadata()

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

gnome.scripting.surface_point_line_spill(num_elements, start_position, release_time, end_position=None, end_release_time=None, substance=None, amount=0, units='kg', water=None, on=True, windage_range=None, windage_persist=None, name='Surface Point or Line Release')

Helper function for a surface spill at a point or over a line.

Returns a configured Spill object

Parameters:

• num_elements (integer) – total number of elements to be released

• start_position (2-tuple of floats (long, lat)) – initial location the elements are released

• release_time (datetime.datetime) – time the LEs are released (datetime object)

• end_position=None – Optional. For moving source, the end position If None, then release is from a point source

• end_release_time=None – optional – for a time varying release, the end release time. If None, then release is instantaneous

• substance=None – Type of oil spilled.

• amount=None – mass or volume of oil spilled

• units=None – units for amount spilled

• .04) (tuple windage_range=(.01,) – Percentage range for windage. Active only for surface particles when a mind mover is added

• windage_persist=900 – Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale

• Spill' (name='Surface Point/Line) – a name for the spill

gnome.scripting.point_line_spill(num_elements, start_position, release_time, end_position=None, end_release_time=None, substance=None, amount=0, units='kg', water=None, on=True, windage_range=None, windage_persist=None, name='Point-Line Spill')

Helper function to create a spill from a point or line source.

Returns a configured Spill object

Parameters:

• num_elements (integer) – total number of elements to be released

• start_position (3-tuple of floats (long, lat, positive depth) or 2-tuple of floats (lon, lat) in which case depth will default to 0.) – initial location the elements are released

• release_time (datetime.datetime) – time the elements are released

• end_position=None – Optional. For moving source, the end position If None, then release is from a point source

• end_release_time=None – Optional – for a time varying release, the end release time. If None, then the release is instantaneous

• substance=None – Type of oil spilled.

• amount=None – mass or volume of oil spilled

• units=None – units for amount spilled

• .04) (tuple windage_range=(.01,) – Percentage range for windage. Active only for surface particles when a wind mover is added

• windage_persist=900 – Persistence for windage values in seconds. Use -1 for infinite, otherwise it is randomly reset on this time scale

• Spill' (name='Point-Line) – a name for the spill

gnome.scripting.subsurface_spill(num_elements, start_position, release_time, distribution, distribution_type='droplet_size', end_release_time=None, substance=None, amount=0, units='kg', water=None, on=True, windage_range=None, windage_persist=None, name='Subsurface plume')

Helper function returns a Spill object

Parameters:

• num_elements (integer) – total number of elements to be released

• start_position (3-tuple of floats (long, lat, z)) – initial location the elements are released

• release_time (datetime.datetime) – time the LEs are released (datetime object)

• distribution=None – An object capable of generating a probability distribution. Right now, we have: * UniformDistribution * NormalDistribution * LogNormalDistribution * WeibullDistribution

• distribution_type=droplet_size (str) – What is being sampled from the distribution. Options are: * droplet_size - Rise velocity is then calculated * rise_velocity - No droplet size is computed

• end_release_time=None – End release time for a time varying release. If None, then release is instantaneous

• substance=None – Required unless density specified. Type of oil spilled.

• density=None (float) – Required unless substance specified. Density of spilled material.

• density_units='kg/m^3' (str)

• amount=None (float) – mass or volume of oil spilled.

• units=None (str) – must provide units for amount spilled.

• .04) (tuple windage_range=(.01,) – Percentage range for windage. Active only for surface particles when a mind mover is added

• windage_persist=900 – Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale.

• Release' (str name='Subsurface) – a name for the spill.

gnome.scripting.grid_spill(bounds, resolution, release_time, substance=None, amount=1.0, units='kg', on=True, water=None, windage_range=None, windage_persist=None, name='Surface Grid Spill')

Helper function returns a Grid Spill object

Parameters:

• bounds (2x2 numpy array or equivalent) – bounding box of region you want the elements in: ((min_lon, min_lat), (max_lon, max_lat))

• resolution (integer) – resolution of grid – it will be a resoluiton X resolution grid

• substance=None – Type of oil spilled.

• amount=None (float) – mass or volume of oil spilled

• units=None (str) – units for amount spilled

• release_time (datetime.datetime) – time the LEs are released (datetime object)

• .04) (tuple windage_range=(.01,) – Percentage range for windage. Active only for surface particles when a mind mover is added

• windage_persist=900 (int) – Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale

• Release' (str name='Surface Point/Line) – a name for the spill

gnome.scripting.spatial_release_spill(start_positions, release_time, substance=None, water=None, on=True, amount=0, units='kg', windage_range=None, windage_persist=None, name='spatial_release')

Helper function returns a Spill object containing a spatial release

A spatial release is a spill that releases elements at known locations.

gnome.scripting.polygon_release_spill(filename, release_time=None, substance=None, water=None, on=True, amount=0, units='kg', windage_range=None, windage_persist=None, name='spatial_release')

Helper function returns a Spill object containing a polygon release

A polygon release is a spill that releases elements randomly within polygons in a shapefile.

class gnome.scripting.NonWeatheringSubstance(windage_range=None, windage_persist=None, standard_density=1000.0, *args, **kwargs)

Bases: Substance

A class for assigning a unique ID for an object

Parameters:

• windage_range (tuple of values between 0 and 1) – Range of windages for the substance (leeway). Default: (.01, .04)

• windage_persist=900 – persistence of windage settings in seconds. -1 or Inf means infinite.

• standard_density=1000.0 – The density of the substance, used to convert mass to/from volume

property is_weatherable

initialize_LEs(to_rel, arrs, environment=None)

:param to_rel - number of new LEs to initialize :param arrs - dict-like of data arrays representing LEs

class gnome.scripting.GnomeOil(oil_name=None, filename=None, water=None, **kwargs)

Bases: gnome.spills.substance.Substance

Class to create an oil for use in Gnome

Initialize a GnomeOil:

Parameters:

• oil_name=None – Name of one of the sample oils provided by: gnome.spills.sample_oils

• filename=None – filename (Path) of JSON file in the Adios Oil Database format.

• water=None – Water object with environmental conditions – Deprecated.

Additional keyword arguments will be passed to Substance: e.g.: windage_range, windage_persist=None,

A GnomeOil can be initialized in three ways:

1. From a sample oil name : GnomeOil(oil_name="sample_oil_name") the oils are available in gnome.spills.sample_oils

2. From a JSON file in the ADIOS Oil Database format: GnomeOil(filename="adios_oil.json") usually records from the ADIOS Oil Database (https://adios.orr.noaa.gov)

3. From the json : GnomeOil.new_from_dict(**json_) for loading save files, etc. (this is usually done under the hood)

GnomeOil(“sample_oil_name”) —works for test oils from sample_oils only

GnomeOil(oil_name=”sample_oil_name”)

GnomeOil(filename=”oil.json”) —load from file using adios_db

GnomeOil.new_from_dict(**json_) —webgnomeclient, savefiles, etc.

GnomeOil(“invalid_name”) —ValueError (not in sample oils)

filename = None

oil_name = None

water = None

from_adiosdb_file(filename, kwargs)

classmethod get_GnomeOil(oil_info, max_cuts=None)

#fixme: what is oil_info ???

Use this instead of get_oil_props

to_dict(json_=None)

Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is.

The json_ parameter is ignored in this base class. ‘save’ is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving.

initialize_LEs(to_rel, arrs, environment=None)

:param to_rel - number of new LEs to initialize :param arrs - dict-like of data arrays representing LEs

fixme:

this shouldn’t use water temp – it should use standard density and STP temp – and let weathering_data set it correctly

Note

weathering data is currently broken for initial setting

vapor_pressure(temp, atmos_pressure=101325.0)

the vapor pressure on the PCs at a given temperature water_temp and boiling point units are Kelvin

Parameters:

temp – temperature in K

Returns:

vapor_pressure array in SI units (Pascals)

## Fixme: shouldn’t this be in the Evaporation code?

classmethod bounding_temperatures(obj_list, temperature)

General Utility Function

From a list of objects containing a ref_temp_k attribute, return the object(s) that are closest to the specified temperature(s)

Specifically:

• We want the ones that immediately bound our temperature.

• If our temperature is high and out of bounds of the temperatures in our obj_list, then we return a range containing only the highest temperature.

• If our temperature is low and out of bounds of the temperatures in our obj_list, then we return a range containing only the lowest temperature.

We accept only a scalar temperature or a sequence of temperatures

get_densities()

return a list of densities for the oil at a specified state of weathering.

#fixme: this should not happen here!

We include the API as a density if:

• the specified weathering is 0

• the culled list of densities does not contain a measurement at 15C

density_at_temp(temperature=288.15)

Get the oil density at a temperature or temperatures.

Note

This is all kruft left over from the estimating code. At this point, a GnomeOil should already have what it needs.

Note

There is a catch-22 which prevents us from getting the min_temp in some cases:

• To estimate pour point, we need viscosities

• If we need to convert dynamic viscosities to kinematic, we need density at 15C

• To estimate density at temp, we need to estimate pour point

• …and then we recurse

For this case we need to make an exception.

Note

If we have a pour point that is higher than one or more of our reference temperatures, then the lowest reference temperature will become our minimum temperature.

TODO:

We are getting rid of the argument that specifies a weathering amount because it is currently implemented in an unusably precise manner. Robert would like us to implement a means of interpolating density using a combination of (temperature, weathering). But the algorithm for this is not defined at the moment.

property standard_density

Standard density is simply the density at 15C, which is the default temperature for density_at_temp()

classmethod closest_to_temperature(obj_list, temperature, num=1)

General Utility Function

From a list of objects containing a ref_temp_k attribute, return the object(s) that are closest to the specified temperature(s)

We accept only a scalar temperature or a sequence of temperatures

kvis_at_temp(temp_k=288.15, weathering=0.0)

Compute the kinematic viscosity of the oil as a function of temperature

Parameters:

• temp_k – temperatures to compute at: can be scalar or array of values. should be in Kelvin

• weathering – fraction weathered – currently not implemented

viscosity as a function of temp is given by: v = A exp(k_v2 / T)

with constants determined from measured data

determine_visc_constants()

viscosity as a function of temp is given by:

v = A exp(k_v2 / T)

The constants, A and k_v2 are determined from the viscosity data:

If only one data point, a default value for k_vs is used:

2100 K, based on analysis of data in the ADIOS database as of 2018

If two data points, the two constants are directly computed

If three or more, the constants are computed by a least squares fit.

get(prop)

get oil props

gnome.scripting.PointWind

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

gnome.scripting.constant_point_wind_mover(speed, direction, units='m/s')

utility function to create a point wind mover with a constant wind

Parameters:

• speed – wind speed

• direction – wind direction in degrees true (direction from, following the meteorological convention)

• units='m/s' – the units that the input wind speed is in. options: ‘m/s’, ‘knot’, ‘mph’, others…

Returns:

returns a gnome.movers.WindMover object all set up.

Note

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

gnome.scripting.point_wind_mover_from_file(filename, **kwargs)

Creates a wind mover from a wind time-series file (OSM long wind format)

Parameters:

• filename – The full path to the data file

• kwargs – All keyword arguments are passed on to the WindMover constructor

Returns mover:

returns a wind mover, built from the file

class gnome.scripting.Renderer(map_filename=None, output_dir='./', image_size=(800, 600), projection=None, viewport=None, map_BB=None, land_polygons=None, draw_back_to_fore=True, draw_map_bounds=False, draw_spillable_area=False, formats=['png', 'gif'], draw_ontop='forecast', cache=None, output_timestep=None, output_zero_step=True, output_last_step=True, output_single_step=False, output_start_time=None, on=True, timestamp_attrib={}, point_size=2, depth_colors=None, min_color_depth=0, max_color_depth=100, **kwargs)

Bases: gnome.outputters.Outputter, gnome.utilities.map_canvas.MapCanvas

Map Renderer

class that writes map images for GNOME results.

Writes the frames for the LE “movies”, etc.

Init the image renderer.

Parameters:

• map_filename=None – GnomeMap or name of file for basemap (BNA)

• output_dir='./' (str) – directory to output the images

• 600) (2-tuple image_size=(800,) – size of images to output

• projection=None – projection instance to use: If None, set to projections.FlatEarthProjection()

• viewport (pair of (lon, lat) tuples ( lower_left, upper right )) – viewport of map – what gets drawn and on what scale. Default is full globe: (((-180, -90), (180, 90))) If not specifies, it will be set to the map’s bounds.

• map_BB=None – bounding box of map if None, it will use the bounding box of the mapfile.

• draw_back_to_fore=True – draw the background (map) to the foregound image when outputting the images each time step.

• formats=['gif'] – list of formats to output.

• draw_ontop (str) – draw ‘forecast’ or ‘uncertain’ LEs on top. Default is to draw ‘forecast’ LEs, which are in black on top

Following args are passed to base class Outputter’s init:

Parameters:

• cache – sets the cache object from which to read prop. The model will automatically set this param

• output_timestep (timedelta object) – default is None in which case everytime the write_output is called, output is written. If set, then output is written every output_timestep starting from model_start_time.

• output_zero_step (boolean) – default is True. If True then output for initial step (showing initial release conditions) is written regardless of output_timestep

• output_last_step (boolean) – default is True. If True then output for final step is written regardless of output_timestep

• point_size=2 – size to draw elements, in pixels

• depth_colors=None –

  colorscheme to use to color elements according to their depth for 3D modeling. Any scheme that py_gd provides can be used:: py_gd.colorschemes.keys() Currently: ‘cividis’, ‘inferno’, ‘magma’, ‘plasma’, ‘turbo’, ‘twilight’, ‘viridis’ (borrowed from matplotlib)

  If None, elements will not be colored by depth

• min_color_depth=0 – depth to map the first color in the scheme (m)

• max_color_depth=100 – depth to map the last color in the scheme (m)

Remaining kwargs are passed onto Outputter.__init__(…)

map_colors = [('background', (255, 255, 255)), ('lake', (255, 255, 255)), ('land', (255, 204, 153)), ('LE',...

background_map_name = 'background_map.'

foreground_filename_format = 'foreground_{0:05d}.'

foreground_filename_glob = 'foreground_?????.*'

output_dir = './'

property map_filename

last_filename = ''

property draw_ontop

draw_back_to_fore = True

point_size = 2

map_BB = None

draw_map_bounds = False

draw_spillable_area = False

raster_map = None

raster_map_fill = True

raster_map_outline = False

background_color = 'background'

anim_filename

property formats

property delay

property repeat

timestamp_attribs

grids = []

props = []

depth_colors = None

output_dir_to_dict()

start_animation(filename)

prepare_for_model_run(*args, **kwargs)

prepares the renderer for a model run.

Parameters passed to base class (use super): model_start_time, cache

Does not take any other input arguments; however, to keep the interface the same for all outputters, define **kwargs and pass into the base class

In this case, it draws the background image and clears the previous images. If you want to save the previous images, a new output dir should be set.

set_timestamp_attrib(**kwargs)

Function to set details of the timestamp’s appearance when printed. These details are stored as a dict.

Recognized attributes:

Parameters:

• on (Boolean) – Turn the draw function on or off

• dt_format (String) – Format string for strftime to format the timestamp

• background (str) – Color of the text background. Color must be present in foreground palette

• color (str) – Color of the font. Note that the color must be present in the foreground palette

• size (str) – Size of the font, one of {‘tiny’, ‘small’, ‘medium’, ‘large’, ‘giant’}

• position (tuple) – x, y pixel coordinates of where to draw the timestamp.

• align (str) – The reference point of the text bounding box. One of: {‘lt’(left top), ‘ct’, ‘rt’, ‘l’, ‘r’, ‘lb’, ‘cb’, ‘rb’}

draw_timestamp(time)

Function that draws the timestamp to the foreground. Uses self.timestamp_attribs to determine it’s appearance.

Parameters:

time (datetime) – the datetime object representing the timestamp

clean_output_files()

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

draw_background()

Draws the background image – land and optional graticule

This should be called whenever the scale changes

add_grid(grid, on=True, color='grid_1', width=2)

draw_grids()

add_vec_prop(prop, on=True, color='LE', mask_color='uncert_LE', size=3, width=1, scale=1000)

draw_props(time)

draw_masked_nodes(grid, time)

draw_land()

Draws the land map to the internal background image.

draw_elements(sc)

Draws the individual elements to a foreground image

Parameters:

sc – a SpillContainer object to draw

draw_raster_map()

draws the raster map used for beaching to the image.

draws a grid for the pixels

this is pretty slow, but only used for diagnostics. (not bad for just the lines)

write_output(step_num, islast_step=False)

Render the map image, according to current parameters.

Parameters:

• step_num (int) – the model step number you want rendered.

• islast_step (bool) – default is False. Flag that indicates that step_num is last step. If ‘output_last_step’ is True then this is written out

Returns:

A dict of info about this step number if this step is to be output, None otherwise. ‘step_num’: step_num ‘image_filename’: filename ‘time_stamp’: time_stamp # as ISO string

use super to call base class write_output method

If this is last step, then prop is written; otherwise prepare_for_model_step determines whether to write the output for this step based on output_timestep

post_model_run()

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

projection_to_dict()

store projection class as a string for now since that is all that is required for persisting todo: This may not be the case for all projection classes, but keep simple for now so we don’t have to make the projection classes serializable

to_dict(json_=None)

Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is.

The json_ parameter is ignored in this base class. ‘save’ is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving.

class gnome.scripting.NetCDFOutput(filename, zip_output=False, which_data='standard', compress=True, surface_conc='kde', _start_idx=0, **kwargs)

Bases: gnome.outputters.outputter.Outputter, gnome.outputters.outputter.OutputterFilenameMixin

A NetCDFOutput object is used to write the model’s data to a NetCDF file. It inherits from Outputter class and implements the same interface.

This class is meant to be used within the Model, to be added to list of outputters.

>>> model = gnome.model.Model(...)
>>> model.outputters += gnome.netcdf_outputter.NetCDFOutput(
            os.path.join(base_dir,'sample_model.nc'), which_data='most')

which_data flag is used to set which data to add to the netcdf file:

‘standard’ : the basic stuff most people would want

‘most’: everything the model is tracking except the internal-use-only

arrays

‘all’: everything tracked by the model (mostly used for diagnostics of

save files)

Note

cf_attributes is a class attribute: a dict that contains the global attributes per CF convention

The attribute: .arrays_to_output is a set of the data arrays that will be added to the netcdf file. array names may be added to or removed from this set before a model run to customize what gets output: the_netcdf_outputter.arrays_to_output.add[‘rise_vel’]

Since some of the names of the netcdf variables are different from the names in the SpillContainer data_arrays, this list uses the netcdf names

Constructor for Net_CDFOutput object. It reads data from cache and writes it to a NetCDF4 format file using the CF convention

Parameters:

• filename (str. or unicode) – Required parameter. The filename in which to store the NetCDF data.

• zip_output=True – whether to zip up the output netcdf files

• which_data='standard' – If ‘standard’, write only standard data. If ‘most’ means, write everything except the attributes we know are for internal model use. If ‘all’, write all data to NetCDF – usually only for diagnostics. Default is ‘standard’. These are defined in the standard_arrays and usually_skipped_arrays attributes

NOTE: if you want a custom set of output arrays, you can cahnge the .self.arrays_to_output set after initialization.

Optional arguments passed on to base class (kwargs):

Parameters:

• cache – sets the cache object from which to read data. The model will automatically set this param

• output_timestep (timedelta object) – default is None in which case every time the write_output is called, output is written. If set, then output is written every output_timestep starting from model_start_time.

• output_zero_step (boolean) – default is True. If True then output for initial step (showing initial release conditions) is written regardless of output_timestep

• output_last_step (boolean) – default is True. If True then output for final step is written regardless of output_timestep

use super to pass optional kwargs to base class __init__ method

which_data_lu

compress_lu

cf_attributes

standard_arrays = ['latitude', 'longitude', 'depth', 'status_codes', 'spill_num', 'id', 'mass', 'age', 'density',...

special_arrays

usually_skipped_arrays = ['next_positions', 'last_water_positions', 'windages', 'mass_components', 'half_lives',...

forecast_filename

zip_filename

name

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

zip_output = False

arrays_to_output

property uncertain_filename

if uncertain SpillContainer is present, write its data out to this file

property which_data

property chunksize

property compress

property netcdf_format

prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs)

prepare_for_model_run(model_start_time,

spills,

**kwargs)

Write global attributes and define dimensions and variables for NetCDF file. This must be done in prepare_for_model_run because if model _state changes, it is rewound and re-run from the beginning.

If there are existing output files, they are deleted here.

This takes more than standard ‘cache’ argument. Some of these are required arguments - they contain None for defaults because non-default argument cannot follow default argument. Since cache is already 2nd positional argument for Renderer object, the required non-default arguments must be defined following ‘cache’.

If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainers, the data itself is different, but they contain the same type of data arrays. If uncertain, then datay arrays for uncertain spill container are written to filename + ‘_uncertain.nc’

Parameters:

spills (gnome.spill_container.SpillContainerPair object.) – If ‘which_data’ flag is set to ‘all’ or ‘most’, then model must provide the model.spills object (SpillContainerPair object) so NetCDF variables can be defined for the remaining data arrays. If spills is None, but which_data flag is ‘all’ or ‘most’, a ValueError will be raised. It does not make sense to write ‘all’ or ‘most’ but not provide ‘model.spills’.

Note

Does not take any other input arguments; however, to keep the interface the same for all outputters, define **kwargs in case future outputters require different arguments.

use super to pass model_start_time, cache=None and remaining kwargs to base class method

write_output(step_num, islast_step=False)

Write NetCDF output at the end of the step

Parameters:

• step_num (int) – the model step number you want rendered.

• islast_step (bool) – Default is False. Flag that indicates that step_num is last step. If ‘output_last_step’ is True then this is written out

Use super to call base class write_output method

post_model_run()

This is where to clean up – close files, etc.

clean_output_files()

deletes output files that may be around

called by prepare_for_model_run

here in case it needs to be called from elsewhere

rewind()

reset a few parameter and call base class rewind to reset internal variables.

classmethod read_data(netcdf_file, time=None, index=None, which_data='standard')

Read and create standard data arrays for a netcdf file that was created with NetCDFOutput class. Make it a class method since it is independent of an instance of the Outputter. The method is put with this class because the NetCDF functionality for PyGnome data with CF standard is captured here.

Parameters:

• netcdf_file – Name of the NetCDF file from which to read the data

• time – timestamp at which the data is desired. Looks in the netcdf data’s ‘time’ array and finds the closest time to this and outputs this data. If both ‘time’ and ‘index’ are None, return data if file only contains one ‘time’ else raise an error

• index (int) – Index of the ‘time’ variable (or time_step). This is only used if ‘time’ is None. If both ‘time’ and ‘index’ are None,return data if file only contains one ‘time’ else raise an error

• which_data='standard' – Which data arrays are desired. Options are: (‘standard’, ‘most’, ‘all’, [list_of_array_names])

Returns:

A dict containing standard data closest to the indicated ‘time’.

Standard data is defined as follows:

Standard data arrays are numpy arrays of size N, where N is number of particles released at time step of interest. They are defined by the class attribute “standard_arrays”, currently:

'current_time_stamp': datetime object associated with this data
'positions'         : NX3 array. NetCDF variables:
                      'longitude', 'latitude', 'depth'
'status_codes'      : NX1 array. NetCDF variable :'status_codes'
'spill_num'         : NX1 array. NetCDF variable: 'spill_num'
'id'                : NX1 array of particle id. NetCDF variable
                      'id'
'mass'              : NX1 array showing 'mass' of each particle

standard_arrays = ['latitude',
                   'longitude', # pulled from the 'positions' array
                   'depth',
                   'status_codes',
                   'spill_num',
                   'id',
                   'mass',
                   'age',
                   ]

to_dict(json_=None)

Returns a dictionary representation of this object. Uses the schema to determine which attributes are put into the dictionary. No extra processing is done to each attribute. They are presented as is.

The json_ parameter is ignored in this base class. ‘save’ is passed in when the schema is saving the object. This allows an override of this function to do any custom stuff necessary to prepare for saving.

class gnome.scripting.KMZOutput(filename, **kwargs)

Bases: gnome.outputters.outputter.OutputterFilenameMixin, gnome.outputters.outputter.Outputter

class that outputs GNOME results in a kmz format.

Suitable for Google Earth, and semi-suitable for MarPlot

Parameters:

output_dir=None (str) – output directory for kmz files.

uses super to pass optional **kwargs to base class __init__ method

time_formatter = '%m/%d/%Y %H:%M'

kml_name

prepare_for_model_run(model_start_time, spills, **kwargs)

prepare_for_model_run(model_start_time,

cache=None,

uncertain=False,

spills=None,

**kwargs)

Write the headers, png files, etc for the KMZ file

This must be done in prepare_for_model_run because if model _state changes, it is rewound and re-run from the beginning.

If there are existing output files, they are deleted here.

This takes more than standard ‘cache’ argument. Some of these are required arguments - they contain None for defaults because non-default argument cannot follow default argument. Since cache is already 2nd positional argument for Renderer object, the required non-default arguments must be defined following ‘cache’.

If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainer’s, the data itself is different, but they contain the same type of data arrays. If uncertain, then data arrays for uncertain spill container are written to the KMZ file.

Note

Does not take any other input arguments; however, to keep the interface the same for all outputters, define kwargs in case future outputters require different arguments.

write_output(step_num, islast_step=False)

dump a timestep’s data into the kmz file

rewind()

reset a few parameter and call base class rewind to reset internal variables.

class gnome.scripting.OilBudgetOutput(filename='gnome_oil_budget.csv', file_format='csv', cache=None, on=True, output_timestep=None, *args, **kwargs)

Bases: gnome.outputters.weathering.BaseMassBalanceOutputter, gnome.outputters.outputter.OutputterFilenameMixin

Outputter for the oil budget table

Sets attributes for outputters, like output_timestep, cache, etc.

Parameters:

• cache – sets the cache object from which to read data. The model will automatically set this parameter.

• output_timestep=None – If None output will be written every model time step. If set, then output is written every output_timestep starting from the model start time. If the output_timestep is less than the model timestep, an Warning will be raised at runtime.

• output_zero_step=True – If True then output for initial step (showing initial release conditions) is written regardless of output_timestep or output_single_step

• output_last_step=True – If True then output for final step is written regardless of output_timestep or output_single_step. This is potentially an extra output, if not aligned with output_timestep.

• output_single_step=False – If True then output is written for only one step, the output_start_time, regardless of output_timestep. output_zero_step and output_last_step are still respected, set these to False if you want only one time step.

• output_start_time=None – Time to start outputting restults. If None it is set to the model start time

• output_dir=None – Directory to dump output in, if it needs to do this.

• surface_conc=None – Compute surface concentration Any non-empty string will compute (and output) the surface concentration. The contents of the string determine the algorithm used. “kde” is currently the only available option.

budget_categories = ['amount_released', 'evaporated', 'natural_dispersion', 'sedimentation', 'beached', 'floating',...

header_row = ['Model Time', 'Hours Since Model Start', 'Amount Released (kg)', 'Evaporated (kg)', 'Dispersed...

file_format = 'csv'

prepare_for_model_run(model_start_time, spills, **kwargs)

start the csv file

write_output(step_num, islast_step=False)

Oil budget is only output for forecast spill container, not the uncertain spill container. This is because Weathering has its own uncertainty and mixing the two was giving weird results. The cloned models that are modeling weathering uncertainty do not include the uncertain spill container.

post_model_run()

Called after a model run is complete

remove the csv file - hopefully resulting in the file being closed.

class gnome.scripting.ShapeOutput(filename, zip_output=True, include_certain_boundary=False, certain_boundary_separate_by_spill=True, certain_boundary_hull_ratio=0.5, certain_boundary_hull_allow_holes=False, include_uncertain_boundary=True, include_certain_in_uncertain_boundary=True, uncertain_boundary_separate_by_spill=True, uncertain_boundary_hull_ratio=0.5, uncertain_boundary_hull_allow_holes=False, timeoffset=None, surface_conc='kde', **kwargs)

Bases: gnome.outputters.outputter.Outputter

class that outputs GNOME results (particles) in a shapefile format.

Parameters:

• filename – Full path and basename of the shape file.

• zip_output=True – Whether to zip up the output shape files.

• surface_conc="kde" – Method to use to compute surface concentration current options are: ‘kde’ and None

time_formatter = '%m/%d/%Y %H:%M'

filenamestem

filedir = ''

tempdir

shapefile_name_certain

shapefile_name_certain_boundary

shapefile_name_uncertain

shapefile_name_uncertain_boundary

timeoffset = None

zip_output = True

include_certain_boundary = False

certain_boundary_separate_by_spill = True

certain_boundary_hull_ratio = 0.5

certain_boundary_hull_allow_holes = False

include_uncertain_boundary = True

include_certain_in_uncertain_boundary = True

uncertain_boundary_separate_by_spill = True

uncertain_boundary_hull_ratio = 0.5

uncertain_boundary_hull_allow_holes = False

shapefile_builder_certain

shapefile_builder_certain_boundary

shapefile_builder_uncertain

shapefile_builder_uncertain_boundary

prepare_for_model_run(model_start_time, spills, uncertain=False, **kwargs)

If uncertainty is on, then SpillContainerPair object contains identical _data_arrays in both certain and uncertain SpillContainer’s, the data itself is different, but they contain the same type of data arrays. If uncertain, then data arrays for uncertain spill container are written.

write_output(step_num, islast_step=False)

Dump a timestep’s data into the shapefile

post_model_run()

The final step to wrap everything up

create_bundle(uncertain)

Create a shapefile bundle including both certain and uncertain shapefiles

rewind()

reset a few parameter and call base class rewind to reset internal variables.

clean_output_files()

deletes ouput files that may be around called by prepare_for_model_run here in case it needs to be called from elsewhere

class gnome.scripting.WeatheringOutput(output_dir=None, **kwargs)

Bases: BaseMassBalanceOutputter

class that outputs GNOME weathering results on a time step by time step basis

The output is the aggregation of properties for all LEs (aka Mass Balance) for a particular time step. There are a number of different things we would like to graph: - Evaporation - Dissolution - Dissipation - Biodegradation - ???

Parameters:

output_dir=None (str) – output directory for the json files. If not directory is provided, files will not be written.

other arguments as defined in the Outputter class

write_output(step_num, islast_step=False)

Weathering data is only output for forecast spill container, not the uncertain spill container. This is because Weathering has its own uncertainty and mixing the two was giving weird results. The cloned models that are modeling weathering uncertainty do not include the uncertain spill container.

output_to_file(json_content, step_num)

clean_output_files()

Cleans out the output dir

This should be implemented by subclasses that dump files.

Each outputter type dumps different types of files, and this should only clear out those.

See the OutputterFilenameMixin for a simple example.

class gnome.scripting.MapFromBNA(filename, raster_size=4096 * 4096, map_bounds=None, spillable_area=None, shift_lons=0, **kwargs)

Bases: RasterMap

A raster land-water map, created from file with polygons in it.

Currently only support BNA, but could be shapefile, or ???

Creates a RasterMap from a data file. It is expected that you will get the spillable area and map bounds from the data file – if they exist

Required arguments:

Parameters:

• filename – full path to the data file

• raster_size (integer) – the total number of pixels (bytes) to make the raster – the actual size will match the aspect ratio of the bounding box of the land

• shiftLons (integer) – shift longitudes to be in -180 to 180 coords or 0 to 360. 180, or 360 are valid inputs

Optional arguments (kwargs):

Parameters:

• refloat_halflife – the half-life (in hours) for the re-floating.

• map_bounds – The polygon bounding the map – could be larger or smaller than the land raster

• spillable_area – The polygon bounding the spillable_area

• id (string) – unique ID of the object. Using UUID as a string. This is only used when loading object from save file.

filename

shift_lons = 0

build_raster(land_polys=None, BB=None)

Build the underlying raster used for the map

This should be called if the resolution or land polygons change

property raster_size

Maximum physical size of the raster in bytes

to_geojson()

Output the vector version of the shoreline polygons.

This is what gets drawn in the WebGNOME client, for example

This version directly writes the polygons already stored in the map object – keeping the door open to that data coming from something other than a bna file.

FIXME: Technically, geojson recommends ccw polygons – but putting that

check in was pretty slow, so it’s commented out.

FIXME: This really should export the map_bounds and spillable_area as well.

class gnome.scripting.GnomeMap(map_bounds=None, spillable_area=None, land_polys=None, **kwargs)

Bases: gnome.gnomeobject.GnomeId

The very simplest map for GNOME – all water with only a bounding box for the map bounds.

This also serves as a description of the interface and base class for more complex maps

The __init__ will be different for other implementations

Parameters:

• map_bounds – The polygon bounding the map if any elements are outside the map bounds, they are removed from the simulation.

• spillable_area (Either a PolygonSet object or a list of lists from which a polygon set can be created. Each element in the list is a list of points defining a polygon.) – The PolygonSet bounding the spillable_area.

• land_polys (Either a PolygonSet object or a list of lists from which a polygon set can be created. Each element in the list is a list of points defining a polygon.) – The PolygonSet holding the land polygons

Note on ‘map_bounds’:

[(lon, lat), (lon, lat), (lon, lat), .. An NX2 array of points that describe a polygon if no map bounds is provided – the whole world is valid

refloat_halflife = None

property spillable_area

List of polygons defining the region in which it is legal to set spills

property land_polys

Sequence of polygons surrounding land – mostly used for rendering.

get_polygons()

property map_bounds

Bounds of the map – an NX2 array of float describing a polygon.

[(lon, lat), (lon, lat), …]

get_map_bounding_box()

return a bounding box of the map

needed because map_bounds can be a polygon

bounding box is a 2x2 tuple:

((left, bottom), (right, top))

on_map(coords)

Determine whether points are on the map or not

Parameters:

coords (NX3 numpy array of floats: (long, lat, depth) or something that can be turned into one.) – location for test.

Returns:

bool array: True if the location is on the map, False otherwise

Note:

coords are 3-d, but the concept of “on the map” is 2-d in this context, so depth is ignored.

on_land(coord)

Parameters:

coord (3-tuple of floats: (long, lat, depth)) – location for test.

Returns:

• Always returns False– no land in this implementation

in_water(coords)

Determines if the points are in water (rather than on land)

Parameters:

coords (3-tuple of floats: (long, lat, depth) or an Nx3 array) – location for test.

Returns:

• True if the point is in the water,

• False if the point is on land (or off map?)

This implementation has no land, so always True in on the map.

allowable_spill_position(coord)

Parameters:

coord (3-tuple of floats: (long, lat, depth)) – location for test.

Returns:

• True if the point is an allowable spill position

• False if the point is not an allowable spill position

Note

it could be either off the map, or in a location that spills aren’t allowed

beach_elements(sc, model_time=None)

Determines which LEs were or weren’t beached or moved off_map. status_code is changed to oil_status.off_maps if off the map.

Called by the model in the main time loop, after all movers have acted.

Parameters:

sc (gnome.spill_container.SpillContainer) – current SpillContainer

This map class has no land, so only the map check and resurface_airborn elements is done: noting else changes.

subclasses that override this probably want to make sure that:

self.resurface_airborne_elements(sc) self._set_off_map_status(sc)

are called.

refloat_elements(spill_container, time_step, model_time=None)

This method performs the re-float logic – changing the element status flag, and moving the element to the last known water position

Parameters:

spill_container (gnome.spill_container.SpillContainer) – current SpillContainer

Note

This map class has no land, and so is a no-op.

resurface_airborne_elements(spill_container)

Takes any elements that are left above the water surface (z < 0.0) and puts them on the surface (z == 0.0)

Parameters:

spill_container (gnome.spill_container.SpillContainer) – current SpillContainer

Note

While this shouldn’t occur according to the physics we’re modeling, some movers may push elements up too high, or multiple movers may add vertical movement that adds up to over the surface. e.g rise velocity.

to_geojson()

class gnome.scripting.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.scripting.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.scripting.SteadyUniformCurrent(speed, direction, units='m/s', name='Steady Uniform Current')

Bases: gnome.environment.environment.Environment

Simple current: the same at all time and places

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

Parameters:

• speed – speed of the current

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

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

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

data_start

data_stop

units = 'm/s'

property speed

property direction

property u

property v

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

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

Parameters:

• points – will be ignored

• time – will be ignored

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

Returns:

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

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

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.scripting.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.scripting.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.scripting.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.scripting.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.scripting.RandomMover(diffusion_coef=100000.0, uncertain_factor=2.0, **kwargs)

Bases: gnome.movers.CyMover

“Random Walk” diffusion mover

Moves the elements each time step in a random direction, according to the specified diffusion coefficient.

Parameters:

• diffusion_coef (float or integer in units of cm^2/s) – Diffusion coefficient for random diffusion. Default is 100,000 cm2/sec

• uncertain_factor – Uncertainty factor. Default is 2.0

Remaining kwargs are passed onto gnome.movers.Mover __init__

See Mover documentation for remaining valid kwargs.

mover

property data_start

property data_stop

property diffusion_coef

property uncertain_factor

class gnome.scripting.RandomMover3D(vertical_diffusion_coef_above_ml=5, vertical_diffusion_coef_below_ml=0.11, horizontal_diffusion_coef_above_ml=100000, horizontal_diffusion_coef_below_ml=126, mixed_layer_depth=10.0, surface_is_allowed=False, **kwargs)

Bases: gnome.movers.CyMover

This mover class inherits from CyMover and contains CyRandomMover3D

The real work is done by CyRandomMover3D. CyMover sets everything up that is common to all movers.

Parameters:

• vertical_diffusion_coef_above_ml – Vertical diffusion coefficient for random diffusion above the mixed layer. Default is 5 cm2/s

• vertical_diffusion_coef_below_ml – Vertical diffusion coefficient for random diffusion below the mixed layer. Default is .11 cm2/s

• mixed_layer_depth – Mixed layer depth. Default is 10 meters

• horizontal_diffusion_coef_above_ml – Horizontal diffusion coefficient for random diffusion above the mixed layer. Default is 100000 cm2/s

• horizontal_diffusion_coef_below_ml – Horizontal diffusion coefficient for random diffusion below the mixed layer. Default is 126 cm2/s

• surface_is_allowed – Vertical diffusion will ignore surface particles if this is True. Default is False.

Remaining kwargs are passed onto Mover’s __init__ using super.

See Mover documentation for remaining valid kwargs.

mover

property horizontal_diffusion_coef_above_ml

property horizontal_diffusion_coef_below_ml

property vertical_diffusion_coef_above_ml

property vertical_diffusion_coef_below_ml

property mixed_layer_depth

property surface_is_allowed

class gnome.scripting.PointWindMover(wind=None, **kwargs)

Bases: WindMoversBase

Python wrapper around the Cython wind_mover module. This class inherits from CyMover and contains CyWindMover

The real work is done by the CyWindMover object. CyMover sets everything up that is common to all movers.

Uses super to call CyMover base class __init__

Parameters:

wind – wind object – provides the wind time series for the mover

Remaining kwargs are passed onto WindMoversBase __init__ using super. See Mover documentation for remaining valid kwargs.

Note

Can be initialized with wind=None; however, wind must be set before running. If wind is not None, toggle make_default_refs to False since user provided a valid Wind and does not wish to use the default from the Model.

mover

property wind

property data_start

property data_stop

prepare_for_model_run()

if wind attribute is not set, raise ReferencedObjectNotSet excpetion

class gnome.scripting.CatsMover(filename=None, tide=None, uncertain_duration=48, **kwargs)

Bases: CurrentMoversBase

Base class from which all Python movers/weatherers can inherit

It defines the base functionality for mover/weatherer.

NOTE: Since base class is not Serializable, it does not need

a class level _schema attribute.

Uses super to invoke base class __init__ method.

Parameters:

filename – file containing currents patterns for Cats

Optional parameters (kwargs). Defaults are defined by CyCatsMover object.

Parameters:

• tide – a gnome.environment.Tide object to be attached to CatsMover

• scale – a boolean to indicate whether to scale value at reference point or not

• scale_value – value used for scaling at reference point

• scale_refpoint – reference location (long, lat, z). The scaling applied to all data is determined by scaling the raw value at this location.

• uncertain_duration – how often does a given uncertain element gets reset

• uncertain_time_delay – when does the uncertainly kick in.

• up_cur_uncertain – Scale for uncertainty along the flow

• down_cur_uncertain – Scale for uncertainty along the flow

• right_cur_uncertain – Scale for uncertainty across the flow

• left_cur_uncertain – Scale for uncertainty across the flow

• uncertain_eddy_diffusion – Diffusion coefficient for eddy diffusion. Default is 0.

• uncertain_eddy_v0 – Default is .1 (Check that this is still used)

Remaining kwargs are passed onto Mover’s __init__ using super. See Mover documentation for remaining valid kwargs.

mover

up_cur_uncertain

down_cur_uncertain

right_cur_uncertain

left_cur_uncertain

uncertain_eddy_diffusion

uncertain_eddy_v0

scale

scale_value

filename

property ref_scale

property scale_refpoint

property tide

property data_start

property data_stop

get_grid_data()

Invokes the GetToplogyHdl method of TriGridVel_c object

get_center_points()

get_scaled_velocities(model_time)

Get file values scaled to ref pt value, with tide applied (if any)

class gnome.scripting.ComponentMover(filename1=None, filename2=None, wind=None, scale_refpoint=None, pat1_angle=0, pat1_speed=10, pat1_speed_units=2, pat1_scale_to_value=0.1, pat2_angle=90, pat2_scale_to_value=0.1, pat2_speed=10, pat2_speed_units=2, scale_by=0, **kwargs)

Bases: CurrentMoversBase

Base class from which all Python movers/weatherers can inherit

It defines the base functionality for mover/weatherer.

NOTE: Since base class is not Serializable, it does not need

a class level _schema attribute.

Uses super to invoke base class __init__ method.

Parameters:

filename – file containing currents for first Cats pattern

Optional parameters (kwargs). Defaults are defined by CyCatsMover object.

Parameters:

• filename – file containing currents for second Cats pattern

• wind – A gnome.environment.Wind object to be used to drive the CatsMovers. Will want a warning that mover will not be active without a wind

• scale – A boolean to indicate whether to scale value at reference point or not

• scale_value – Value used for scaling at reference point

• scale_refpoint – Reference location (long, lat, z). The scaling applied to all data is determined by scaling the raw value at this location.

Remaining kwargs are passed onto Mover’s __init__ using super. See Mover documentation for remaining valid kwargs.

filename1 = None

filename2 = None

mover

scale_by = 0

property scale_refpoint

pat1_angle = 0

pat1_speed = 10

pat1_speed_units = 2

pat1_scale_to_value = 0.1

pat2_angle = 90

pat2_scale_to_value = 0.1

pat2_speed = 10

pat2_speed_units = 2

extrapolate

use_averaged_winds

wind_power_factor

past_hours_to_average

scale_factor_averaged_winds

use_original_scale_factor

property data_start

property data_stop

property wind

get_grid_data()

Invokes the GetToplogyHdl method of TriGridVel_c object

get_center_points()

get_optimize_values(model_time)

get_scaled_velocities(model_time)

Get file values scaled to optimized check if pat2 exists

class gnome.scripting.RiseVelocityMover(**kwargs)

Bases: gnome.movers.CyMover

This mover class inherits from CyMover and contains CyRiseVelocityMover

The real work is done by CyRiseVelocityMover. CyMover sets everything up that is common to all movers.

Uses super to invoke base class __init__ method.

Optional parameters (kwargs) used to initialize CyRiseVelocityMover

Parameters:

• water_density – Default is 1020 kg/m3

• water_viscosity – Default is 1.e-6

Remaining kwargs are passed onto Mover’s __init__ using super. See Mover documentation for remaining valid kwargs.

mover

get_move(sc, time_step, model_time_datetime)

Override base class functionality because mover has a different get_move signature

Parameters:

• sc – an instance of the gnome.SpillContainer class

• time_step – time step in seconds

• model_time_datetime – current time of the model as a date time object

class gnome.scripting.WindMover(wind=None, uncertain_duration=3.0 * 3600, uncertain_time_delay=0, uncertain_speed_scale=2.0, uncertain_angle_scale=0.4, scale_value=1, default_num_method='RK2', filename=None, **kwargs)

Bases: gnome.movers.movers.PyMover

WindMover implemented in Python. Uses the .wind attribute to move particles. The .at() interface is expected on the .wind attribute

Initialize a WindMover :param wind: Environment object representing wind to be

used.

Parameters:

• active_range (2-tuple of datetimes) – Range of datetimes for when the mover should be active

• scale_value – Value to scale wind data

• uncertain_duration – how often does a given uncertain element get reset

• uncertain_time_delay – when does the uncertainly kick in.

• uncertain_speed_scale – Scale for uncertainty of wind speed

• uncertain_angle_scale – Scale for uncertainty of wind angle

• num_method – Numerical method for calculating movement delta. Choices:(‘Euler’, ‘RK2’, ‘RK4’) Default: RK2

wind = None

make_default_refs = False

uncertain_duration = 10800.0

uncertain_time_delay = 0

uncertain_speed_scale = 2.0

uncertain_angle_scale = 0.4

uncertain_diffusion = 0

scale_value = 1

sigma_theta = 0

sigma2 = 0

is_first_step = False

time_uncertainty_was_set = 0

shape = (2,)

uncertainty_list

classmethod from_netCDF(filename=None, scale_value=1, uncertain_duration=3 * 3600, uncertain_time_delay=0, uncertain_speed_scale=2.0, uncertain_angle_scale=0.4, default_num_method='RK2', **kwargs)

property data_start

property data_stop

prepare_for_model_run()

reset uncertainty

prepare_for_model_step(sc, time_step, model_time_datetime)

Call base class method using super Also updates windage for this timestep

Parameters:

• sc – an instance of gnome.spill_container.SpillContainer class

• time_step – time step in seconds

• model_time_datetime – current time of model as a date time object

model_step_is_done(sc)

remove any off map les

get_bounds()

Return a bounding box surrounding the grid data. This function exists because it is part of the top level Mover API

update_uncertainty(num_les, elapsed_time)

update uncertainty

Parameters:

• num_les – the number released so far

• elapsed_time – time in seconds since model run started

update_uncertainty_values(elapsed_time)

update uncertainty values

Parameters:

elapsed_time – time in seconds since model run started

allocate_uncertainty(num_les)

add uncertainty

Parameters:

num_les – the number of les released so far

add_uncertainty(deltas, time_step)

add uncertainty

Parameters:

deltas – the movement for the current time step

get_move(sc, time_step, model_time_datetime, num_method=None)

Compute the move in (long,lat,z) space. It returns the delta move for each element of the spill as a numpy array of size (number_elements X 3) and dtype = gnome.basic_types.world_point_type

Base class returns an array of numpy.nan for delta to indicate the get_move is not implemented yet.

Each class derived from Mover object must implement it’s own get_move

Parameters:

• sc – an instance of gnome.spill_container.SpillContainer class

• time_step – time step in seconds

• model_time_datetime – current model time as datetime object

All movers must implement get_move() since that’s what the model calls

class gnome.scripting.CurrentMover(current=None, scale_value=1, uncertain_duration=24 * 3600, uncertain_time_delay=0, uncertain_along=0.5, uncertain_cross=0.25, default_num_method='RK2', filename=None, **kwargs)

Bases: gnome.movers.movers.PyMover

CurrentMover implemented in Python. Uses the .current attribute to move particles. The .at() interface is expected on the .current attribute

Initialize a CurrentMover

Parameters:

• current (Any Current or Current-like that implements the .at() function) – Environment object representing ocean currents to be used.

• active_range (2-tuple of datetimes) – Range of datetimes for when the mover should be active

• scale_value – Value to scale current data

• uncertain_duration – how often does a given uncertain element get reset in seconds

• uncertain_time_delay – when does the uncertainly kick in in seconds

• uncertain_cross – Scale for uncertainty perpendicular to the flow

• uncertain_along – Scale for uncertainty parallel to the flow

• default_num_method – Numerical method for calculating movement delta. Choices:(‘Euler’, ‘RK2’, ‘RK4’) Default: RK2

property filename

current = None

scale_value = 1

uncertain_along = 0.5

uncertain_cross = 0.25

uncertain_duration = 86400

uncertain_time_delay = 0

model_time = 0

spill_type = 0

is_first_step = False

time_uncertainty_was_set = 0

shape = (2,)

classmethod from_netCDF(filename=None, name=None, scale_value=1, uncertain_duration=24 * 3600, uncertain_time_delay=0, uncertain_along=0.5, uncertain_cross=0.25, **kwargs)

Function for specifically creating a CurrentMover from a file

property data_start

property data_stop

get_bounds()

Return a bounding box surrounding the grid data. This function exists because it is part of the top level Mover API

get_move(sc, time_step, model_time_datetime, num_method=None)

Compute the move in (long,lat,z) space. It returns the delta move for each element of the spill as a numpy array of size (number_elements X 3) and dtype = gnome.basic_types.world_point_type

Base class returns an array of numpy.nan for delta to indicate the get_move is not implemented yet.

Each class derived from Mover object must implement it’s own get_move

Parameters:

• sc – an instance of gnome.spill_container.SpillContainer class

• time_step – time step in seconds

• model_time_datetime – current model time as datetime object

All movers must implement get_move() since that’s what the model calls

prepare_for_model_run()

reset uncertainty

prepare_for_model_step(sc, time_step, model_time_datetime)

add uncertainty

model_step_is_done(sc)

remove any off map les

class gnome.scripting.IceAwareRandomMover(ice_concentration=None, **kwargs)

Bases: RandomMover

“Random Walk” diffusion mover

Moves the elements each time step in a random direction, according to the specified diffusion coefficient.

Parameters:

• diffusion_coef (float or integer in units of cm^2/s) – Diffusion coefficient for random diffusion. Default is 100,000 cm2/sec

• uncertain_factor – Uncertainty factor. Default is 2.0

Remaining kwargs are passed onto gnome.movers.Mover __init__

See Mover documentation for remaining valid kwargs.

ice_concentration = None

classmethod from_netCDF(filename=None, dataset=None, grid_topology=None, units=None, time=None, ice_concentration=None, grid=None, grid_file=None, data_file=None, **kwargs)

get_move(sc, time_step, model_time_datetime)

Base implementation of Cython wrapped C++ movers Override for things like the PointWindMover since it has a different implementation

Parameters:

• sc – spill_container.SpillContainer object

• time_step – time step in seconds

• model_time_datetime – current model time as datetime object

class gnome.scripting.SimpleMover(velocity=0, uncertainty_scale=0.5, **kwargs)

Bases: gnome.movers.Mover

simple_mover

a really simple mover – moves all LEs a constant speed and direction

(not all that different than a constant wind mover, now that I

think about it)

simple_mover (velocity)

create a simple_mover instance

Parameters:

• velocity – a (u, v, w) triple – in meters per second

• uncertainty_scale=0.5 – the scale of the uncertainty of the velocity

Remaining kwargs are passed onto Mover’s __init__ using super. See Mover documentation for remaining valid kwargs.

velocity

uncertainty_scale = 0.5

get_move(spill, time_step, model_time)

moves the particles defined in the spill object

Parameters:

• spill – spill is an instance of the gnome.spills.Spill class

• time_step – time_step in seconds

• model_time – current model time as a datetime object

In this case, it uses the positions and status_code data arrays.

Returns delta:

Nx3 numpy array of movement – in (long, lat, meters) units

gnome.scripting.PyCurrentMover

gnome.scripting.PyWindMover

gnome.scripting.get_datafile(filename)

Looks to see if filename exists in local directory. If it exists, then it simply returns the ‘filename’ back as a string.

If ‘filename’ does not exist in the local filesystem, then it tries to download it from the gnome server (http://gnome.orr.noaa.gov/py_gnome_testdata). If it successfully downloads the file, it puts it in the user specified path given in filename and returns the ‘filename’ string.

If file is not found or server is down, it re-throws the HTTPError raised by urllib

Parameters:

filename (string) – path to the file including filename

Exception:

raises HTTPError if server is down or file not found on server

Returns:

returns the string ‘filename’ once it has been downloaded to user specified location

gnome.scripting.load_model(filename)

load a model from an existing savefile

Parameters:

filename – filename (path) of the save file to load.

Returns:

A configured Model object.

Note:

This is simply a handy wrapper around the Model.load_savefile classmethod