`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¶

Package Contents¶

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 class for assigning a unique ID for an object
`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.
`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 returns a Spill object
`point_line_spill`(num_elements, start_position, ...[, ...])	Helper function returns a Spill object
`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

Attributes¶

`oil_status_map`
`now`
`PointWind`
`PyCurrentMover`
`PyWindMover`

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, **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.

property uncertain¶: Uncertainty attribute of the model. If flag is toggled, rewind model

property uncertain_spills¶

property cache_enabled¶: If True, then generated data is cached

property has_weathering_uncertainty¶

property has_weathering¶

property start_time¶: Start time of the simulation

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

_schema¶

_oc_list = ['movers', 'weatherers', 'environment', 'outputters']¶

modes¶

next¶

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.

_register_callbacks()¶: Register callbacks with the OrderedCollections

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.

_reset_num_time_steps()¶: reset number of time steps if duration, or time_step change

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

_order_weatherers()¶: use weatherer_sort to sort the weatherers

_attach_default_refs(ref_dict)¶: Model invokes the default reference attachment system. Please note the structure of this function as an example of how to extend the system to contained child objects.

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:

Set up special objects.
Some weatherers currently require other weatherers to exist. This step satisfies those requirements
Remake collections in case ordering constraints apply (weatherers)
Compile array_types and run setup procedure on spills
array_types defines what data arrays are required by the various components of the model
Attach default references
Call prepare_for_model_run on all relevant objects
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

_update_fate_status(sc)¶: WeatheringData used to perform this operation in weather_elements; however, WeatheringData is one of the objects in weatherers collection so just let model do this for now. Eventually, we want to get rid of ‘fate_status’ array and only manipulate ‘status_codes’. Until then, update fate_status in move_elements

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.

_split_into_substeps()¶

Returns:

sequence of (datetime, timestep) (Note: we divide evenly on second boundaries.

Thus, there will likely be a remainder that needs to be included. We include this remainder, which results in 1 more sub-step than we requested.)

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

__iter__()¶: Rewinds the model and returns itself so it can be iterated over.

__next__()¶

(This method satisfies Python’s iterator and generator protocols)

Returns:: the step number

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

_add_to_environ_collec(obj_added)¶

if an environment object exists in obj_added, but not in the Model’s environment collection, then add it automatically. todo: maybe we don’t want to do this - revisit this requirement JAH 9/22/2021: We sort of need this now because a lot of script behavior expects it. A lamentable state of affairs indeed.

CHB: maybe this could be more standardized though

– pity to have hard coded what all the possible environment types are.

perhaps all objects could have a “need_env_objects” attribute?

_callback_add_mover(obj_added)¶: Callback after mover has been added

_callback_add_outputter(obj_added)¶: Callback after outputter has been added

_callback_add_weatherer_env(obj_added)¶: Callback after weatherer/environment object has been added. ‘waves’ environment object contains ‘wind’ and ‘water’ so add those to environment collection and the ‘water’ attribute. todo: simplify this

_callback_add_spill(obj_added)¶

__eq__(other)¶

__eq__(other)¶

Since this class is designed as a mixin with one objective being to save _state of the object, then recreate a new object with the same _state.

Defines a base implementation of __eq__ so an object before persistence can be compared with a new object created after it is persisted. It can be overridden by the class with which it is mixed.

It looks at attributes defined in self._state and checks that the values match

It uses allclose() check for floats and numpy arrays, to avoid floating point tolerances: set to: RTOL=1e-05, ATOL=1e-08

Parameters:: other – another GnomeObject used for comparison in obj1 == other

NOTE: super is not used.

__ne__(other)¶: Return self!=value.

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.

_save_spill_data(saveloc, nc_filename)¶: save the data arrays for current timestep to NetCDF If saveloc is zipfile, then move NetCDF to zipfile

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.

_load_spill_data(saveloc, filename, nc_file)¶: load NetCDF file and add spill data back in - designed for savefiles

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

