Quick Start Guide¶
The simplest way to run particle-tracking-manager is to choose a built-in ocean model and select a location to initialize drifters, then use the built-in defaults for everything else (including start time which defaults to the first time step in the model output). You can do this interacting with the software as a Python library or using a command line interface.
Alternatively, you can run the package with new model output by inputting the necessary information into the Manager.
Details about what setup and configuration are available in Configuration and Setup Options.
Python Package¶
Run directly from the Lagrangian model you want to use, which will inherit from the manager class. For now there is one option of OpenDriftModel.
import particle_tracking_manager as ptm
m = ptm.OpenDriftModel(ocean_model="NWGOA", lon=-151, lat=59, steps=1)
# Can modify `m` between these steps, or look at `OpenDrift` config with `m.drift_model_config()`
m.run_all()
Then find results in file m.outfile_name.
Command Line Interface¶
The equivalent for the set up above for using the command line is:
ptm lon=-151 lat=59 ocean_model=NWGOA steps=1
To just initialize the simulation and print the OpenDrift configuration to screen without running the simulation, add the --dry-run flag:
ptm lon=-151 lat=59 ocean_model=NWGOA steps=1 --dry-run
m.outfile_name is printed to the screen after the command has been run. ptm is installed as an entry point with particle-tracking-manager.
Python package with local model output¶
This demo will run using easily-available ROMS model output from xroms.
import particle_tracking_manager as ptm
import xroms
import xarray as xr
m = ptm.OpenDriftModel(lon = -90, lat = 28.7, number=10, steps=20,
use_static_masks=True)
url = xroms.datasets.CLOVER.fetch("ROMS_example_full_grid.nc")
ds = xr.open_dataset(url, decode_times=False)
m.add_reader(ds=ds)
# m.run_all() or the following
m.seed()
m.run()
18:17:23 INFO opendrift.models.basemodel:529: OpenDriftSimulation initialised (version 1.11.2)
18:17:23 INFO opendrift:391: do3D is False so disabling vertical motion.
18:17:23 INFO opendrift.models.oceandrift:380: Setting config: drift:vertical_advection -> False
18:17:23 INFO opendrift.models.oceandrift:380: Setting config: drift:vertical_mixing -> False
18:17:23 INFO opendrift:372: Turning off vertical_mixing since do3D is False
18:17:23 INFO opendrift:428: vertical_mixing is False, so setting value of vertical_mixing_timestep to None.
Downloading file 'ROMS_example_full_grid.nc' from 'https://github.com/xoceanmodel/xroms/raw/main/xroms/data/ROMS_example_full_grid.nc' to '/home/docs/.cache/xroms'.
18:17:27 INFO opendrift:359: Since ocean_model is user-input, changing horizontal_diffusivity parameter from None to 0.0.
You can also set it to a specific value with `m.horizontal_diffusivity=[number]`.
18:17:27 INFO opendrift:439: ocean_model is not one of ['NWGOA', 'CIOFS', 'CIOFSOP'].
18:17:27 INFO opendrift:575: Using remote output for ocean_model user_input
18:17:27 INFO opendrift:584: Dropping vertical velocity (w) because do3D is False
18:17:27 INFO opendrift:603: Retaining wind variables because stokes_drift, wind_drift_factor, wind_uncertainty, or vertical_mixing are on or drift_model is 'OpenOil'
18:17:27 INFO opendrift:610: Dropping salt and temp variables because drift_model is not LarvalFish nor OpenOil
18:17:27 INFO opendrift:621: Dropping ice variables because drift_model is not OpenOil
18:17:27 INFO opendrift:634: Dropping wetdry masks because using static masks instead.
18:17:27 INFO opendrift:754: setting reader start_time as simulation start_time
18:17:27 INFO opendrift:769: Narrowed model output to simulation time
18:17:27 INFO opendrift.readers.reader_ROMS_native:249: 'gls_cmu0'
18:17:27 INFO opendrift.readers.reader_ROMS_native:250: Did not find complete set of GLS parameters
18:17:27 WARNING opendrift.readers.basereader.structured:50: No proj string or projection could be derived, using 'fakeproj'. This assumes that the variables are structured and gridded approximately equidistantly on the surface (i.e. in meters). This must be guaranteed by the user. You can get rid of this warning by supplying a valid projection to the reader.
18:17:27 INFO opendrift.readers.basereader.structured:90: Making interpolator for lon,lat to x,y conversion...
18:17:28 INFO opendrift.readers.basereader.structured:108: Saving interpolator for lon,lat to x,y conversion.
18:17:28 INFO opendrift.models.basemodel.environment:247: Fallback values will be used for the following variables which have no readers:
18:17:28 INFO opendrift.models.basemodel.environment:250: x_wind: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: y_wind: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: upward_sea_water_velocity: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: ocean_vertical_diffusivity: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_significant_height: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_stokes_drift_x_velocity: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_stokes_drift_y_velocity: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_period_at_variance_spectral_density_maximum: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_mean_period_from_variance_spectral_density_second_frequency_moment: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_swell_wave_to_direction: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_swell_wave_peak_period_from_variance_spectral_density: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_swell_wave_significant_height: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wind_wave_to_direction: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wind_wave_mean_period: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: sea_surface_wind_wave_significant_height: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: surface_downward_x_stress: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: surface_downward_y_stress: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: turbulent_kinetic_energy: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: turbulent_generic_length_scale: 0.000000
18:17:28 INFO opendrift.models.basemodel.environment:250: ocean_mixed_layer_thickness: 30.000000
18:17:28 INFO opendrift:492: start_time: 2009-11-19 12:00:00, end_time: 2009-11-19 13:40:00, steps: 20.0, duration: 0 days 01:40:00
18:17:28 INFO opendrift.models.basemodel:908: Using existing reader for land_binary_mask
18:17:28 INFO opendrift.readers.reader_ROMS_native:319: Using mask_rho for mask_rho
18:17:28 INFO opendrift.models.basemodel:920: All points are in ocean
18:17:28 WARNING opendrift.models.basemodel:701: Seafloor check not being run because sea_surface_height is missing. This will happen the first time the function is run but if it happens subsequently there is probably a problem.
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:00:00 - step 1 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.readers.reader_ROMS_native:340: Using mask_u for mask_u
18:17:28 INFO opendrift.readers.reader_ROMS_native:361: Using mask_v for mask_v
18:17:28 INFO opendrift.readers.reader_ROMS_native:384: Using angle from Dataset.
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:05:00 - step 2 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:10:00 - step 3 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:15:00 - step 4 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:20:00 - step 5 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:25:00 - step 6 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:30:00 - step 7 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:35:00 - step 8 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:40:00 - step 9 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:45:00 - step 10 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:50:00 - step 11 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 12:55:00 - step 12 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:00:00 - step 13 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:05:00 - step 14 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:10:00 - step 15 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:15:00 - step 16 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:20:00 - step 17 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:25:00 - step 18 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:30:00 - step 19 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.models.basemodel:2011: 2009-11-19 13:35:00 - step 20 of 20 - 10 active elements (0 deactivated)
18:17:28 INFO opendrift.export.io_netcdf:112: Wrote 2 steps to file None_initial
Plot using OpenDrift’s built in plotting. Many options are available, including animations (see OpenDrift docs for more information).
m.o.plot(fast=True)
18:17:29 WARNING opendrift.models.basemodel:2378: Plotting fast. This will make your plots less accurate.
(<GeoAxes: title={'center': 'OpenDrift - OceanDrift\n2009-11-19 12:00 to 2009-11-19 13:00 UTC (2 steps)'}>,
<Figure size 1100x610.583 with 1 Axes>)
Idealized simulation¶
To run an idealized scenario, no reader should be added but configuration parameters can be manually changed, for example:
import particle_tracking_manager as ptm
from datetime import datetime
m = ptm.OpenDriftModel(lon=4.0, lat=60.0, start_time=datetime(2015, 9, 22, 6),
use_auto_landmask=True, steps=20)
# idealized simulation, provide a fake current
m.o.set_config('environment:fallback:y_sea_water_velocity', 1)
# seed
m.seed()
# run simulation
m.run()
18:17:36 INFO opendrift.models.basemodel:529: OpenDriftSimulation initialised (version 1.11.2)
18:17:36 INFO opendrift:391: do3D is False so disabling vertical motion.
18:17:36 INFO opendrift.models.oceandrift:380: Setting config: drift:vertical_advection -> False
18:17:37 INFO opendrift.models.oceandrift:380: Setting config: drift:vertical_mixing -> False
18:17:37 INFO opendrift:372: Turning off vertical_mixing since do3D is False
18:17:37 INFO opendrift:428: vertical_mixing is False, so setting value of vertical_mixing_timestep to None.
18:17:37 INFO opendrift.models.basemodel.environment:220: Adding a dynamical landmask with max. priority based on assumed maximum speed of 5 m/s. Adding a customised landmask may be faster...
18:17:37 INFO opendrift.models.basemodel.environment:247: Fallback values will be used for the following variables which have no readers:
18:17:37 INFO opendrift.models.basemodel.environment:250: x_sea_water_velocity: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: y_sea_water_velocity: 1.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_height: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: x_wind: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: y_wind: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: upward_sea_water_velocity: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: ocean_vertical_diffusivity: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_significant_height: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_stokes_drift_x_velocity: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_stokes_drift_y_velocity: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_period_at_variance_spectral_density_maximum: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wave_mean_period_from_variance_spectral_density_second_frequency_moment: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_swell_wave_to_direction: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_swell_wave_peak_period_from_variance_spectral_density: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_swell_wave_significant_height: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wind_wave_to_direction: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wind_wave_mean_period: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_surface_wind_wave_significant_height: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: surface_downward_x_stress: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: surface_downward_y_stress: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: turbulent_kinetic_energy: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: turbulent_generic_length_scale: 0.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: ocean_mixed_layer_thickness: 30.000000
18:17:37 INFO opendrift.models.basemodel.environment:250: sea_floor_depth_below_sea_level: 10000.000000
18:17:37 INFO opendrift:492: start_time: 2015-09-22 06:00:00, end_time: 2015-09-22 07:40:00, steps: 20.0, duration: 0 days 01:40:00
18:17:37 INFO opendrift.models.basemodel:908: Using existing reader for land_binary_mask
18:17:37 INFO opendrift.models.basemodel:920: All points are in ocean
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:00:00 - step 1 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:05:00 - step 2 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:10:00 - step 3 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:15:00 - step 4 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:20:00 - step 5 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:25:00 - step 6 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:30:00 - step 7 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:35:00 - step 8 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:40:00 - step 9 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:45:00 - step 10 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:50:00 - step 11 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 06:55:00 - step 12 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:00:00 - step 13 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:05:00 - step 14 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:10:00 - step 15 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:15:00 - step 16 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:20:00 - step 17 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:25:00 - step 18 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:30:00 - step 19 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.models.basemodel:2011: 2015-09-22 07:35:00 - step 20 of 20 - 100 active elements (0 deactivated)
18:17:37 INFO opendrift.export.io_netcdf:112: Wrote 2 steps to file None_initial
m.o.plot(fast=True)
18:17:37 WARNING opendrift.models.basemodel:2378: Plotting fast. This will make your plots less accurate.
(<GeoAxes: title={'center': 'OpenDrift - OceanDrift\n2015-09-22 06:00 to 2015-09-22 07:00 UTC (2 steps)'}>,
<Figure size 983.698x1100 with 1 Axes>)
Ways to Get Information¶
Check drifter initialization properties:
m.initial_drifters
Look at reader/ocean model properties:
m.reader
Get reader/ocean model properties (gathered metadata about model):
m.reader_metadata(<key>)
Show configuration details — many more details on this in Configuration and Setup Options:
m.show_config()
Show OpenDrift configuration for selected drift_model:
m.drift_model_config()