Grid explanations user guide by michaeldenes · Pull Request #2779 · Parcels-code/Parcels

michaeldenes · 2026-07-29T13:57:03Z

Description

This PR includes a grid explanations user guide, to help users understand how their underlying model data is defined and interpreted.

Checklist

Contributes to Updating parcels website and documentation for v4 preview release #2702
Tests added
This PR targets the correct branch (main for normal development, v3-support for v3 support)

AI Disclosure

This PR contains AI-generated content.
- I have tested any AI-generated content in my PR.
- I take responsibility for any AI-generated content in my PR.
- Describe how you used it (e.g., by pasting your prompt):

for more information, see https://pre-commit.ci

erikvansebille

Thanks @michaeldenes. See below for some suggestions/questions and comments

erikvansebille · 2026-07-30T06:37:21Z

+
+## Structured grids
+
+A structured grid is composed of quadrilateral elements, that are indexed using logical 2D or 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to `dimensions`, for example [...]. In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions.


The [...] here needs to be replaced by something? What did you have in mind?

erikvansebille · 2026-07-30T06:45:10Z

+
+## Structured grids
+
+A structured grid is composed of quadrilateral elements, that are indexed using logical 2D or 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to `dimensions`, for example [...]. In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions.


The sentence "In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions" is true, but not relevant for Parcels v4. We don't search for neighbours anymore. Instead:

In grids with 1-dimensional coordinates (= rectilinear grids), we do a quick search of the coordinate to find the right value:

Parcels/src/parcels/_core/index_search.py

Lines 47 to 51 in e19411f

index = np.clip(np.searchsorted(arr, x, side="right") - 1, 0, len(arr) - 2)

# Use broadcasting to avoid repeated array access

arr_index = arr[index]

arr_next = arr[np.clip(index + 1, 1, len(arr) - 1)] # Ensure we don't go out of bounds

bcoord = (x - arr_index) / (arr_next - arr_index)

In grids with 2-dimensional coordinates (= curvilinear grids; but could also be rectilinear), we use the hash-table approach that Joe documented extensively in https://docs.oceanparcels.org/en/main/development/unstructured_grid_search.html. Note that there is no fundamental difference between how we treat unstructured grids and structured grids with 2D coordinates. The only implementation difference is the point-in-cell check

