:py:mod:`gnome.spills.gnome_oil` ================================ .. py:module:: gnome.spills.gnome_oil Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: gnome.spills.gnome_oil.Density gnome.spills.gnome_oil.GnomeOil Functions ~~~~~~~~~ .. autoapisummary:: gnome.spills.gnome_oil.density_at_temp gnome.spills.gnome_oil.vol_expansion_coeff gnome.spills.gnome_oil.kvis_at_temp .. py:class:: Density(kg_m_3, ref_temp_k, weathering=0) Bases: :py:obj:`object` .. py:method:: __repr__() Return repr(self). .. py:function:: density_at_temp(ref_density, ref_temp_k, temp_k, k_rho_t=0.0008) Source: Adios2 If we have an oil density at a reference temperature, then we can estimate what its density might be at another temperature. NOTE: need a reference for the coefficient of expansion .. py:function:: vol_expansion_coeff(rho_0, t_0, rho_1, t_1) Calculate the volumetric expansion coefficient of a liquid based on a set of two densities and their associated temperatures. .. py:function:: kvis_at_temp(ref_kvis, ref_temp_k, temp_k, k_v2=2100) Source: Adios2 If we have an oil kinematic viscosity at a reference temperature, then we can estimate what its viscosity might be at another temperature. .. note:: An analysis of the multi-KVis oils in our oil library suggest that a value of 2100 would be a good default value for k_v2. .. py:class:: GnomeOil(oil_name=None, filename=None, water=None, **kwargs) Bases: :py:obj:`gnome.spills.substance.Substance` Class to create an oil for use in Gnome Initialize a GnomeOil: :param oil_name=None: Name of one of the sample oils provided by: ``gnome.spills.sample_oils`` :param filename=None: filename (Path) of JSON file in the Adios Oil Database format. :param water=None: Water object with environmental conditions -- Deprecated. Additional keyword arguments will be passed to Substance: e.g.: ``windage_range``, ``windage_persist=None``, A GnomeOil can be initialized in three ways: 1) From a sample oil name : ``GnomeOil(oil_name="sample_oil_name")`` the oils are available in gnome.spills.sample_oils 2) From a JSON file in the ADIOS Oil Database format: ``GnomeOil(filename="adios_oil.json")`` usually records from the ADIOS Oil Database (https://adios.orr.noaa.gov) 3) From the json : ``GnomeOil.new_from_dict(**json_)`` for loading save files, etc. (this is usually done under the hood) GnomeOil("sample_oil_name") ---works for test oils from sample_oils only GnomeOil(oil_name="sample_oil_name") GnomeOil(filename="oil.json") ---load from file using adios_db GnomeOil.new_from_dict(**json\_) ---webgnomeclient, savefiles, etc. GnomeOil("invalid_name") ---ValueError (not in sample oils) .. py:property:: standard_density Standard density is simply the density at 15C, which is the default temperature for density_at_temp() .. py:attribute:: _schema .. py:attribute:: _req_refs :value: ['water'] .. py:method:: from_adiosdb_file(filename, kwargs) .. py:method:: _set_up_array_types() .. py:method:: _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) .. py:method:: __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. .. py:method:: __deepcopy__(memo) .. py:method:: get_GnomeOil(oil_info, max_cuts=None) :classmethod: #fixme: what is oil_info ??? Use this instead of get_oil_props .. 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_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 .. py:method:: _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 .. py:method:: 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 :param temp: temperature in K :returns: vapor_pressure array in SI units (Pascals) ## Fixme: shouldn't this be in the Evaporation code? .. py:method:: bounding_temperatures(obj_list, temperature) :classmethod: 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 .. py:method:: 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 .. py:method:: 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. .. py:method:: _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. .. py:method:: _vol_expansion_coeff(densities, temperature) .. py:method:: closest_to_temperature(obj_list, temperature, num=1) :classmethod: 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 .. py:method:: kvis_at_temp(temp_k=288.15, weathering=0.0) Compute the kinematic viscosity of the oil as a function of temperature :param temp_k: temperatures to compute at: can be scalar or array of values. should be in Kelvin :param 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 .. py:method:: 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. .. py:method:: get(prop) get oil props