`opendrift.models.openoil`

Subpackages

opendrift.models.openoil.adios

Submodules

Package Contents

Classes

`OceanDrift`	Open source buoyant particle trajectory model based on OpenDrift.
`Lagrangian3DArray`	Extending LagrangianArray for elements moving in 3 dimensions
`Oil`	Extending LagrangianArray with variables relevant for oil particles.
`OpenOil`	Open source oil trajectory model based on the OpenDrift framework.

Functions

oil_wave_entrainment_rate_li2017(dynamic_viscosity, ...)

Attributes

`logger`
`CONFIG_LEVEL_ESSENTIAL`
`CONFIG_LEVEL_BASIC`
`CONFIG_LEVEL_ADVANCED`

opendrift.models.openoil.logger

class opendrift.models.openoil.OceanDrift(*args, **kwargs)[source]

Bases: opendrift.models.basemodel.OpenDriftSimulation

Open source buoyant particle trajectory model based on OpenDrift.

Developed at MET Norway

Generic module for particles that move in 3 dimensions and may be to vertical turbulent mixing with the possibility for positive or negative buoyancy

Particles could be e.g. oil droplets, plankton, nutrients or sediments, Model may be subclassed for more specific behaviour.

Initialise OpenDriftSimulation

Args:

seed: integer or None. A given integer will yield identical: random numbers drawn each simulation. Random numbers are e.g. used to distribute particles spatially when seeding, and may be used by modules (subclasses) for e.g. diffusion. Specifying a fixed value (default: 0) is useful for sensitivity tests. With seed = None, different random numbers will be drawn for subsequent runs, even with identical configuration/input.
iomodule: name of module used to export data: default: netcdf, see opendrift.io for more alternatives. iomodule is module/filename without preceeding io_
loglevel: set to 0 (default) to retrieve all debug information.: Provide a higher value (e.g. 20) to receive less output. Use the string ‘custom’ to configure logging from outside.
logtime: if True, a time stamp is given for each logging line.: logtime can also be given as a python time specifier (e.g. ‘%H:%M:%S’)

ElementType

required_variables

update()[source]: Update positions and properties of elements.

simulate_trajectories(outfile, trajectories, number=1, wind_drift_factors=None, current_drift_factors=None, time_step=None, time_step_output=None, simulation_duration=None, simulation_interval=None)[source]

wind_drift_factor_from_trajectory_lw(drifters, wind_drift_factors, simulation_length, simulation_interval)[source]

Perform simulations and use skillscore to optimize wind_drift_factor

drifters: list of dictionaries with numpy arrays of ‘lon’ and ‘lat’: and list of datetimes

wind_drift_factors: the wind_drift_factors to use for simulations/optimalizations

machine_learning_correction()[source]

disable_vertical_motion()[source]: Deactivate any vertical processes/advection

update_terminal_velocity(Tprofiles=None, Sprofiles=None, z_index=None)[source]: Calculate terminal velocity due to bouyancy from own properties and environmental variables. Sub-modules should overload this method for particle-specific behaviour

prepare_vertical_mixing()[source]

prepare_run()[source]

vertical_advection()[source]

Move particles vertically according to vertical ocean current

Vertical advection by ocean currents is normally small compared to termical velocity

vertical_buoyancy()[source]: Move particles vertically according to their buoyancy

surface_stick()[source]: To be overloaded by subclasses, e.g. downward mixing of oil

bottom_interaction(Zmin=None)[source]: To be overloaded by subclasses, e.g. radionuclides in sediments

surface_wave_mixing(time_step_seconds)[source]: To be overloaded by subclasses, e.g. downward mixing of oil

get_diffusivity_profile(model, depths)[source]

vertical_mixing(store_depths=False)[source]

Mix particles vertically according to eddy diffusivity and buoyancy

Buoyancy is expressed as terminal velocity, which is the steady-state vertical velocity due to positive or negative buoyant behaviour. It is usually a function of particle density, diameter, and shape.

Vertical particle displacemend du to turbulent mixing is calculated using a random walk scheme” (Visser et al. 1996)

animate_vertical_distribution(depths=None, maxdepth=None, bins=50, filename=None, subsamplingstep=1)[source]: Function to animate vertical distribution of particles bins: number of bins in the histogram maxdepth: maximum depth subsamplingstep: speed-up the generation of the animation reducing the number of output frames fasterwriter: speed-up the writing to outpute file

plot_vertical_distribution(maxdepth=None, bins=None, maxnum=None)[source]

Function to plot vertical distribution of particles

maxdepth: maximum depth considered for the profile bins: number of bins between surface and maxdepth maxnum: range of bars in histogram is [0,maxnum]

plotter_vertical_distribution_time(ax=None, mask=None, dz=1.0, maxrange=-100, bins=None, step=1)[source]

