gnome.spills.spill

spill.py - An implementation of the spill class(s)

A “spill” is essentially a source of elements. These classes combine

Releases: where and when elements are released and Substance – what the types of the elements are.

(currently there are only two substances: GnomeOIl and NonWeatheringSubstance)

Module Contents

Classes

BaseSpill	A base class for spill, with only what we really need
Spill	Models a spill by combining Release and Substance objects

Functions

_setup_spill(release, water, substance, amount, units, ...)	set the windage on the substance, if it's provided
point_line_spill(num_elements, start_position, ...[, ...])	Helper function returns a Spill object
surface_point_line_spill(num_elements, start_position, ...)	Helper function returns a Spill object
grid_spill(bounds, resolution, release_time[, ...])	Helper function returns a Grid Spill object
subsurface_spill(num_elements, start_position, ...[, ...])	Helper function returns a 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

class gnome.spills.spill.BaseSpill(name=None, _appearance=None, *args, **kwargs)

Bases: gnome.gnomeobject.GnomeId

A base class for spill, with only what we really need

Note: this should have all the methods that the model needs, to define the interface.

for now, the real base is specified by Spill, but this gives us something to derive from to make a whole new one, and still be able to add it to the model.

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

gnome.spills.spill._setup_spill(release, water, substance, amount, units, name, on, windage_range, windage_persist)

set the windage on the substance, if it’s provided

otherwise simply passes everything in to the Spill

gnome.spills.spill.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.spills.spill.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.spills.spill.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.spills.spill.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.spills.spill.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.spills.spill.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.