_validate_env_coll(refs, raise_exc=False)¶: validate refs + log warnings or raise error if required refs not found. If refs is None, model must query its weatherers/movers/environment collections to figure out what objects it needs to have in environment.

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

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)

__str__()¶: Return str(self).

__repr__()¶: Return repr(self).

isoformat()¶

__lt__(other)¶: an MinusInfTime object is always less than any other object except itself

__le__(other)¶: an MinusInfTime object is always less than or equal to any other object.

__eq__(other)¶: A MinusInfTime object is only equal to itself

__ne__(other)¶: A MinusInfTime object is only equal to itself

__gt__(other)¶: A MinusInfTime object is not greater than anything

__ge__(other)¶: A Minus InfTime object is not greater than or equal to anything other than itself

__pos__()¶

__neg__()¶

class gnome.scripting.InfTime¶

Bases: object

class representing time into infinity

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

__str__()¶: Return str(self).

__repr__()¶: Return repr(self).

isoformat()¶

__lt__(other)¶: an InfTime object is never less than any other object

__le__(other)¶: an InfTime object is never less than or equal to any other object otehr than itself.

__eq__(other)¶: an InfTime object is only equal to itself

__ne__(other)¶: an InfTime object is only equal to itself

__gt__(other)¶: an InfTime object is greater than eveything except another InfTime object

__ge__(other)¶: an InfTime object is greater or equal to anything

__pos__()¶

__neg__()¶

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

property all_array_types¶: Need to add array types from Release and Substance

property substance¶

property release_time¶

property end_release_time¶

property release_duration¶

property num_elements¶

property start_position¶

property end_position¶

property amount¶

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

_schema¶

valid_vol_units¶

valid_mass_units¶

__repr__()¶: Return repr(self).

_check_units(units)¶: Checks the user provided units are in list of valid volume or mass units

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.

_attach_default_refs(ref_dict)¶

!!!IMPORTANT!!! If this object requires default references (self._req_refs exists), this function will use the name of the references as keys into a reference dictionary to get a list of satisfactory references (objects that have obj._ref_as == self._req_refs). It will then attach the first object in the reference list to that attribute on this object.

This behavior can be overridden if the object needs more specific attachment behavior than simply ‘first in line’

In addition, this function SHOULD BE EXTENDED if this object should provide default references to any contained child objects. When doing so, please be careful to respect already existing references. The reference attachment system should only act if the requested reference ‘is None’ when the function is invoked. See Model._attach_default_refs() for an example.

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 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¶

property start_position¶

property end_position¶

_schema¶

__repr__()¶: Return repr(self).

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

initialize_LEs_post_substance(to_rel, sc, start_time, end_time, environment)¶

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¶

property __geo_interface__¶

property features¶

property polygons¶

property thicknesses¶

property weights¶

property areas¶

_schema¶

gen_fc_from_kwargs(kwargs)¶

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 returns a 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 or Line Release')¶

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, postive 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 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='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¶

_schema¶

The simplest substance that can be used with the model

It can not be weathered, but does have basic properties for transport:

Windage, density, etc.

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:

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

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)

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)

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

_schema¶

_req_refs = ['water']¶

from_adiosdb_file(filename, kwargs)¶

_set_up_array_types()¶

_init_from_json(*, api, pour_point, solubility, bullwinkle_fraction, original_bullwinkle_fraction=None, bullwinkle_time=None, original_bullwinkle_time=None, emulsion_water_fraction_max, densities, density_ref_temps, density_weathering, kvis, kvis_ref_temps, kvis_weathering, mass_fraction, boiling_point, molecular_weight, component_density, sara_type=None, adios_oil_id=None, k0y=None, num_components=None, **kwargs)¶

__hash__()¶

needs to be hashable, so that it can be used in lru-cache

Oils will only hash equal if they are the same object – that’s limiting, but OK.

__deepcopy__(memo)¶

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

_set_pc_values(prop, values)¶

utility that sets a property to each pseudo component

checks that it’s the right size, and converts to an array

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.

_get_reference_densities(densities, temperature)¶

Given a temperature, we return the best measured density, and its reference temperature, to be used in calculation.

For our purposes, it is the density closest to the given temperature.

_vol_expansion_coeff(densities, temperature)¶

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 –

property time¶

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

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

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

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

_ref_as = 'wind'¶

_gnome_unit = 'm/s'¶

_schema¶

valid_vel_units¶

update_from_dict(dict_, refs=None)¶

_check_units(units)¶: Checks the user provided units are in list Wind.valid_vel_units

__repr__()¶: Return repr(self).

new_set_timeseries(value, coord_sys)¶

_convert_units(data, coord_sys, from_unit, to_unit)¶: method to convert units for the ‘value’ stored in the date/time value pair

_write_timeseries_to_zip(saveloc, ts_name)¶: use a StringIO type of file descriptor and write directly to zipfile

_write_timeseries_to_file(datafile)¶: write timeseries data to file

_write_timeseries_to_fd(fd)¶

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

Writes the “OSSM format” with the full header

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

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

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

Parameters:

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

Returns:

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

Note

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

todo: return data in appropriate significant digits

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

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

Parameters:

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

get_value(time)¶

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

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

Note

It invokes get_wind_data(..) function

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

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

Parameters:

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

set_speed_uncertainty(up_or_down=None)¶

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

For each wind value in our time series:

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

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

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

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

gnome.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__(…)

property delay¶

property repeat¶

property map_filename¶

property draw_ontop¶

property formats¶

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_?????.*'¶

_schema¶

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)

_draw(step_num)¶: create a small function so prop arrays are garbage collected from memory after this function exits - it returns current_time_stamp

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

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¶

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',...¶

_schema¶

_update_var_attributes(spills)¶: update instance specific self._var_attributes

_initialize_rootgrp(rootgrp, sc)¶: create dimensions for root group and set cf_attributes

_update_arrays_to_output(sc)¶: create list of variables that we want to put in the file

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

_create_nc_var(grp, var_name, dtype, shape, chunksz)¶

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.

_zip_output_files()¶

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

_schema¶

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

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.

_valid_file_formats¶

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

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

_schema¶

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, uncertain_boundary_separate_by_spill=True, uncertain_boundary_hull_ratio=0.5, uncertain_boundary_hull_allow_holes=False, 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

_schema¶

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

__del__()¶

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

_schema¶

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.

__getstate__()¶

This is to support pickle.dumps() inside the uncertainty model subprocesses. We need to be able to pickle our weathering outputters so that our uncertainty subprocesses can send them back to the parent process through a message queue. And the cache attribute (specifically, the ElementCache.lock attribute) can not be pickled, and instead produces a RuntimeError.

(Note: The __setstate__() probably doesn’t need to recreate the: ElementCache since it will be created inside the Model.setup_model_run() function.)

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.

property raster_size¶: Maximum physical size of the raster in bytes

_schema¶

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

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

property map_bounds¶

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

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

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.

_schema¶

refloat_halflife¶

_ref_as = 'map'¶

__add__(other)¶

get_polygons()¶

_attr_from_list_to_array(l_)¶: dict returned as list of tuples to be converted to numpy array Again used to update_from_dict map_bounds and spillable_area

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

_set_off_map_status(sc)¶

Determines which elements moved off the map

Called by beach_elements after checking for land-hits

Parameters:: sc (gnome.spill_container.SpillContainer) – current SpillContainer

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)

_schema¶

init_from_gridcur(filename, extrapolation_is_allowed, **kwargs)¶: Wrapper for external initalize function

classmethod new_from_dict(serial_dict)¶

creates a new object from dictionary

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

class gnome.scripting.GridCurrent(angle=None, **kwargs)¶

Bases: VelocityGrid, gnome.environment.environment.Environment

GridCurrent is VelocityGrid that adds specific stuff for currents:

Information about how to find currents in netCDF file
Ability to apply an angle adjustment of grid-aligned currents
overloading the memorization to memoize the angle-adjusted current.
add a get_data_vectors() provides magnitude, direction – used to draw the currents in a GUI

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

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