Before going into the hash-table query, I think(?) that we first check if the particle is stil in the old cell (through its element index ei). But whether this works is to be explored (see Grid search (ei/igrid) not caching between successive grid search calls #2693 and Check that there are unit tests that check for correct particles._ei setting and updating #2669)

So I would rephrase this sentence to better highlight that we don't use neighbour search

erikvansebille · 2026-07-30T06:46:23Z

+
+A structured grid is composed of quadrilateral elements, that are indexed using logical 2D or 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to `dimensions`, for example [...]. In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions.
+
+There are two styles of structured grids, rectilinear and curvilinear, as shown in Figure 1. Rectilinear grids are nearly always aligned with the coordinate axes (that is, there is a one-to-one mapping between the dimensions and the physical coordinate space), making them simple and computationally efficient to query. However, they're limited by the fact that it is difficult to resolve complex coastlines without high resolution, and they suffer from singularities in the flow fields at the poles where the grid lines converge. Curvilinear grids allow for curved grid lines, which allow for better representation of coastlines. They often move the poles onto land to avoid singularities occuring in the ocean. However, they become trickier to work with, as the spatial positions of their vertices are stored in separate 2D arrays, and moving to an eastward neighbour is not as simple as incrementing the $i$-th coordinate by 1.


Why 'nearly' always? In Parcels, I think they have to be always. The index_search works with either 1D coordinates or 2D coordinates

I think I've seen models with a rotated rectilinear grid (say, along the coast of the Netherlands), which is not aligned East/North, hence the careful choice of wording. Happy to change to "typically" rather than "nearly always".

erikvansebille · 2026-07-30T06:49:28Z

+
+A structured grid is composed of quadrilateral elements, that are indexed using logical 2D or 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to `dimensions`, for example [...]. In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions.
+
+There are two styles of structured grids, rectilinear and curvilinear, as shown in Figure 1. Rectilinear grids are nearly always aligned with the coordinate axes (that is, there is a one-to-one mapping between the dimensions and the physical coordinate space), making them simple and computationally efficient to query. However, they're limited by the fact that it is difficult to resolve complex coastlines without high resolution, and they suffer from singularities in the flow fields at the poles where the grid lines converge. Curvilinear grids allow for curved grid lines, which allow for better representation of coastlines. They often move the poles onto land to avoid singularities occuring in the ocean. However, they become trickier to work with, as the spatial positions of their vertices are stored in separate 2D arrays, and moving to an eastward neighbour is not as simple as incrementing the $i$-th coordinate by 1.


Suggested change

There are two styles of structured grids, rectilinear and curvilinear, as shown in Figure 1. Rectilinear grids are nearly always aligned with the coordinate axes (that is, there is a one-to-one mapping between the dimensions and the physical coordinate space), making them simple and computationally efficient to query. However, they're limited by the fact that it is difficult to resolve complex coastlines without high resolution, and they suffer from singularities in the flow fields at the poles where the grid lines converge. Curvilinear grids allow for curved grid lines, which allow for better representation of coastlines. They often move the poles onto land to avoid singularities occuring in the ocean. However, they become trickier to work with, as the spatial positions of their vertices are stored in separate 2D arrays, and moving to an eastward neighbour is not as simple as incrementing the $i$-th coordinate by 1.

There are two styles of structured grids, rectilinear and curvilinear, as shown in Figure 1.

1. Rectilinear grids are nearly always aligned with the coordinate axes (that is, there is a one-to-one mapping between the dimensions and the physical coordinate space), making them simple and computationally efficient to query. However, they're limited by the fact that it is difficult to resolve complex coastlines without high resolution, and they suffer from singularities in the flow fields at the poles where the grid lines converge.

2. Curvilinear grids allow for curved grid lines, which allow for better representation of coastlines. They often move the poles onto land to avoid singularities occurring in the ocean. However, they become trickier to work with, as the spatial positions of their vertices (their ["coordinates" in xarray-parlance](https://docs.xarray.dev/en/latest/user-guide/terminology.html#term-Coordinate)) are stored in separate 2D coordinate arrays, and moving to an eastward neighbour is not as simple as incrementing the $i$-th dimension by 1.

erikvansebille · 2026-07-30T06:52:02Z

+
+Let's assume we have a simple 2D rectlinear grid. The grid is composed of a number of nodes (or vertices), connected by edges, which together construct grid cells and grid cell faces. In Figure 2, we draw a simple grid cell. Here, your data may be defined on the corners of the grid cell (the nodes/vertices), at the centre of the cell face, or across a cell edge.
+
+![Figure 2 - A simple grid cell. Blue circles denote nodes (or vertices) of the grid cell. The red circle denotes the centre of the cell face.](image-1.png)


Why not provide the code to generate this (and following) plot too? That will for sure be useful if someone later wants to adapt the plot - and it also aligns with the rest of the tutorials/documentation by making the file as self-contained as possible. I think you can even collapse/hide the input cell if it's too long and distracting

This figure is hand drawn. If you'd like, I can turn it into a python script.

erikvansebille · 2026-07-30T06:52:45Z

+
+![Figure 2 - A simple grid cell. Blue circles denote nodes (or vertices) of the grid cell. The red circle denotes the centre of the cell face.](image-1.png)
+
+You will need to make several assumptions about your data. Your data may represent a point-wise "sample" of some field. For example, velocity data may be defined at the nodes of your grid, and a fairly safe assumption to make is that you can bi-linearly interpolate these data points to your particle positions. In such an example, your velocity field may look like Figure 3.


Why "fairly safe"? I don't understand what you mean. Under what conditions is it fairly safe to make this assumption?

Again, being safe with word choices. I'll use "a typical assumption to make"

erikvansebille · 2026-07-30T06:54:52Z

+
+![Figure 3 - Bi-linear interpolation of point-wise data at nodes](image-2.png)
+
+Alternatively, your data may represent an "average value" across a cell face. For example, your temperature and salinity data may be defined at the cell centre, and represent an average value for the entire grid cell. A fairly safe assumption to make is that you can nearest-neighbour interpolate these data points to your particle positions. In such a case, your temperature field may look like figure 4.


Can we be a bit more specific than "may be defined" here? Again, under what conditions would this be typical? How could a user find out?

erikvansebille · 2026-07-30T07:05:17Z

+
+Lastly, your data may represent a value across a cell edge. For example, in (2D) Arakawa C-grid datasets, velocities are defined across an edge as they represent a "flux" across that cell edge. [for some reason an accepted assumption is] to perform a 1D linear interpolation of the zonal velocity in the zonal direction, and similarly a 1D linear interpolation of the meridional velocity in the meridional direction. In such a case, your velocity field may look like figure 5.
+
+![Figure 5 - C-grid 1D interpolation of velocity data defined across a cell edge](image-5.png)


Anything to say about vertical grids? Or even just put a placeholder?

…mplete.

for more information, see https://pre-commit.ci

michaeldenes · 2026-07-31T13:55:27Z

Whacky stuff going on with commits. Have decided to redo this in another branch and PR, using an ipynb instead of markdown file.

michaeldenes and others added 4 commits July 29, 2026 14:45

Preliminary grids explanation (need to rename images and move elsewhere)

56b73e9

Update background speed colour in fig5

67250bb

Add axes labels

8778509

Merge branch 'Parcels-code:main' into main

37bd359

github-project-automation Bot added this to Parcels development Jul 29, 2026

github-project-automation Bot moved this to Backlog in Parcels development Jul 29, 2026

[pre-commit.ci] auto fixes from pre-commit.com hooks

5231bac

for more information, see https://pre-commit.ci

erikvansebille mentioned this pull request Jul 29, 2026

Updating parcels website and documentation for v4 preview release #2702

Open

8 tasks

erikvansebille added 2 commits July 29, 2026 17:35

Small changes to first paragraph

f81176d

Update explanation_grids.md

2b1c61f

erikvansebille requested changes Jul 30, 2026

View reviewed changes

github-project-automation Bot moved this from Backlog to Ready in Parcels development Jul 30, 2026

michaeldenes and others added 12 commits July 31, 2026 10:06

Adding code snippets and Erik's suggestions. Some to do's still to co…

8ec6bca

…mplete.

Something to do with merge conflicts...

049c1ad

Re-adding parts that were missed when resolving the merge conflicts.

5de7811

[pre-commit.ci] auto fixes from pre-commit.com hooks

b4a4f5e

for more information, see https://pre-commit.ci

Too many quote marks

27999bd

[pre-commit.ci] auto fixes from pre-commit.com hooks

524d8f6

for more information, see https://pre-commit.ci

Updating figure to include vertical plane, and the caption.

ce464aa

Something again to do with the tick marks.

7f7ebc7

[pre-commit.ci] auto fixes from pre-commit.com hooks

77ff473

for more information, see https://pre-commit.ci

Small note on dimensions and coordinates.

ebecd3f

Additional info on continuity and smoothness

7dd6c70

[pre-commit.ci] auto fixes from pre-commit.com hooks

54ff5ec

for more information, see https://pre-commit.ci

michaeldenes closed this Jul 31, 2026

github-project-automation Bot moved this from Ready to Done in Parcels development Jul 31, 2026


		## Structured grids

		A structured grid is composed of quadrilateral elements, that are indexed using logical 2D or 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to `dimensions`, for example [...]. In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions.

	index = np.clip(np.searchsorted(arr, x, side="right") - 1, 0, len(arr) - 2)
	# Use broadcasting to avoid repeated array access
	arr_index = arr[index]
	arr_next = arr[np.clip(index + 1, 1, len(arr) - 1)] # Ensure we don't go out of bounds
	bcoord = (x - arr_index) / (arr_next - arr_index)


		A structured grid is composed of quadrilateral elements, that are indexed using logical 2D or 3D indices, like $(i,j,k)$. In `xarray` terminology, these indices correspond to `dimensions`, for example [...]. In structured grids, grid cell neighbours are easily found by decrementing or incrementing these dimensions.

		There are two styles of structured grids, rectilinear and curvilinear, as shown in Figure 1. Rectilinear grids are nearly always aligned with the coordinate axes (that is, there is a one-to-one mapping between the dimensions and the physical coordinate space), making them simple and computationally efficient to query. However, they're limited by the fact that it is difficult to resolve complex coastlines without high resolution, and they suffer from singularities in the flow fields at the poles where the grid lines converge. Curvilinear grids allow for curved grid lines, which allow for better representation of coastlines. They often move the poles onto land to avoid singularities occuring in the ocean. However, they become trickier to work with, as the spatial positions of their vertices are stored in separate 2D arrays, and moving to an eastward neighbour is not as simple as incrementing the $i$-th coordinate by 1.


		Let's assume we have a simple 2D rectlinear grid. The grid is composed of a number of nodes (or vertices), connected by edges, which together construct grid cells and grid cell faces. In Figure 2, we draw a simple grid cell. Here, your data may be defined on the corners of the grid cell (the nodes/vertices), at the centre of the cell face, or across a cell edge.

		![Figure 2 - A simple grid cell. Blue circles denote nodes (or vertices) of the grid cell. The red circle denotes the centre of the cell face.](image-1.png)


		![Figure 2 - A simple grid cell. Blue circles denote nodes (or vertices) of the grid cell. The red circle denotes the centre of the cell face.](image-1.png)

		You will need to make several assumptions about your data. Your data may represent a point-wise "sample" of some field. For example, velocity data may be defined at the nodes of your grid, and a fairly safe assumption to make is that you can bi-linearly interpolate these data points to your particle positions. In such an example, your velocity field may look like Figure 3.


		![Figure 3 - Bi-linear interpolation of point-wise data at nodes](image-2.png)

		Alternatively, your data may represent an "average value" across a cell face. For example, your temperature and salinity data may be defined at the cell centre, and represent an average value for the entire grid cell. A fairly safe assumption to make is that you can nearest-neighbour interpolate these data points to your particle positions. In such a case, your temperature field may look like figure 4.


		Lastly, your data may represent a value across a cell edge. For example, in (2D) Arakawa C-grid datasets, velocities are defined across an edge as they represent a "flux" across that cell edge. [for some reason an accepted assumption is] to perform a 1D linear interpolation of the zonal velocity in the zonal direction, and similarly a 1D linear interpolation of the meridional velocity in the meridional direction. In such a case, your velocity field may look like figure 5.

		![Figure 5 - C-grid 1D interpolation of velocity data defined across a cell edge](image-5.png)

Uh oh!

Conversation

michaeldenes commented Jul 29, 2026 • edited by erikvansebille Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

AI Disclosure

Uh oh!

erikvansebille left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaeldenes commented Jul 31, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

michaeldenes commented Jul 29, 2026 •

edited by erikvansebille

Loading