Merge branch 'v4-dev' into fieldset_from_nemo-nick

Author: VeckoTheGecko

.gitignore

@@ -3,6 +3,7 @@ docs/_build/*
 docs/_downloads
 docs/jupyter_execute/*
 docs/.jupyter_cache/*
+docs/reference
 output
 
 *.log

docs/_autoapi_templates/python/class.rst

@@ -116,7 +116,6 @@
 # directories to ignore when looking for source files.
 exclude_patterns = [
     "_build",
-    "_autoapi_templates",
     "jupyter_execute",
     "**.ipynb_checkpoints",
     "user_guide/examples_v3",
@@ -544,5 +543,4 @@ def linkcode_resolve(domain, info):
 ]
 autoapi_member_order = "bysource"
 autodoc_typehints = "none"
-autoapi_template_dir = "_autoapi_templates"
 autoapi_own_page_level = "class"

docs/_autoapi_templates/python/module.rst

@@ -9,7 +9,3 @@ Getting started with parcels is easy; here you will find:
 🎓 Output tutorial <tutorial_output.ipynb>
 📖 Conceptual workflow <explanation_concepts.md>
 ```
-
-```{note}
-TODO: Add links to Reference API in quickstart tutorial and concepts explanation
-```

docs/conf.py

@@ -41,8 +41,8 @@ ds_fields
 As we can see, the reanalysis dataset contains eastward velocity `uo`, northward velocity `vo`, potential temperature
 (`thetao`) and salinity (`so`) fields.
 
-These hydrodynamic fields need to be stored in a `parcels.FieldSet` object. Parcels provides tooling to parse many types
-of models or observations into such a `parcels.FieldSet` object. Here, we use `FieldSet.from_copernicusmarine()`, which
+These hydrodynamic fields need to be stored in a {py:obj}`parcels.FieldSet` object. Parcels provides tooling to parse many types
+of models or observations into such a `parcels.FieldSet` object. Here, we use {py:func}`parcels.FieldSet.from_copernicusmarine()`, which
 recognizes the standard names of a velocity field:
 
 ```{code-cell}
@@ -61,10 +61,10 @@ velocity = ds_fields.isel(time=0, depth=0).plot.quiver(x="longitude", y="latitud
 Now that we have created a `parcels.FieldSet` object from the hydrodynamic data, we need to provide our second input:
 the virtual particles for which we will calculate the trajectories.
 
-We need to create a `parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet`
+We need to create a {py:obj}`parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet`
 object also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of
-`parcels.Particle` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add
-other `Variables` such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb).
+{py:obj}`parcels.ParticleClass` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add
+other {py:obj}`parcels.Variable`s such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb).
 
 ```{code-cell}
 # Particle locations and initial time
@@ -90,13 +90,9 @@ ax.scatter(lon,lat,s=40,c='w',edgecolors='r');
 ## Compute: `Kernel`
 
 After setting up the input data and particle start locations and times, we need to specify what calculations to do with
-the particles. These calculations, or numerical integrations, will be performed by what we call a `Kernel`, operating on
+the particles. These calculations, or numerical integrations, will be performed by what we call a {py:obj}`parcels.Kernel`, operating on
 all particles in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field.
-Parcels comes with a number of standard kernels, from which we will use the Runge-Kutta advection kernel `AdvectionRK2`:
-
-```{note}
-TODO: link to a list of included kernels
-```
+Parcels comes with a number of common {py:obj}`parcels.kernels`, from which we will use the Runge-Kutta advection kernel {py:obj}`parcels.kernels.AdvectionRK2`:
 
 ```{code-cell}
 kernels = [parcels.kernels.AdvectionRK2]
@@ -105,7 +101,7 @@ kernels = [parcels.kernels.AdvectionRK2]
 ## Prepare output: `ParticleFile`
 
 Before starting the simulation, we must define where and how frequent we want to write the output of our simulation.
-We can define this in a `ParticleFile` object:
+We can define this in a {py:obj}`parcels.ParticleFile` object:
 
 ```{code-cell}
 output_file = parcels.ParticleFile("output-quickstart.zarr", outputdt=np.timedelta64(1, "h"))
@@ -117,18 +113,14 @@ the `outputdt` argument so that it captures the smallest timescales of our inter
 
 ## Run Simulation: `ParticleSet.execute()`
 
-Finally, we can run the simulation by _executing_ the `ParticleSet` using the specified list of `kernels`.
+Finally, we can run the simulation by _executing_ the `ParticleSet` using the specified list of `kernels`. This is done using the {py:meth}`parcels.ParticleSet.execute()` method.
 Additionally, we need to specify:
 
 - the `runtime`: for how long we want to simulate particles.
 - the `dt`: the timestep with which to perform the numerical integration in the `kernels`. Depending on the numerical
   integration scheme, the accuracy of our simulation will depend on `dt`. Read [this notebook](https://github.com/Parcels-code/10year-anniversary-session2/blob/8931ef69577dbf00273a5ab4b7cf522667e146c5/advection_and_windage.ipynb)
   to learn more about numerical accuracy.
 
-```{note}
-TODO: add Michaels 10-years Parcels notebook to the user guide
-```
-
 ```{code-cell}
 :tags: [hide-output]
 pset.execute(

docs/getting_started/index.md

@@ -43,6 +43,7 @@ Besides having commutable Kernels, the main advantage of this implementation is
 Below is a simple example of some particles at the surface of the ocean. We create an idealised zonal wind flow that will "push" a particle that is already affected by the surface currents. The Kernel loop ensures that these two forces act at the same time and location.
 
 ```{code-cell}
+:tags: [hide-output]
 import matplotlib.pyplot as plt
 import numpy as np
 import xarray as xr
@@ -69,21 +70,18 @@ ds_fields["VWind"] = xr.DataArray(
 
 fieldset = parcels.FieldSet.from_copernicusmarine(ds_fields)
 
-# Set unit converters for custom wind fields
-fieldset.UWind.units = parcels.GeographicPolar()
-fieldset.VWind.units = parcels.Geographic()
+# Create a vecorfield for the wind
+windvector = parcels.VectorField("Wind", fieldset.UWind, fieldset.VWind)
+fieldset.add_field(windvector)
 ```
 
 Now we define a wind kernel that uses a forward Euler method to apply the wind forcing. Note that we update the `particles.dlon` and `particles.dlat` variables, rather than `particles.lon` and `particles.lat` directly.
 
 ```{code-cell}
 def wind_kernel(particles, fieldset):
-    particles.dlon += (
-        fieldset.UWind[particles] * particles.dt
-    )
-    particles.dlat += (
-        fieldset.VWind[particles] * particles.dt
-    )
+    uwind, vwind = fieldset.Wind[particles]
+    particles.dlon += uwind * particles.dt
+    particles.dlat += vwind * particles.dt
 ```
 
 First run a simulation where we apply kernels as `[AdvectionRK4, wind_kernel]`