_ref_as = 'current'¶

_gnome_unit = 'm/s'¶

default_names¶

cf_names¶

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

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

Parameters:

points (Nx2 or Nx3 array of double) – Coordinates to be queried (P)
time (datetime.datetime object) – The time at which to query these points (T)
units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)
extrapolate (boolean (True or False)) – if True, extrapolation will be supported

Returns:

returns a Nx2 array of interpolated values

Return type:

double

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

property speed¶

property direction¶

property u¶

property v¶

_ref_as = 'current'¶

_schema¶

data_start¶

data_stop¶

__repr__()¶: Return repr(self).

_set_uv()¶

at(points, time, units=None)¶

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

Parameters:

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

Returns:

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

class gnome.scripting.GridWind(wet_dry_mask=None, *args, **kwargs)¶

Bases: VelocityGrid, gnome.environment.environment.Environment

Gridded winds – usually from netcdf files from meteorological models.

This will most often be initialized from netcdf files as:

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

filename can be:

An already open netCDF4 Dataset
A single path to a netcdf file
A list of paths to a set of netcdf files with timeseries

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

_ref_as = 'wind'¶

_gnome_unit = 'm/s'¶

default_names¶

cf_names¶

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

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

Parameters:

points (Nx2 array of double) – Coordinates to be queried (P)
time (datetime.datetime object) – The time at which to query these points (T)
depth (integer) – Specifies the depth level of the variable
units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)
extrapolate (boolean (True or False)) – if True, extrapolation will be supported
coord_sys (string, one of ('uv','u','v','r-theta','r','theta')) – String describing the coordinate system to be used.

Returns:

returns a Nx2 array of interpolated values

Return type:

double

transform_result(value, coord_sys)¶

get_start_time()¶

get_end_time()¶

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

_ref_as = ['current', 'ice_aware']¶

_req_refs¶

_schema¶

classmethod from_netCDF(*args, **kwargs)¶

create a new VectorVariable object from a netcdf file

See init_from_netcdf for signature

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

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

Parameters:

filename (string) – Default data source. Parameters below take precedence
varnames ([] of string) – Names of the variables in the data source file
grid_topology ({string : string, ...}) – Description of the relationship between grid attributes and variable names.
name (string) – Name of property
units (string) – Units
time ([] of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data
data (netCDF4.Variable or numpy.array) – Underlying data source
grid (pysgrid or pyugrid) – Grid that the data corresponds with
dataset (netCDF4.Dataset) – Instance of open Dataset
data_file (string) – Name of data source file
grid_file (string) – Name of grid source file

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

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

Parameters:

points (Nx2 or Nx3 array of double) – Coordinates to be queried (P)
time (datetime.datetime object) – The time at which to query these points (T)
units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)
extrapolate (boolean (True or False)) – if True, extrapolation will be supported

Returns:

returns a Nx2 array of interpolated values

Return type:

double

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

_ref_as = ['wind', 'ice_aware']¶

_req_refs¶

_schema¶

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

create a new VectorVariable object from a netcdf file

See init_from_netcdf for signature

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

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

Parameters:

points (Nx2 array of double) – Coordinates to be queried (P)
time (datetime.datetime object) – The time at which to query these points (T)
depth (integer) – Specifies the depth level of the variable
units (string such as ('m/s', 'knots', etc)) – units the values will be returned in (or converted to)
extrapolate (boolean (True or False)) – if True, extrapolation will be supported
coord_sys (string, one of ('uv','u','v','r-theta','r','theta')) – String describing the coordinate system to be used.

Returns:

returns a Nx2 array of interpolated values

Return type:

double

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

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

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

Parameters:

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

property extrapolation_is_allowed¶

property data_start¶

property data_stop¶

property yeardata¶

_ref_as = 'tide'¶

_schema¶

scale_factor¶

_obj_to_create(filename)¶: open file, read a few lines to determine if it is an ossm file or a shio file

class gnome.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'}

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

