particle_tracking_manager.models.opendrift.opendrift

Using OpenDrift for particle tracking.

Classes

OpenDriftModel([drift_model, ...])

Open drift particle tracking model.

class particle_tracking_manager.models.opendrift.opendrift.OpenDriftModel(drift_model='OceanDrift', export_variables=['z', 'origin_marker'], radius=1000.0, radius_type='gaussian', horizontal_diffusivity=None, current_uncertainty=0, wind_uncertainty=0, use_auto_landmask=False, diffusivitymodel='windspeed_Large1994', stokes_drift=True, mixed_layer_depth=30, coastline_action='previous', seafloor_action='previous', max_speed=5, wind_drift_factor=0.02, wind_drift_depth=0.02, vertical_mixing_timestep=60, object_type='Person-in-water (PIW), unknown state (mean values)', diameter=0.0014, neutral_buoyancy_salinity=31.25, stage_fraction=0.0, hatched=0, length=0, weight=0.08, oil_type='GENERIC MEDIUM CRUDE', m3_per_hour=1, oil_film_thickness=1, droplet_size_distribution='uniform', droplet_diameter_mu=0.001, droplet_diameter_sigma=0.0005, droplet_diameter_min_subsea=0.0005, droplet_diameter_max_subsea=0.005, emulsification=True, dispersion=True, evaporation=True, update_oilfilm_thickness=True, biodegradation=True, log='low', **kw)

Bases: ParticleTrackingManager

Open drift particle tracking model.

Defaults all come from config_model configuration file.

Parameters:

• drift_model (str, optional) – Options: “OceanDrift”, “LarvalFish”, “OpenOil”, “Leeway”, by default “OceanDrift”

• export_variables (list, optional) – List of variables to export, by default None. See PTM docs for options.

• radius (int, optional) – Radius around each lon-lat pair, within which particles will be randomly seeded. This is used by function seed_elements.

• radius_type (str) – 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. This is used by function seed_elements.

• horizontal_diffusivity (float) – Horizontal diffusivity is None by default but will be set to a grid-dependent value for known ocean_model values. This is calculated as 0.1 m/s sub-gridscale velocity that is missing from the model output and multiplied by an estimate of the horizontal grid resolution. This leads to a larger value for NWGOA which has a larger value for mean horizontal grid resolution (lower resolution). If the user inputs their own ocean_model information, they can input their own horizontal_diffusivity value. A user can use a known ocean_model and then overwrite the horizontal_diffusivity value to some value.

• current_uncertainty (float) – Add gaussian perturbation with this standard deviation to current components at each time step.

• wind_uncertainty (float) – Add gaussian perturbation with this standard deviation to wind components at each time step.

• use_auto_landmask (bool) – Set as True to use general landmask instead of that from ocean_model. Use for testing primarily. Default is False.

• diffusivitymodel (str) – Algorithm/source used for profile of vertical diffusivity. Environment means that diffusivity is acquired from readers or environment constants/fallback. Turned on if vertical_mixing==True.

• stokes_drift (bool, optional) –

  Set to True to turn on Stokes drift, by default True. This enables 3 settings in OpenDrift:

  • o.set_config(‘drift:use_tabularised_stokes_drift’, True)

  • o.set_config(‘drift:tabularised_stokes_drift_fetch’, ‘25000’) # default

  • o.set_config(‘drift:stokes_drift_profile’, ‘Phillips’) # default

  The latter two configurations are not additionally set in OpenDriftModel since they are already the default once stokes_drift is True.

• mixed_layer_depth (float) – Fallback value for ocean_mixed_layer_thickness if not available from any reader. This is used in the calculation of vertical diffusivity.

• coastline_action (str, optional) – Action to perform if a drifter hits the coastline, by default “previous”. Options are ‘stranding’, ‘previous’.

• seafloor_action (str, optional) – Action to perform if a drifter hits the seafloor, by default “deactivate”. Options are ‘deactivate’, ‘previous’, ‘lift_to_seafloor’.

• max_speed (int) – Typical maximum speed of elements, used to estimate reader buffer size.

• wind_drift_factor (float) – Elements at surface are moved with this fraction of the wind vector, in addition to currents and Stokes drift.

• wind_drift_depth (float) – The direct wind drift (windage) is linearly decreasing from the surface value (wind_drift_factor) until 0 at this depth.

• vertical_mixing_timestep (float) – Time step used for inner loop of vertical mixing.

• object_type (str = config_model["object_type"]["default"],) – Leeway object category for this simulation.

• diameter (float) – Seeding value of diameter.

• neutral_buoyancy_salinity (float) – Seeding value of neutral_buoyancy_salinity.

• stage_fraction (float) – Seeding value of stage_fraction.

• hatched (float) – Seeding value of hatched.

• length (float) – Seeding value of length.

• weight (float) – Seeding value of weight.

• oil_type (str) – Oil type to be used for the simulation, from the NOAA ADIOS database.

• m3_per_hour (float) – The amount (volume) of oil released per hour (or total amount if release is instantaneous).

• oil_film_thickness (float) – Seeding value of oil_film_thickness.

• droplet_size_distribution (str) – Droplet size distribution used for subsea release.

• droplet_diameter_mu (float) – The mean diameter of oil droplet for a subsea release, used in normal/lognormal distributions.

• droplet_diameter_sigma (float) – The standard deviation in diameter of oil droplet for a subsea release, used in normal/lognormal distributions.

• droplet_diameter_min_subsea (float) – The minimum diameter of oil droplet for a subsea release, used in uniform distribution.

• droplet_diameter_max_subsea (float) – The maximum diameter of oil droplet for a subsea release, used in uniform distribution.

• emulsification (bool) – Surface oil is emulsified, i.e. water droplets are mixed into oil due to wave mixing, with resulting increase of viscosity.

• dispersion (bool) – Oil is removed from simulation (dispersed), if entrained as very small droplets.

• evaporation (bool) – Surface oil is evaporated.

• update_oilfilm_thickness (bool) – Oil film thickness is calculated at each time step. The alternative is that oil film thickness is kept constant with value provided at seeding.

• biodegradation (bool) – Oil mass is biodegraded (eaten by bacteria).

• log (str, optional) – Options are “low” and “high” verbosity for log, by default “low”

Notes

Docs available for more initialization options with ptm.ParticleTrackingManager?

Attributes:

outfile_name

Output file name.

seed_kws

Gather seed input kwargs.

Methods

add_reader(**kwargs)	Here is where the model output is opened.
all_export_variables()	Output list of all possible export variables.
calc_duration()	Calculate duration based on end_time and start_time.
calc_end_time(changed_variable)	Calculate end time based on other simulation length parameters.
calc_known_horizontal_diffusivity()	Calculate horizontal diffusivity based on known ocean_model.
calc_steps()	Calculate steps based on duration and time_step.
drift_model_config([ptm_level, prefix])	Show config for this drift model selection.
export_variables()	Output list of all actual export variables.
get_configspec(prefix, substring, ...)	Copied from OpenDrift, then modified.
output()	Hold for future output function.
query_reader()	define in child class.
reader_metadata(key)	allow manager to query reader metadata.
run()	Call model run function.
run_add_reader([ds, name, ...])	Might need to cache this if its still slow locally.
run_all()	Run all steps.
run_drifters()	Run the drifters!
run_seed()	Actually seed drifters for model.
seed([lon, lat, z])	Initialize the drifters in space and time
show_config(**kwargs)	Show parameter configuration across both model and PTM.
show_config_model([key, prefix, level, ...])	Show configuring for the drift model selected in configuration.

_add_model_config()

Goal is to combine the config both directions:

• override OpenDrift config defaults with those from opendrift_config as well as include extra information like ptm_level

• bring OpenDrift config parameter metadata into config_model so application could query it to get the ranges, options, etc.

_add_ptm_config()

Add PTM config to overall config.

property _config

Surface the model configuration.

_update_config()

Update configuration between model, PTM additions, and model additions.

add_reader(**kwargs)

Here is where the model output is opened.

all_export_variables()

Output list of all possible export variables.

calc_duration()

Calculate duration based on end_time and start_time.

calc_end_time(changed_variable)

Calculate end time based on other simulation length parameters.

calc_known_horizontal_diffusivity()

