:py:mod:`gnome.spills.initializers` =================================== .. py:module:: gnome.spills.initializers .. autoapi-nested-parse:: Utilities for initializing data arrays associated with the elements This code is kept separately here to make it easier to mix and match for various release and substance types. Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.spills.initializers.InitBaseClass gnome.spills.initializers.InitWindages gnome.spills.initializers.InitMassFromPlume gnome.spills.initializers.DistributionBase gnome.spills.initializers.InitRiseVelFromDist gnome.spills.initializers.InitRiseVelFromDropletSizeFromDist Functions ~~~~~~~~~ .. autoapisummary:: gnome.spills.initializers.plume_initializers gnome.spills.initializers.plume_from_model_initializers .. py:class:: InitBaseClass(*args, **kwargs) Bases: :py:obj:`gnome.gnomeobject.GnomeId` All Init* classes will define the _state attribute, so just do so in a base class. It also documents that all initializers must implement an initialize method .. py:method:: initialize(num_new_particles, spill, data_arrays, substance) all classes that derive from Base class must implement an initialize method. This method should initialize the appropriate data in the data arrays dict. See subclasses for examples. .. py:class:: InitWindages(windage_range=(0.01, 0.04), windage_persist=900, *args, **kwargs) Bases: :py:obj:`InitBaseClass` All Init* classes will define the _state attribute, so just do so in a base class. It also documents that all initializers must implement an initialize method Initializes the windages, windage_range, windage_persist data arrays. Initial values for windages use infinite persistence. These are updated by the PointWindMover for particles with non-zero persistence. Optional arguments: :param windage_range: the windage range of the elements. Default is (0.01, 0.04) from 1% to 4%. :type windage_range: tuple: (min, max) :param windage_persist: Default is 900s, so windage is updated every 900 seconds. -1 means the persistence is infinite so it is only set at the beginning of the run. :type windage_persist: integer seconds .. py:attribute:: _schema .. py:method:: __repr__() Return repr(self). .. py:method:: 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. .. py:method:: initialize(num_new_particles, data_arrays, substance) Since windages exists in data_arrays, so must windage_range and windage_persist if this initializer is used/called .. py:class:: InitMassFromPlume Bases: :py:obj:`InitBaseClass` Initialize the 'mass' array based on mass flux from the plume spilled update array_types .. py:attribute:: _schema .. py:method:: initialize(num_new_particles, data_arrays, substance) all classes that derive from Base class must implement an initialize method. This method should initialize the appropriate data in the data arrays dict. See subclasses for examples. .. py:class:: DistributionBase(*args, **kwargs) Bases: :py:obj:`InitBaseClass` Define a base class for all initializers that contain a distribution. Keep the code to serialize/deserialize distribution objects here so we only have to write it once. .. py:attribute:: _schema .. py:class:: InitRiseVelFromDist(distribution=None, **kwargs) Bases: :py:obj:`DistributionBase` Define a base class for all initializers that contain a distribution. Keep the code to serialize/deserialize distribution objects here so we only have to write it once. Set the rise velocity parameters to be sampled from a distribution. :param distribution: An initialized distribution object. It should return values in m/s :type distribution: DistributionBase See gnome.utilities.distribution for details Right now, we have: * UniformDistribution * NormalDistribution * LogNormalDistribution * WeibullDistribution New distribution classes could be made. The only requirement is they need to have a set_values() method which accepts a NumPy array. (presumably, this function will also modify the array in some way) .. py:method:: initialize(num_new_particles, data_arrays, substance) all classes that derive from Base class must implement an initialize method. This method should initialize the appropriate data in the data arrays dict. See subclasses for examples. .. py:class:: InitRiseVelFromDropletSizeFromDist(distribution=None, water_density=1020.0, water_viscosity=1e-06, **kwargs) Bases: :py:obj:`DistributionBase` Define a base class for all initializers that contain a distribution. Keep the code to serialize/deserialize distribution objects here so we only have to write it once. Set the droplet size from a distribution. Use the C++ get_rise_velocity function exposed via cython (rise_velocity_from_drop_size) to obtain rise_velocity from droplet size. Even though the droplet size is not changing over time, it is still stored in data array, as it can be useful for post-processing (called 'droplet_diameter') :param distribution: An object capable of generating a probability distribution. :type distribution: Right now, we have: * UniformDistribution * NormalDistribution * LogNormalDistribution * WeibullDistribution New distribution classes could be made. The only requirement is they need to have a set_values() method which accepts a NumPy array. (presumably, this function will also modify the array in some way) :param water_density: 1020.0 [kg/m3] :type water_density: float :param water_viscosity: 1.0e-6 [m^2/s] :type water_viscosity: float .. py:method:: initialize(num_new_particles, data_arrays, substance) Update values of 'rise_vel' and 'droplet_diameter' data arrays for new particles. First create a droplet_size array sampled from specified distribution, then use the cython wrapped (C++) function to set the 'rise_vel' based on droplet size and properties like LE_density, water density and water_viscosity: gnome.cy_gnome.cy_rise_velocity_mover.rise_velocity_from_drop_size() .. py:function:: plume_initializers(distribution_type='droplet_size', distribution=None, windage_range=(0.01, 0.04), windage_persist=900, **kwargs) Helper function returns an ElementType object containing 'rise_vel' and 'windages' initialized with user specified parameters for distribution. :param str distribution_type: type of distribution, 'droplet_size' or 'rise_velocity' :param gnome.utilities.distributions distribution=None: :param windage_range: minimum and maximum windage :type windage_range: tuple-of-floats :param int windage_persist: persistence of windage in seconds :param str substance_name=None: :param float density=None: :param str density_units='kg/m^3': Distribution type available options: * 'droplet_size': Droplet size is sampled from the specified distribution. No droplet size is computed. * 'rise_velocity': Rise velocity is directly sampled from the specified distribution. Rise velocity is calculated. Distributions - An object capable of generating a probability distribution. Right now, we have: * UniformDistribution * NormalDistribution * LogNormalDistribution * WeibullDistribution New distribution classes could be made. The only requirement is they need to have a ``set_values()`` method which accepts a NumPy array. (presumably, this function will also modify the array in some way) .. note:: substance_name or density must be provided .. py:function:: plume_from_model_initializers(distribution_type='droplet_size', distribution=None, windage_range=(0.01, 0.04), windage_persist=900, **kwargs) Helper function returns an ElementType object containing 'rise_vel' and 'windages' initializer with user specified parameters for distribution.