:py:mod:`gnome.spills.spill` ============================ .. py:module:: gnome.spills.spill .. autoapi-nested-parse:: 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 ~~~~~~~ .. autoapisummary:: gnome.spills.spill.BaseSpill gnome.spills.spill.Spill Functions ~~~~~~~~~ .. autoapisummary:: gnome.spills.spill._setup_spill gnome.spills.spill.point_line_spill gnome.spills.spill.surface_point_line_spill gnome.spills.spill.grid_spill gnome.spills.spill.subsurface_spill gnome.spills.spill.spatial_release_spill gnome.spills.spill.polygon_release_spill .. py:class:: BaseSpill(name=None, _appearance=None, *args, **kwargs) Bases: :py:obj:`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. .. py:class:: Spill(on=True, num_elements=1000, amount=0, units='kg', substance=None, release=None, water=None, amount_uncertainty_scale=0.0, **kwargs) Bases: :py:obj:`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). :param release: an object defining how elements are to be released :type release: derived from :class:`~gnome.spills.release.Release` :param substance: an object defining the substance of this spill. Defaults to :class:`~gnome.spills.substance.NonWeatheringSubstance` :type substance: derived from :class:`~gnome.spills.substance.Substance` **Optional parameters (kwargs):** :param name: Human-usable Name of this spill :type name: str :param on=True: Toggles the spill on/off. :type on: bool :param amount=None: mass or volume of oil spilled. :type amount: double (volume or mass) :param units=None: must provide units for amount spilled. :type units: str :param 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. :type amount_uncertainty_scale: float .. note:: Define either volume or mass in 'amount' attribute and provide appropriate 'units'. .. py:property:: all_array_types Need to add array types from Release and Substance .. py:property:: substance .. py:property:: release_time .. py:property:: end_release_time .. py:property:: release_duration .. py:property:: num_elements .. py:property:: start_position .. py:property:: end_position .. py:property:: amount .. py:property:: units Default units in which amount of oil spilled was entered by user. The 'amount' property is returned in these 'units' .. py:attribute:: _schema .. py:attribute:: valid_vol_units .. py:attribute:: valid_mass_units .. py:method:: __repr__() Return repr(self). .. py:method:: _check_units(units) Checks the user provided units are in list of valid volume or mass units .. py:method:: get_mass() Return the total mass released during the spill. .. py:method:: 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. .. py:method:: 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. .. py:method:: rewind() rewinds the release to original status (before anything has been released). .. py:method:: 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 .. py:method:: 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 .. py:method:: 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() :param current_time: current time :type current_time: datetime.datetime :param int time_step: 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. .. py:method:: _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. .. py:function:: _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 .. py:function:: 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 :param num_elements: total number of elements to be released :type num_elements: integer :param start_position: initial location the elements are released :type 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 :param release_time: time the LEs are released (datetime object) :type release_time: datetime.datetime :param end_position=None: Optional. For moving source, the end position If None, then release is from a point source :type end_position: 2-tuple of floats (long, lat) :param end_release_time=None: optional -- for a time varying release, the end release time. If None, then release is instantaneous :type end_release_time: datetime.datetime :param substance=None: Type of oil spilled. :type substance: Substance object :param amount=None: mass or volume of oil spilled :type amount: float :param units=None: units for amount spilled :type units: str :param tuple windage_range=(.01, .04): Percentage range for windage. Active only for surface particles when a mind mover is added :type windage_range: tuple :param windage_persist=900: Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale :type windage_persist: int :param name='Point/Line Spill': a name for the spill :type name: str .. py:function:: 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 :param num_elements: total number of elements to be released :type num_elements: integer :param start_position: initial location the elements are released :type start_position: 2-tuple of floats (long, lat) :param release_time: time the LEs are released (datetime object) :type release_time: datetime.datetime :param end_position=None: Optional. For moving source, the end position If None, then release is from a point source :type end_position: 2-tuple of floats (long, lat) :param end_release_time=None: optional -- for a time varying release, the end release time. If None, then release is instantaneous :type end_release_time: datetime.datetime :param substance=None: Type of oil spilled. :type substance: Substance object :param amount=None: mass or volume of oil spilled :type amount: float :param units=None: units for amount spilled :type units: str :param tuple windage_range=(.01, .04): Percentage range for windage. Active only for surface particles when a mind mover is added :type windage_range: tuple :param windage_persist=900: Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale :type windage_persist: int :param name='Surface Point/Line Spill': a name for the spill :type name: str .. py:function:: 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 :param bounds: bounding box of region you want the elements in: ((min_lon, min_lat), (max_lon, max_lat)) :type bounds: 2x2 numpy array or equivalent :param resolution: resolution of grid -- it will be a resoluiton X resolution grid :type resolution: integer :param substance=None: Type of oil spilled. :type substance: str or OilProps :param float amount=None: mass or volume of oil spilled :param str units=None: units for amount spilled :param release_time: time the LEs are released (datetime object) :type release_time: datetime.datetime :param tuple windage_range=(.01, .04): Percentage range for windage. Active only for surface particles when a mind mover is added :param int windage_persist=900: Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale :param str name='Surface Point/Line Release': a name for the spill .. py:function:: 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 :param num_elements: total number of elements to be released :type num_elements: integer :param start_position: initial location the elements are released :type start_position: 3-tuple of floats (long, lat, z) :param release_time: time the LEs are released (datetime object) :type release_time: datetime.datetime :param distribution=None: An object capable of generating a probability distribution. Right now, we have: * UniformDistribution * NormalDistribution * LogNormalDistribution * WeibullDistribution :type distribution: gnome.utilities.distribution :param str distribution_type=droplet_size: What is being sampled from the distribution. Options are: * droplet_size - Rise velocity is then calculated * rise_velocity - No droplet size is computed :param end_release_time=None: End release time for a time varying release. If None, then release is instantaneous :type end_release_time: datetime.datetime :param substance=None: Required unless density specified. Type of oil spilled. :type substance: GnomeOil :param float density=None: Required unless substance specified. Density of spilled material. :param str density_units='kg/m^3': :param float amount=None: mass or volume of oil spilled. :param str units=None: must provide units for amount spilled. :param tuple windage_range=(.01, .04): Percentage range for windage. Active only for surface particles when a mind mover is added :param windage_persist=900: Persistence for windage values in seconds. Use -1 for inifinite, otherwise it is randomly reset on this time scale. :param str name='Subsurface Release': a name for the spill. .. py:function:: 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. .. py:function:: 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.