property data_stop¶

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

property units¶

_ref_as = 'water'¶

_field_descr¶

_schema¶

_units_type¶

_gnome_units¶

__str__¶

__repr__()¶: Return repr(self).

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

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

static _get_density(salinity, temp, temp_units)¶: use lru cache so we don’t recompute if temp is not changing

_convert_sediment_units(from_, to)¶: used internally to convert to/from sediment units.

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

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

property data_stop¶

_ref_as = 'waves'¶

_req_refs = ['wind', 'water']¶

_schema¶

validate()¶

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

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

Logs warnings:

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

get_value(points, time)¶

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

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

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

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

get_emulsification_wind(points, time)¶

Return the right wind for the wave climate

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

If not, then you need the actual wind.

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

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

compute_H(U)¶

pseudo_wind(H)¶

whitecap_fraction(U)¶

mean_wave_period(U)¶

peak_wave_period(points, time)¶

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

dissipative_wave_energy(H)¶

energy_dissipation_rate(H, U)¶

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

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

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

class gnome.scripting.IceVelocity(angle=None, **kwargs)¶

Bases: VelocityGrid, gnome.environment.environment.Environment

A class for assigning a unique ID for an object

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

_ref_as = ['ice_velocity', 'ice_aware']¶

_gnome_unit = 'm/s'¶

default_names¶

cf_names¶

class gnome.scripting.IceConcentration(*args, **kwargs)¶

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

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

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

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

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

This class represents a value defined on a grid

Parameters:

name (string) – Name
units (string) – Units
time (list of datetime.datetime, netCDF4 Variable, or Time object) – Time axis of the data
data (array-like object such as netCDF4.Variable or numpy.ndarray) – Underlying data source
grid (Grid object (pysgrid or pyugrid or )) – Grid that the data corresponds with
data_file (string) – Name of data source file
grid_file (string) – Name of grid source file
varname (string) – Name of the variable in the data source file
fill_value – the fill value used for undefined data
location (str) – location on the grid – possible values depend on the grid type
attributes (dict) – attributes associated with the Variable (analogous to netcdf variable attributes)

_ref_as = ['ice_concentration', 'ice_aware']¶

default_names¶

cf_names¶

_gnome_unit = 'fraction'¶

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

property data_start¶

property data_stop¶

property diffusion_coef¶

property uncertain_factor¶

_schema¶

__repr__()¶: Return repr(self).

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.

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¶

_schema¶

__repr__()¶: Return repr(self).

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.

property wind¶

property data_start¶

property data_stop¶

_schema¶

_ref_as = 'wind_mover'¶

_req_refs¶

__repr__()¶: Return repr(self).

__str__()¶: Return str(self).

prepare_for_model_run()¶: if wind attribute is not set, raise ReferencedObjectNotSet excpetion

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.

_schema¶

__repr__()¶

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, time_offset=0, 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
time_offset – Time zone shift if data is in GMT
num_method – Numerical method for calculating movement delta. Choices:(‘Euler’, ‘RK2’, ‘RK4’) Default: RK2

property data_start¶

property data_stop¶

_schema¶

_ref_as = 'py_wind_movers'¶

_req_refs¶

classmethod from_netCDF(filename=None, time_offset=0, 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)¶

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, time_offset=0, 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
time_offset – Time zone shift: not functional
default_num_method – Numerical method for calculating movement delta. Choices:(‘Euler’, ‘RK2’, ‘RK4’) Default: RK2

property filename¶

property data_start¶

property data_stop¶

_schema¶

_ref_as = 'py_current_movers'¶

_req_refs¶

classmethod from_netCDF(filename=None, name=None, time_offset=0, 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

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

_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)¶

add uncertainty

Parameters:: deltas – the movement for the current time step

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.

_schema¶

_req_refs¶

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.

_schema¶

__repr__()¶: Return repr(self).

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

gnome.scripting¶

Submodules¶

Package Contents¶

Classes¶

Functions¶

Attributes¶

`gnome.scripting`¶