update explanation

Author: reint-fischer

docs/getting_started/explanation_concepts.md

@@ -8,14 +8,14 @@ kernelspec:
 Parcels is a set of Python classes and methods to create particle tracking simulations. Here, we will explain the basic concepts defined by the most important classes and functions. This overview can be useful to start understanding the names for different components we use in Parcels, and to structure and make appropriate use of the code in a simulation script.
 
 A Parcels simulation is generally built up from four different components:
-1. [**FieldSet**](#1.-FieldSet). The input dataset of gridded fields (e.g. ocean current velocity, temperature) in which virtual particles are defined.
-2. [**ParticleSet**](#2.-ParticleSet). The dataset of virtual particles. These always contain time, z, lat, and lon, for which initial values must be defined, and may contain other variables.
-3. [**Kernels**](#3.-Kernels). Kernels perform some specific operation on the particles every time step (e.g. interpolate the temperature from the temperature field to the particle location).
-4. [**Execute**](#4.-Execution). Execute the simulation. The core method which integrates the operations defined in Kernels for a given time and timestep, and writes output to a ParticleFile.
+1. [**FieldSet**](#1-fieldset). The input dataset of gridded fields (e.g. ocean current velocity, temperature) in which virtual particles are defined.
+2. [**ParticleSet**](#2-particleset). The dataset of virtual particles. These always contain time, z, lat, and lon, for which initial values must be defined, and may contain other variables.
+3. [**Kernels**](#3-kernels). Kernels perform some specific operation on the particles every time step (e.g. interpolate the temperature from the temperature field to the particle location).
+4. [**Execute**](#4-execution). Execute the simulation. The core method which integrates the operations defined in Kernels for a given time and timestep, and writes output to a ParticleFile.
 
 We discuss each component in more detail below and link to more detailed [how-to guides](../user_guide/index.md) and the full list of classes and methods in the [API reference](../reference.md). If you want to learn by doing, check out the [quickstart tutorial](./tutorial_quickstart.md) to start creating your first Parcels simulation. 
 
-![png](images/parcels_user_diagram.png)
+![png](../user_guide/explanations/images/parcels_user_diagram.png)
 
 ## 1. FieldSet
 

docs/getting_started/index.md

@@ -6,8 +6,8 @@ Getting started with parcels is easy; here you will find:
 :maxdepth: 1
 Installation guide <installation.md>
 Quickstart tutorial <tutorial_quickstart.md>
-Parcels concepts explainer <concepts_overview.md>
 Simple output tutorial <tutorial_output.ipynb>
+Parcels concepts explanation <explanation_concepts.md>
 
 ```
 

docs/user_guide/examples_v3/tutorial_parcels_structure.ipynb

@@ -23,10 +23,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "1. [**FieldSet**](#1.-FieldSet). Load and set up the fields. These can be velocity fields that are used to advect the particles, but it can also be e.g. temperature.\n",
-    "2. [**ParticleSet**](#2.-ParticleSet). Define the type of particles. Also additional `Variables` can be added to the particles (e.g. temperature, to keep track of the temperature that particles experience).\n",
-    "3. [**Kernels**](#3.-Kernels). Kernels perform some specific operation on the particles every time step (e.g. interpolate the temperature from the temperature field to the particle location).\n",
-    "4. [**Execution and output**](#4.-Execution-and-Output). Execute the simulation and write and store the output in a Zarr file.\n",
+    "\n",
     "5. [**Optimising and parallelising**](#5.-Optimising-and-parallelising). Optimise and parallelise the code to run faster.\n",
     "\n",
     "We discuss each component in more detail below.\n",
@@ -47,7 +44,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Parcels provides a framework to simulate the movement of particles **within an existing flow field environment**. To start a parcels simulation we must define this environment with the `FieldSet` class. The minimal requirements for this Fieldset are that it must contain the `'U'` and `'V'` fields: the 2D hydrodynamic data that will move the particles in a horizontal direction. Additionally, it can contain e.g. a temperature or vertical flow field.\n"
+    "Parcels provides a framework to simulate the movement of particles **within an existing flow field environment**. To start a parcels simulation we must define this environment with the `FieldSet` class. The minimal requirements for this Fieldset are that it must contain the `'U'` and `'V'` fields: the 2D hydrodynamic data that will move the particles in a horizontal direction. Additionally, it can contain e.g. a temperature or vertical flow field."
    ]
   },
   {

docs/user_guide/explanations/explanation_grids.md

@@ -0,0 +1,10 @@
+# Grids
+
+Parcels `Field` objects exist on a (structured) `parcels.XGrid` or (unstructured) `parcels.UXgrid`. Here we describe these grids on a conceptual level.
+
+```{note}
+The contents for this page are still under development in v4.
+TODO
+- link to xgcm.Grid documentation
+- adapt from v3 grid indexing tutorial (../examples_v3/documentation_indexing.ipynb)
+```

docs/user_guide/explanations/explanation_interpolation.md

@@ -1,4 +1,4 @@
-# Interpolator explanation
+# Interpolators
 
 Interpolation is an important functionality of Parcels. On this page we will discuss the way it is
 implemented in **Parcels** and how to write a custom interpolator function.

docs/user_guide/how-to-guides/images/parcels_user_diagram.png

@@ -11,7 +11,7 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4.
 
 - [Quickstart Tutorial](../getting_started/tutorial_quickstart.md)
 - [Output Tutorial](../getting_started/tutorial_output.ipynb)
-- [Concepts Overview](../getting_started/concepts_overview.md)
+- [Concepts Explanation](../getting_started/explanation_concepts.md)
 
 ## How to
 
@@ -22,67 +22,65 @@ The tutorials written for Parcels v3 are currently being updated for Parcels v4.
 ```{toctree}
 :caption: Set up FieldSets
 :titlesonly:
-
-examples/tutorial_nemo_curvilinear.ipynb
-examples/tutorial_unitconverters.ipynb
+how-to-guides/tutorial_nemo_curvilinear.ipynb
+how-to-guides/tutorial_unitconverters.ipynb
+explanations/explanation_grids.md
 ```
 
-<!-- examples/documentation_indexing.ipynb -->
-<!-- examples/tutorial_nemo_3D.ipynb -->
-<!-- examples/tutorial_croco_3D.ipynb -->
-<!-- examples/tutorial_timevaryingdepthdimensions.ipynb -->
-<!-- examples/tutorial_periodic_boundaries.ipynb -->
-<!-- examples/tutorial_interpolation.ipynb -->
+<!-- how-to-guides/documentation_indexing.ipynb -->
+<!-- how-to-guides/tutorial_nemo_3D.ipynb -->
+<!-- how-to-guides/tutorial_croco_3D.ipynb -->
+<!-- how-to-guides/tutorial_timevaryingdepthdimensions.ipynb -->
 
 ```{toctree}
 :caption: Create ParticleSets
 :titlesonly:
-examples/tutorial_delaystart.ipynb
+how-to-guides/tutorial_delaystart.ipynb
 ```
 
 ```{toctree}
 :caption: Write Kernels
 :titlesonly:
 
-examples/explanation_kernelloop.md
-examples/tutorial_sampling.ipynb
-examples/tutorial_statuscodes.ipynb
-examples/tutorial_gsw_density.ipynb
-examples/tutorial_Argofloats.ipynb
+explanations/explanation_kernelloop.md
+how-to-guides/tutorial_sampling.ipynb
+how-to-guides/tutorial_statuscodes.ipynb
+how-to-guides/tutorial_gsw_density.ipynb
+how-to-guides/tutorial_Argofloats.ipynb
 ```
 
 ```{toctree}
 :caption: Set interpolation method
 :titlesonly:
 
-examples/explanation_interpolation.md
-examples/tutorial_interpolation.ipynb
+explanations/explanation_interpolation.md
+how-to-guides/tutorial_interpolation.ipynb
 ```
 
-<!-- examples/tutorial_diffusion.ipynb -->
-<!-- examples/tutorial_particle_field_interaction.ipynb -->
-<!-- examples/tutorial_interaction.ipynb -->
-<!-- examples/tutorial_analyticaladvection.ipynb -->
-<!-- examples/tutorial_kernelloop.ipynb -->
+<!-- how-to-guides/tutorial_diffusion.ipynb -->
+<!-- how-to-guides/tutorial_particle_field_interaction.ipynb -->
+<!-- how-to-guides/tutorial_interaction.ipynb -->
+<!-- how-to-guides/tutorial_analyticaladvection.ipynb -->
+<!-- how-to-guides/tutorial_kernelloop.ipynb -->
 
 ```{toctree}
 :caption: Other tutorials
 :name: tutorial-other
 
 ```
 
-<!-- examples/tutorial_peninsula_AvsCgrid.ipynb -->
-<!-- examples/documentation_stuck_particles.ipynb -->
-<!-- examples/documentation_unstuck_Agrid.ipynb -->
-<!-- examples/documentation_LargeRunsOutput.ipynb -->
-<!-- examples/documentation_geospatial.ipynb -->
-<!-- examples/documentation_advanced_zarr.ipynb -->
+<!-- how-to-guides/tutorial_peninsula_AvsCgrid.ipynb -->
+<!-- how-to-guides/documentation_stuck_particles.ipynb -->
+<!-- how-to-guides/documentation_unstuck_Agrid.ipynb -->
+<!-- how-to-guides/documentation_LargeRunsOutput.ipynb -->
+<!-- how-to-guides/documentation_geospatial.ipynb -->
+<!-- how-to-guides/documentation_advanced_zarr.ipynb -->
 
 ```{toctree}
 :caption: Worked examples
 ```
 
-<!-- examples/documentation_homepage_animation.ipynb -->
+<!-- how-to-guides/documentation_homepage_animation.ipynb -->
 
 ```{toctree}
 :hidden: