tons of updates to and for docs

including errors I caught in the process of writing the tutorial as well as tests to demonstrate.

docs/configuration.md

@@ -160,9 +160,11 @@ m.show_config(key="ocean_model")
 The built-in ocean models are:
 * NWGOA (1999–2008) over the Northwest Gulf of Alaska (Danielson, S. L., K. S. Hedstrom, E. Curchitser,	2016. Cook Inlet Model Calculations, Final Report to Bureau of Ocean Energy Management,	M14AC00014,	OCS	Study BOEM 2015-050, University	of Alaska Fairbanks, Fairbanks,	AK,	149 pp.)
 * CIOFS (1999–2022) across Cook Inlet, Alaska, a hindcast version of NOAA's CIOFS model. (Thyng, K. M., C. Liu, M. Feen, E. L. Dobbins, 2023. Cook Inlet Circulation Modeling, Final Report to Oil Spill Recovery Institute, Axiom Data Science, Anchorage, AK.)
-* CIOFS_NOW (mid-2021 through 48 hours from present time) which is the nowcast/forecast version of the CIOFS model. (Shi, L., L. Lanerolle, Y. Chen, D. Cao, R. Patchen, A. Zhang,
+* CIOFSOP (mid-2021 through 48 hours from present time) which is the nowcast/forecast version of the CIOFS model. (Shi, L., L. Lanerolle, Y. Chen, D. Cao, R. Patchen, A. Zhang,
 and E. P. Myers, 2020. NOS Cook Inlet Operational Forecast System: Model development and hindcast skill assessment, NOAA Technical Report NOS CS 40, Silver Spring, Maryland, September 2020.)
 
+If you are running locally on an Axiom server you can use `ocean_model_local=True` to access the model output locally instead of remotely.
+
 An alternative ocean model can be used instead by initializing the `Manager` then setting up the reader manually, as shown in a {ref}`Quick Start<new_reader>` example:
 
 ```
@@ -239,6 +241,8 @@ To limit the variables saved in the export file, input a list of just the variab
 m = ptm.OpenDriftModel(export_variables=[])
 ```
 
+The default list of `export_variables` is set in `config_model` but is modified depending on the `drift_model` set.
+
 
 #### How to modify details for Stokes Drift
 

docs/environment.yml

@@ -8,6 +8,7 @@ dependencies:
    - adios_db
    - aiohttp
    - appdirs
+   - cmocean
    - numpy
    - xarray
    # These are needed for the docs themselves

docs/index.rst

@@ -23,6 +23,7 @@ To install from PyPI:
    :caption: Examples and demos
 
    quick_start
+   tutorial
    configuration
 
 

docs/quick_start.md

@@ -59,19 +59,28 @@ 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=1, steps=2)
+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")
-reader_kwargs = dict(loc=url, kwargs_xarray={})
-m.add_reader(**reader_kwargs)
+ds = xr.open_dataset(url, decode_times=False)
+m.add_reader(ds=ds)
 
 # m.run_all() or the following
 m.seed()
 m.run()
 ```
 
+Plot using `OpenDrift`'s built in plotting. Many options are available, including animations (see [OpenDrift docs for more information](https://opendrift.github.io/)).
+
+```{code-cell} ipython3
+m.o.plot(fast=True)
+```
+
 ## Idealized simulation
 
 To run an idealized scenario, no reader should be added but configuration parameters can be manually changed, for example:
@@ -80,7 +89,7 @@ To run an idealized scenario, no reader should be added but configuration parame
 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,)
+                       use_auto_landmask=True, steps=20)
 
 # idealized simulation, provide a fake current
 m.o.set_config('environment:fallback:y_sea_water_velocity', 1)
@@ -92,6 +101,10 @@ m.seed()
 m.run()
 ```
 
+```{code-cell} ipython3
+m.o.plot(fast=True)
+```
+
 ## Ways to Get Information
 
 Check drifter initialization properties:

docs/tutorial.md