Calculate horizontal diffusivity based on known ocean_model.

calc_steps()

Calculate steps based on duration and time_step.

config_model

config_ptm

diffusivitymodel

drift_model

drift_model_config(ptm_level=[1, 2, 3], prefix='')

Show config for this drift model selection.

This shows all PTM-controlled parameters for the OpenDrift drift model selected and their current values, at the selected ptm_level of importance. It includes some additional configuration parameters that are indirectly controlled by PTM parameters.

Parameters:

• ptm_level (int, list, optional) – Options are 1, 2, 3, or lists of combinations. Use [1,2,3] for all. Default is 1.

• prefix (str, optional) – prefix to search config for, only for OpenDrift parameters (not PTM).

duration

end_time

export_variables()

Output list of all actual export variables.

get_configspec(prefix, substring, excludestring, level, ptm_level)

Copied from OpenDrift, then modified.

horizontal_diffusivity

lat

log

logger

loglevel

lon

mixed_layer_depth

o

ocean_model

property outfile_name

Output file name.

output()

Hold for future output function.

query_reader()

define in child class.

reader_metadata(key)

allow manager to query reader metadata.

run()

Call model run function.

run_add_reader(ds=None, name=None, oceanmodel_lon0_360=False, standard_name_mapping=None)

Might need to cache this if its still slow locally.

Parameters:

• ds (xr.Dataset, optional) – Previously-opened Dataset containing ocean model output, if user wants to input unknown reader information.

• name (str, optional) – If ds is input, user can also input name of ocean model, otherwise will be called “user_input”.

• oceanmodel_lon0_360 (bool) – True if ocean model longitudes span 0 to 360 instead of -180 to 180.

• standard_name_mapping (dict) – Mapping of model variable names to standard names.

run_all()

Run all steps.

run_drifters()

Run the drifters!

run_seed()

Actually seed drifters for model.

seed(lon=None, lat=None, z=None)

Initialize the drifters in space and time

… and with any special properties.

property seed_kws

Gather seed input kwargs.

This could be run more than once.

seed_seafloor

show_config(**kwargs)

Show parameter configuration across both model and PTM.

show_config_model(key=None, prefix='', level=None, ptm_level=None, substring='', excludestring='excludestring')

Show configuring for the drift model selected in configuration.

Runs configuration for you if it hasn’t yet been run.

Parameters:

• key (str, optional) – If input, show configuration for just that key.

• prefix (str, optional) – prefix to search config for, only for OpenDrift parameters (not PTM).

• level (int, list, optional) –

  Limit search by level:

  • CONFIG_LEVEL_ESSENTIAL = 1

  • CONFIG_LEVEL_BASIC = 2

  • CONFIG_LEVEL_ADVANCED = 3

  e.g. 1, [1,2], [1,2,3]

• ptm_level (int, list, optional) –

  Limit search by level:

  • Surface to user = 1

  • Medium surface to user = 2

  • Surface but bury = 3

  e.g. 1, [1,2], [1,2,3]. To access all PTM parameters search for ptm_level=[1,2,3].

• substring (str, optional) – If input, show configuration that contains that substring.

• excludestring (str, optional) – configuration parameters are not shown if they contain this string.

Examples

Show all possible configuration for the previously-selected drift model:

>>> manager.show_config()

Show configuration with a specific prefix:

>>> manager.show_config(prefix="seed")

Show configuration matching a substring:

>>> manager.show_config(substring="stokes")

Show configuration at a specific level (from OpenDrift):

>>> manager.show_config(level=1)

Show all OpenDrift configuration:

>>> manager.show_config(level=[1,2,3])

Show configuration for only PTM-specified parameters:

>>> manager.show_config(ptm_level=[1,2,3])

Show configuration for a specific PTM level:

>>> manager.show_config(ptm_level=2)

Show configuration for a single key:

>>> manager.show_config("seed:oil_type")

Show configuration for parameters that are both OpenDrift and PTM-modified:

>>> m.show_config(ptm_level=[1,2,3], level=[1,2,3])

start_time

steps

stokes_drift

surface_only

time_step

timedir

vertical_mixing_timestep

wind_drift_depth

wind_drift_factor

z