DOCS: Add tutorial for writing converter functions by VeckoTheGecko · Pull Request #2939 · Parcels-code/Parcels

VeckoTheGecko · 2026-10-06T14:38:18Z

Description

(Will populate PR template later - submitting now for review discussion)

Checklist

Closes #xxxx
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):

VeckoTheGecko · 2026-10-06T14:38:58Z

I merged #2938 (which was quite cut and dry) so that we could focus on this

VeckoTheGecko · 2026-10-06T14:41:02Z

keen to hear your thoughts here @erikvansebille .

I think there are some items in What a convert function needs to produce that need to be worked on (either via copy edits here, or via improvements to the code itself - so that more stuff is pulled from the available metadata) - but other than that this is very much in line with my understanding of SGRID.

erikvansebille

Very useful manual! See below some comments/thoughts/questions

erikvansebille · 2026-10-07T06:39:47Z

+Parcels reads structured-grid model data through {py:func}`parcels.FieldSet.from_sgrid_conventions`. This function
+does not guess how your model grid is laid out. Instead, it reads [SGRID](https://sgrid.github.io/sgrid/) metadata


I find the "does not ... instead" wording a bit confusing. Why not the simpler

Suggested change

Parcels reads structured-grid model data through {py:func}`parcels.FieldSet.from_sgrid_conventions`. This function

does not guess how your model grid is laid out. Instead, it reads [SGRID](https://sgrid.github.io/sgrid/) metadata

Parcels reads structured-grid model data through {py:func}`parcels.FieldSet.from_sgrid_conventions`. This function reads [SGRID](https://sgrid.github.io/sgrid/) metadata

erikvansebille · 2026-10-07T06:42:54Z

+walks through writing a converter for a made-up model, and shows how to check the result with `describe()`.
+
+```{note}
+This guide covers structured grids only (SGRID). Unstructured grids use the UGRID conventions and are not covered here.


@wyatt-fluidnumerics and @fluidnumericsJoe do you want to extend this manual to UGRID too? In a next PR?

erikvansebille · 2026-10-08T06:40:30Z

+{py:func}`parcels.FieldSet.describe` to check that the vector fields were found and that the mesh is what you expect:
+
+```{code-cell}
+fieldset = parcels.FieldSet.from_sgrid_conventions(ds)


Is it intentional that there's a warning? Should we mention anything about it? Or fix it in the convert function?

erikvansebille · 2026-10-08T06:41:55Z

+print(f"x: {pset.x[0]:.4f} (expected ~{expected_x:.4f})")
+print(f"y: {pset.y[0]:.4f} (expected ~{expected_y:.4f})")
+print(f"z: {pset.z[0]:.4f} (expected ~{expected_z:.4f})")


Should we also do these as asserts, so that the RTD fails if for any reason they don't agree?

erikvansebille · 2026-10-08T06:42:44Z

+| `No variable found in dataset with 'cf_role' attribute set to 'grid_topology'`                 | No SGRID metadata has been attached.                               | Add the `grid` variable (Step 2, part 5).                                                                                                      |
+| `DataArray 'U' with dims (...) has dimensions {'kt'} that are not associated with a direction` | A field dimension is not listed in the SGRID metadata.             | Add it to `face_dimensions` or `vertical_dimensions`, or drop the extra dimension (e.g. with `.isel`).                                         |
+| `No variable named 'lat'`                                                                      | The node coordinates have not been renamed.                        | Rename them to `lon` and `lat`, and make sure `node_coordinates` is `"lon lat"`.                                                               |
+| `Coordinate 'lon' of your dataset has no 'units' attribute`                                    | Parcels cannot tell whether the mesh is spherical or flat.         | Set `units` (e.g. `"degrees_east"` or `"m"`), or pass `mesh=` to `from_sgrid_conventions`.                                                     |


Do we need to be even more explicit how to set units?

erikvansebille · 2026-10-08T06:45:13Z

+| _No error, but particles don't move vertically, or move the wrong way_                         | `W` is not named `W`, or its sign convention is positive upward.   | Rename it to `W`, and negate it if the model uses positive upward.                                                                             |
+
+## A template to start from
+


Add one sentence what to do with the template below? (although the title is relatively self-explanatory)

I'm happy leaving it as is. Adding "copy paste the following into where you're writing your code" doesn't really add much value I think

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

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

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

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

github-project-automation Bot added this to Parcels development Oct 6, 2026

VeckoTheGecko marked this pull request as draft October 6, 2026 14:39

VeckoTheGecko requested a review from erikvansebille October 6, 2026 14:39

VeckoTheGecko changed the title ~~Add tutorial_writing_convert_functions.md~~ DOCS: Add tutorial for writing converter functions Oct 6, 2026

erikvansebille requested changes Oct 8, 2026

View reviewed changes

VeckoTheGecko mentioned this pull request Oct 8, 2026

Fix rendering of SGRID metadata #2952

Open

VeckoTheGecko and others added 7 commits October 8, 2026 13:54

Add tutorial_writing_convert_functions.md

6113695

Update docs/user_guide/examples/tutorial_writing_convert_functions.md

405fdb4

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

Rename file to explanation_...

ea2d3b2

Update docs/user_guide/examples/explanation_writing_convert_functions.md

bf09543

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

Update docs/user_guide/examples/explanation_writing_convert_functions.md

7fcf09c

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

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

1ed22c0

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

Review feedback

ede7880

VeckoTheGecko force-pushed the push-snmzxtpwntxv branch from 46ee402 to ede7880 Compare October 8, 2026 13:03

VeckoTheGecko and others added 4 commits October 8, 2026 16:16

Add note about difference between axis and dimension

a19929e

Apply batched suggestions from code review

3017a42

Co-authored-by: Erik van Sebille <e.vansebille@uu.nl>

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

f654ad9

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

Update note on padding types

2453dab

		Parcels reads structured-grid model data through {py:func}`parcels.FieldSet.from_sgrid_conventions`. This function
		does not guess how your model grid is laid out. Instead, it reads [SGRID](https://sgrid.github.io/sgrid/) metadata

		\| _No error, but particles don't move vertically, or move the wrong way_ \| `W` is not named `W`, or its sign convention is positive upward. \| Rename it to `W`, and negate it if the model uses positive upward. \|

		## A template to start from

Conversation

VeckoTheGecko commented Oct 6, 2026

Description

Checklist

AI Disclosure

Uh oh!

VeckoTheGecko commented Oct 6, 2026

Uh oh!

VeckoTheGecko commented Oct 6, 2026

Uh oh!

erikvansebille left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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!

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants