particle_tracking_manager.the_manager

Contains logic for configuring particle tracking simulations.

Classes

ParticleTrackingManager(model[, lon, lat, ...])

Manager class that controls particle tracking model.

class particle_tracking_manager.the_manager.ParticleTrackingManager(model, lon=None, lat=None, geojson=None, seed_flag='elements', z=0, seed_seafloor=False, number=100, start_time=None, run_forward=True, time_step=300, time_step_output=3600, steps=None, duration=None, end_time=None, ocean_model=None, ocean_model_local=False, surface_only=None, do3D=False, vertical_mixing=True, use_static_masks=True, output_file=None, **kw)

Bases: object

Manager class that controls particle tracking model.

Parameters:

• model (str) – Name of Lagrangian model package to use for drifter tracking. Only option currently is “opendrift”.

• lon (Optional[Union[int,float]], optional) – Longitude of center of initial drifter locations, by default None. Use with seed_flag=”elements”.

• lat (Optional[Union[int,float]], optional) – Latitude of center of initial drifter locations, by default None. Use with seed_flag=”elements”.

• geojson (Optional[dict], optional) – GeoJSON object defining polygon for seeding drifters, by default None. Use with seed_flag=”geojson”.

• seed_flag (str, optional) – Flag for seeding drifters. Options are “elements”, “geojson”. Default is “elements”.

• z (Union[int,float], optional) – Depth of initial drifter locations, by default 0 but taken from the default in the model. Values are overridden if surface_only==True to 0 and to the seabed if seed_seafloor is True.

• seed_seafloor (bool, optional) – Set to True to seed drifters vertically at the seabed, default is False. If True then value of z is set to None and ignored.

• number (int) – Number of drifters to simulate. Default is 100.

• start_time (Optional[str,datetime.datetime,pd.Timestamp], optional) – Start time of simulation, by default None

• run_forward (bool, optional) – True to run forward in time, False to run backward, by default True

• time_step (int, optional) – Time step in seconds, options >0, <86400 (1 day in seconds), by default 300.

• time_step_output (int, Timedelta, optional) – How often to output model output. Should be a multiple of time_step. By default 3600.

• steps (int, optional) – Number of time steps to run in simulation. Options >0. steps, end_time, or duration must be input by user. By default steps is 3 and duration and end_time are None. Only one of steps, end_time, or duration can be non-None at initialization time. If one of steps, end_time, or duration is input later, it will be used to overwrite the three parameters according to that newest parameter.

• duration (Optional[datetime.timedelta], optional) – Length of simulation to run, as positive-valued timedelta object, in hours, such as timedelta(hours=48). steps, end_time, or duration must be input by user. By default steps is 3 and duration and end_time are None. For CLI, input duration as a pandas Timedelta string like “48h” for 48 hours. Only one of steps, end_time, or duration can be non-None at initialization time. If one of steps, end_time, or duration is input later, it will be used to overwrite the three parameters according to that newest parameter.

• end_time (Optional[datetime], optional) – Datetime at which to end simulation, as positive-valued datetime object. steps, end_time, or duration must be input by user. By default steps is 3 and duration and end_time are None. Only one of steps, end_time, or duration can be non-None at initialization time. If one of steps, end_time, or duration is input later, it will be used to overwrite the three parameters according to that newest parameter.

• ocean_model (Optional[str], optional) – Name of ocean model to use for driving drifter simulation, by default None. Use None for testing and set up. Otherwise input a string. Options are: “NWGOA”, “CIOFS”, “CIOFSOP”. Alternatively keep as None and set up a separate reader (see example in docs).

• ocean_model_local (Optional, bool) – Set to True to use local version of known ocean_model instead of remote version.

• surface_only (bool, optional) – Set to True to keep drifters at the surface, by default None. If this flag is set to not-None, it overrides do3D to False, vertical_mixing to False, and the z value(s) 0. If True, this flag also turns off reading model output below 0.5m if drift_model is not Leeway: o.set_config('drift:truncate_ocean_model_below_m', 0.5) to save time.

• do3D (bool, optional) – Set to True to run drifters in 3D, by default False. This is overridden if surface_only==True. If True, vertical advection and mixing are turned on with options for setting diffusivitymodel, background_diffusivity, ocean_mixed_layer_thickness, vertical_mixing_timestep. If False, vertical motion is disabled.

• vertical_mixing (bool, optional) – Set to True to include vertical mixing, by default False. This is overridden if surface_only==True.

• use_static_masks (bool, optional) – Set to True to use static masks ocean_model output when ROMS wetdry masks are available, by default False. This is relevant for all of the available known models. If you want to use static masks with a user-input ocean_model, you can drop the wetdry_mask_rho etc variables from the dataset before inputting to PTM. Setting this to True may save computation time but will be less accurate, especially in the tidal flat regions of the model.

• output_file (Optional[str], optional) – Name of output file to save, by default None. If None, default is set in the model.

Notes

Configuration happens at initialization time for the child model. There is currently no separate configuration step.

Attributes:

outfile_name

Output file name.

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_steps()	Calculate steps based on duration and time_step.
export_variables()	Output list of all actual export variables.
output()	Hold for future output function.
query_reader()	define in child class.
reader_metadata(key)	define in child class
run()	Call model run function.
run_all()	Run all steps.
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()	define in child class

_add_model_config()

Have this in the model class to modify config

_add_ptm_config()

Have this in the model class to modify config

_config()

Model should have its own version which returns variable config

_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.

define in child class.

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_steps()

Calculate steps based on duration and time_step.

config_model

config_ptm

duration

end_time

export_variables()

Output list of all actual export variables.

define in child class.

lat

logger

lon

ocean_model

property outfile_name

Output file name.

define in child class.

output()

Hold for future output function.

query_reader()

define in child class.

reader_metadata(key)

define in child class

run()

Call model run function.

run_all()

Run all steps.

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

Initialize the drifters in space and time

… and with any special properties.

seed_seafloor

show_config(**kwargs)

Show parameter configuration across both model and PTM.

show_config_model()

define in child class

start_time

steps

surface_only

time_step

timedir

z