Function to plot vertical distribution of particles.

Use mask to plot any selection of particles.

class opendrift.models.openoil.Lagrangian3DArray(**kwargs)[source]

Bases: opendrift.elements.LagrangianArray

Extending LagrangianArray for elements moving in 3 dimensions The Particle may be buoyant and/or subject to vertical mixing buoyant bahaviour is described by terminal velocity

Initialises a LagrangianArray with given properties.

Args:: Keyword arguments (kwargs) with names corresponding to the OrderedDict ‘variables’ of the class, and corresponding values. The values must be ndarrays of equal length, or scalars. All (or none) variables must be given, unless a default value is specified in the OrderedDict ‘variables’ An empty object may be created by giving no input.

variables

opendrift.models.openoil.oil_wave_entrainment_rate_li2017(dynamic_viscosity, oil_density, interfacial_tension, significant_wave_height=None, wave_breaking_fraction=None, wind_speed=None, sea_water_density=1028.0)[source]

opendrift.models.openoil.CONFIG_LEVEL_ESSENTIAL = 1

opendrift.models.openoil.CONFIG_LEVEL_BASIC = 2

opendrift.models.openoil.CONFIG_LEVEL_ADVANCED = 3

class opendrift.models.openoil.Oil(**kwargs)[source]

Bases: opendrift.models.oceandrift.Lagrangian3DArray

Extending LagrangianArray with variables relevant for oil particles.

Initialises a LagrangianArray with given properties.

Args:: Keyword arguments (kwargs) with names corresponding to the OrderedDict ‘variables’ of the class, and corresponding values. The values must be ndarrays of equal length, or scalars. All (or none) variables must be given, unless a default value is specified in the OrderedDict ‘variables’ An empty object may be created by giving no input.

variables

class opendrift.models.openoil.OpenOil(weathering_model='noaa', *args, **kwargs)[source]

Bases: opendrift.models.oceandrift.OceanDrift

Open source oil trajectory model based on the OpenDrift framework.

Developed at MET Norway based on oil weathering parameterisations found in open/published litterature.

Under construction.

Initialise OpenDriftSimulation

Args:

seed: integer or None. A given integer will yield identical: random numbers drawn each simulation. Random numbers are e.g. used to distribute particles spatially when seeding, and may be used by modules (subclasses) for e.g. diffusion. Specifying a fixed value (default: 0) is useful for sensitivity tests. With seed = None, different random numbers will be drawn for subsequent runs, even with identical configuration/input.
iomodule: name of module used to export data: default: netcdf, see opendrift.io for more alternatives. iomodule is module/filename without preceeding io_
loglevel: set to 0 (default) to retrieve all debug information.: Provide a higher value (e.g. 20) to receive less output. Use the string ‘custom’ to configure logging from outside.
logtime: if True, a time stamp is given for each logging line.: logtime can also be given as a python time specifier (e.g. ‘%H:%M:%S’)

ElementType

required_variables

max_speed = 1.3

status_colors

duplicate_oils = ['ALVHEIM BLEND, STATOIL', 'DRAUGEN, STATOIL', 'EKOFISK BLEND 2000', 'EKOFISK BLEND, STATOIL',...

update_surface_oilfilm_thickness()[source]: The mass of oil is summed within a grid of 100x100 cells covering the oil at a given time. Each oil particle within each cell is given a film thickness as the amount of oil divided by the cell area.

biodegradation()[source]

biodegradation_half_time()[source]: Oil biodegradation with exponential decay

biodegradation_adcroft()[source]: Oil biodegradation function based on the article: Adcroft et al. (2010), Simulations of underwater plumes of dissolved oil in the Gulf of Mexico.

disperse()[source]

oil_weathering()[source]

prepare_run()[source]

oil_weathering_noaa()[source]: Oil weathering scheme adopted from NOAA PyGNOME model: https://github.com/NOAA-ORR-ERD/PyGnome

disperse_noaa()[source]

plot_droplet_spectrum()[source]: Plotting distribution of droplet radii, for debugging

evaporation_noaa()[source]

emulsification_noaa()[source]

update_terminal_velocity(Tprofiles=None, Sprofiles=None, z_index=None)[source]

Calculate terminal velocity for oil droplets

according to:

Tkalich et al. (2002): Vertical mixing of oil droplets by breaking waves
Marine Pollution Bulletin 44, 1219-1229

If profiles of temperature and salt are passed into this function, they will be interpolated from the profiles. if not, T,S will be fetched from reader.

oil_wave_entrainment_rate()[source]

prepare_vertical_mixing()[source]: Calculate entrainment probability before main loop

surface_wave_mixing(time_step_seconds)[source]: Mix surface oil into water column.

surface_stick()[source]: set surfaced particles to exactly zero depth to let them form a slick

get_wave_breaking_droplet_diameter()[source]

get_wave_breaking_droplet_diameter_liz2017()[source]

get_wave_breaking_droplet_diameter_johansen2015()[source]

resurface_elements(minimum_depth=None)[source]: Oil elements reaching surface (or above) form slick, not droplet

advect_oil()[source]

update()[source]: Update positions and properties of oil particles.

get_oil_budget()[source]

Get oil budget for the current simulation

The oil budget consists of the following categories:

surface: the sum of variable mass_oil for all active elements where z = 0
submerged: the sum of variable mass_oil for all active elements where z < 0
stranded: the sum of variable mass_oil for all elements which are stranded
evaporated: the sum of variable mass_evaporated for all elements
dispersed: the sum of variable mass_dispersed for all elements

The sum (total mass) shall equal the mass released. Note that the mass of oil is conserved, whereas the volume may change with changes in density and water uptake (emulsification). Therefore mass should be used for budgets, eventually converted to volume (by dividing on density) in the final step before presentation.

Note that mass_oil is the mass of pure oil. The mass of oil emulsion (oil containing entrained water droplets) can be calculated as:

mass_emulsion = mass_oil / (1 - water_fraction)

I.e. water_fraction = 0 means pure oil, water_fraction = 0.5 means mixture of 50% oil and 50% water, and water_fraction = 0.9 (which is maximum) means 10% oil and 90% water.

plot_oil_budget(filename=None, ax=None, show_watercontent_and_viscosity=True, show_wind_and_current=True)[source]

get_oil_name()[source]

cumulative_oil_entrainment_fraction()[source]: Returns the fraction of oil elements which has been entrained vs time

plot_oil_watercontent_and_viscosity(ax=None, show=True)[source]

set_oiltype(oiltype)[source]: Sets the oil type by specifying the name, the first match will be chosen. See the ADIOS database for a list. OpenDrift provides a small set of extra oils.

set_oiltype_by_id(oiltypeid)[source]: Sets the oil type by specifying the ADIOS ID. See the ADIOS database for a list. OpenDrift provides a small set of extra oils.

set_oiltype_by_json(json)[source]: Sets the oil type by specifing a JSON dict. The format should be the same as the ADIOS database. See the ADIOS database for a list.

set_oiltype_from_file(path)[source]

Sets the oil type by specifing a JSON file. The format should be the same as the ADIOS database. See the ADIOS database for a list.

>>> o = OpenOil()
>>> o.set_oiltype_from_file('opendrift/models/openoil/adios/extra_oils/AD04001.json')

store_oil_seed_metadata(**kwargs)[source]

seed_elements(*args, **kwargs)[source]

Seed elements with given position(s), time and properties.

Arguments:

lon: scalar or array: central longitude(s).
lat: scalar or array: central latitude(s).
radius: scalar or array: radius in meters around each lon-lat pair, within which particles will be randomly seeded.
number: integer, total number of particles to be seeded: If number is None, the number of elements is the length of lon/lat or time if these are arrays. Otherwise the number of elements are obtained from the config-default.
time: datenum or list: The time at which particles are seeded/released. If time is a list with two elements, elements are seeded continously from start/first to end/last time. If time is a list with more than two elements, the number of elements is equal to len(time) and are seeded as a time series.
radius_type: string: If ‘gaussian’ (default), the radius is the standard deviation in x-y-directions. If ‘uniform’, elements are spread evenly and always inside a circle with the given radius.
kwargs:: keyword arguments containing properties/attributes and values corresponding to the actual particle type (ElementType). These are forwarded to the ElementType class. All properties for which there are no default value must be specified.

seed_cone(*args, **kwargs)[source]

Seed elements along a transect/cone between two points/times

Arguments:

lon: scalar or list with 2 elements [lon0, lon1]

lat: scalar or list with 2 elements [lat0, lat]

time: datetime or list with 2 elements [t0, t1]

radius: scalar or list with 2 elements [r0, r1] Unit: meters

number (int): The number of elements. If this is None, the number of elements is taken from configuration.

Elements are seeded along a transect from

(lon0, lat0) with uncertainty radius r0 at time t0, towards (lon1, lat1) with uncertainty radius r1 at time t1. If r0 != r1, the unceetainty radius is linearly changed along the transect, thus outlining a “cone”.

seed_from_gml(gmlfile, num_elements=1000, *args, **kwargs)[source]: Read oil slick contours from GML file, and seed particles within.

seed_from_geotiff_thickness(filename, number=50000, *args, **kwargs)[source]: Seed from files as provided by Prof. Chuanmin Hu

_substance_name()[source]

opendrift.models.openoil