Merge pull request #1702 from OceanParcels/tutorial_nemo3D_tracer_explanation

Adding explicit explanation how to add tracers in FieldSet.from_nemo()

Author: erikvansebille

docs/examples/tutorial_nemo_3D.ipynb

@@ -33,7 +33,9 @@
     "\n",
     "In the following, we will show how to create the `dimensions` dictionary for 3D NEMO simulations. What you require is a 'mesh_mask' file, which in our case is called `coordinates.nc` but in some other versions of NEMO has a different name. In any case, it will have to contain the variables `glamf`, `gphif` and `depthw`, which are the longitude, latitude and depth of the mesh nodes, respectively. Note that `depthw` is not part of the mesh_mask file, but is in the same file as the w data (`wfiles[0]`).\n",
     "\n",
-    "For the C-grid interpolation in Parcels to work properly, it is important that `U`, `V` and `W` are on the same grid.\n",
+    "For the C-grid interpolation in Parcels to work properly, it is important that `U`, `V` and `W` are on the same grid. \n",
+    "\n",
+    "All other tracers (e.g. `temperature`, `salinity`) should also be on this same grid. So even though these tracers are computed by NEMO on the T-points, Parcels expects them on the f-points (`glamf`, `gphif` and `depthw`). Parcels then under the hood makes sure the interpolation of these tracers is done correctly.\n",
     "\n",
     "The code below is an example of how to create a 3D simulation with particles, starting in the mouth of the river Rhine at 1m depth, and advecting them through the North Sea using the `AdvectionRK4_3D`\n"
    ]
@@ -71,15 +73,22 @@
     "ufiles = sorted(glob(f\"{example_dataset_folder}/ORCA*U.nc\"))\n",
     "vfiles = sorted(glob(f\"{example_dataset_folder}/ORCA*V.nc\"))\n",
     "wfiles = sorted(glob(f\"{example_dataset_folder}/ORCA*W.nc\"))\n",
+    "# tfiles = sorted(glob(f\"{example_dataset_folder}/ORCA*T.nc\"))  # Not used in this example\n",
     "mesh_mask = f\"{example_dataset_folder}/coordinates.nc\"\n",
     "\n",
     "filenames = {\n",
     "    \"U\": {\"lon\": mesh_mask, \"lat\": mesh_mask, \"depth\": wfiles[0], \"data\": ufiles},\n",
     "    \"V\": {\"lon\": mesh_mask, \"lat\": mesh_mask, \"depth\": wfiles[0], \"data\": vfiles},\n",
     "    \"W\": {\"lon\": mesh_mask, \"lat\": mesh_mask, \"depth\": wfiles[0], \"data\": wfiles},\n",
+    "    # \"T\": {\"lon\": mesh_mask, \"lat\": mesh_mask, \"depth\": wfiles[0], \"data\": tfiles},  # Not used in this example\n",
     "}\n",
     "\n",
-    "variables = {\"U\": \"uo\", \"V\": \"vo\", \"W\": \"wo\"}\n",
+    "variables = {\n",
+    "    \"U\": \"uo\",\n",
+    "    \"V\": \"vo\",\n",
+    "    \"W\": \"wo\",\n",
+    "    # \"T\": \"thetao\",  # Not used in this example\n",
+    "}\n",
     "\n",
     "# Note that all variables need the same dimensions in a C-Grid\n",
     "c_grid_dimensions = {\n",
@@ -92,6 +101,7 @@
     "    \"U\": c_grid_dimensions,\n",
     "    \"V\": c_grid_dimensions,\n",
     "    \"W\": c_grid_dimensions,\n",
+    "    # \"T\": c_grid_dimensions,  # Not used in this example\n",
     "}\n",
     "\n",
     "fieldset = parcels.FieldSet.from_nemo(filenames, variables, dimensions)\n",
@@ -161,7 +171,9 @@
    "source": [
     "## Adding other fields like cell edges\n",
     "\n",
-    "It is quite straightforward to add other gridded data, on the same curvilinear or any other type of grid, to the fieldset. Because it is good practice to make no changes to a `FieldSet` once a `ParticleSet` has been defined in it, we redefine the fieldset and add the fields with the cell edges from the coordinates file using `FieldSet.add_field()`.\n"
+    "It is quite straightforward to add other gridded data, on the same curvilinear or any other type of grid, to the fieldset. Because it is good practice to make no changes to a `FieldSet` once a `ParticleSet` has been defined in it, we redefine the fieldset and add the fields with the cell edges from the coordinates file using `FieldSet.add_field()`.\n",
+    "\n",
+    "Note that including tracers like `temperature` and `salinity` needs to be done at the f-points, so on the same grid as the velocity fields. See also the section above.\n"
    ]
   },
   {