@@ -0,0 +1,278 @@
+---
+jupytext:
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.16.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# Tutorial
+
+Particle Tracking Manager (PTM) is a wrapper around particle tracking codes to easily run particle simulations in select (or user-input) ocean models. Currently, `OpenDrift` is included. In this tutorial we demonstrate using the four wrapped drift models from `OpenDrift` along with some high level configuration changes.
+
+```{code-cell} ipython3
+import xarray as xr
+import particle_tracking_manager as ptm
+import xroms
+import cmocean.cm as cmo
+```
+
+## Ocean Models
+
+Three ocean models are built into PTM and can be accessed by name `ocean_model=` "NWGOA", "CIOFS", and "CIOFSOP", and either accessed remotely or locally if run on an internal server (at Axiom) (with `ocean_model_local=True`). Alternatively, a user can input their own xarray Dataset, which we will do for this tutorial. When you input your own Dataset, you have to add the reader by hand as opposed to being able to input the `ocean_model` name in the initial call.
+
+```{code-cell} ipython3
+url = xroms.datasets.CLOVER.fetch("ROMS_example_full_grid.nc")
+ds = xr.open_dataset(url, decode_times=False)
+```
+
+## Drift Models
+
+After a drift simulation is run, results can be found in file with name `m.outfile_name`.
+
+### OceanDrift (Physics)
+
+This model can in 2D or 3D with or without horizontal or vertical mixing, wind drift, Stokes drift, etc. By default this would be run at the surface in 2D but we can input selections to run in 3D starting at depth.
+
+#### Initialize manager `m`
+
+```{code-cell} ipython3
+m = ptm.OpenDriftModel(lon=-90, lat=28.7, number=10, steps=40,
+                       z=-5, do3D=True, horizontal_diffusivity=100,)
+```
+
+The drift_model-specific parameters chosen by the user and PTM for this simulation are:
+
+```{code-cell} ipython3
+m.drift_model_config()
+```
+
+You can also find the full PTM and `OpenDrift` configuration information with:
+
+```{code-cell} ipython3
+---
+editable: true
+slideshow:
+  slide_type: ''
+---
+m.show_config()
+```
+
+#### Add reader and run
+
+```{code-cell} ipython3
+m.add_reader(ds=ds)
+m.run_all()
+```
+
+#### Plot
+
+```{code-cell} ipython3
+m.o.plot(linecolor="z", fast=True, cmap=cmo.deep)
+```
+
+### Leeway (Search and Rescue)
+
+These are simulations of objects that stay at the surface and are transported by both the wind and ocean currents at rates that depend on how much the object sticks up out of and down into the water. The constants to use for those rates have been experimentally determined by the coastguard and are used in this model.
+
+#### Initialize manager `m`
+
+```{code-cell} ipython3
+m = ptm.OpenDriftModel(drift_model="Leeway", lon = -89.8, lat = 29.08,
+                       number=10, steps=40,
+                       object_type="Fishing vessel, general (mean values)")
+
+# This drift model requires wind data to be set which isn't present in model output
+m.o.set_config('environment:constant:x_wind', -1)
+m.o.set_config('environment:constant:y_wind', 1)
+```
+
+The objects that can be modeled are:
+
+```{code-cell} ipython3
+m.show_config(key="seed:object_type")["enum"]
+```
+
+The drift_model-specific parameters chosen by the user and PTM for this simulation are:
+
+```{code-cell} ipython3
+m.drift_model_config()
+```
+
+#### Add reader and run
+
+```{code-cell} ipython3
+m.add_reader(ds=ds)
+m.run_all()
+```
+
+#### Plot
+
+```{code-cell} ipython3
+m.o.plot(fast=True)
+```
+
+### LarvalFish
+
+This model simulates eggs and larvae that move in 3D with the currents and some basic behavior and vertical movement. It also simulates some basic growth of the larvae.
+
+There are specific seeding options for this model:
+* 'diameter'
+* 'neutral_buoyancy_salinity'
+* 'stage_fraction'
+* 'hatched'
+* 'length'
+* 'weight'
+
+#### Eggs
+
+An optional general flag is to initialize the drifters at the seabed, which might make sense for eggs and is demonstrated here.
+
+##### Initialize manager `m`
+
+```{code-cell} ipython3
+m = ptm.OpenDriftModel(drift_model="LarvalFish", lon=-89.85, lat=28.8, number=10, steps=45,
+                       do3D=True, seed_seafloor=True)
+```
+
+The drift_model-specific parameters chosen by the user and PTM for this simulation are:
+
+```{code-cell} ipython3
+m.drift_model_config()
+```
+
+##### Add reader and run
+
+```{code-cell} ipython3
+m.add_reader(ds=ds)
+m.run_all()
+```
+
+##### Plot
+
+```{code-cell} ipython3
+m.o.plot(linecolor="z", fast=True, cmap=cmo.deep_r)
+```
+
+```{code-cell} ipython3
+m.o.plot_property('length')
+m.o.plot_property('weight')
+m.o.plot_property('diameter')
+m.o.plot_property('stage_fraction')
+```
+
+Output from the simulation can be viewed in the history or elements, or from the output file.
+
+```{code-cell} ipython3
+m.outfile_name
+```
+
+```{code-cell} ipython3
+m.o.history["z"].data
+```
+
+```{code-cell} ipython3
+m.o.elements
+```
+
+#### Hatched!
+
+##### Initialize manager `m`
+
+```{code-cell} ipython3
+m = ptm.OpenDriftModel(drift_model="LarvalFish", lon=-89.85, lat=28.8, number=10, steps=45,
+                       do3D=True, seed_seafloor=True, hatched=1)
+```
+
+The drift_model-specific parameters chosen by the user and PTM for this simulation are:
+
+```{code-cell} ipython3
+m.drift_model_config()
+```
+
+##### Add reader and run
+
+```{code-cell} ipython3
+m.add_reader(ds=ds)
+m.run_all()
+```
+
+##### Plot
+
+```{code-cell} ipython3
+m.o.plot(linecolor="z", fast=True, cmap=cmo.deep_r)
+```
+
+```{code-cell} ipython3
+m.o.plot_property('length')
+m.o.plot_property('weight')
+m.o.plot_property('diameter')
+m.o.plot_property('stage_fraction')
+```
+
+### OpenOil
+
+This model simulates the transport of oil. Processes optionally modeled (which are included in PTM by default) include:
+* "emulsification"
+* "dispersion"
+* "evaporation"
+* "update_oilfilm_thickness"
+* "biodegradation"
+
+There are also specific seeding options for this model:
+* "m3_per_hour"
+* "oil_film_thickness"
+* "droplet_size_distribution"
+* "droplet_diameter_mu"
+* "droplet_diameter_sigma"
+* "droplet_diameter_min_subsea"
+* "droplet_diameter_max_subsea"
+
+#### Initialize manager `m`
+
+```{code-cell} ipython3
+m = ptm.OpenDriftModel(drift_model="OpenOil", lon=-89.85, lat=28.08, number=10, steps=45,
+                       z=-10, do3D=True, oil_type='GENERIC BUNKER C')
+m.o.set_config('environment:constant:x_wind', -1)
+m.o.set_config('environment:constant:y_wind', 1)
+```
+
+List available oil types from NOAA's ADIOS database:
+
+```{code-cell} ipython3
+m.show_config(key="seed:oil_type")
+```
+
+The drift_model-specific parameters chosen by the user and PTM for this simulation are:
+
+```{code-cell} ipython3
+m.drift_model_config()
+```
+
+#### Add reader and run
+
+```{code-cell} ipython3
+m.add_reader(ds=ds)
+m.run_all()
+```
+
+#### Plot
+
+```{code-cell} ipython3
+m.o.plot(linecolor="z", fast=True, cmap=cmo.deep_r)
+```
+
+Plot the oil budget.
+
+```{code-cell} ipython3
+m.o.plot_oil_budget(show_wind_and_current=False)
+```
+
+```{code-cell} ipython3
+
+```

environment.yml

@@ -11,6 +11,7 @@ dependencies:
   - fastparquet
   - jupyter
   - jupyterlab
+  - kerchunk
   - xarray
   - numpy
   - opendrift