Add tutorial for SCHISM model for lake ontario.

[fluidnumericsJoe]

Description

This is a minimum working example that illustrates primarily how to do 2D (lateral) particle advection with SCHISM model output. It walks through handling issues with uxarray, which assumes that the input grid is in units of degrees for latitude and longitude.

The SCHISM output provided here uses x,y in cartesian coordinates in units of meters. Since uxarray automatically wraps longitude to be between [0,360] we have to overwrite the node_lon values stored in the uxgrid object.

We show how to rename the SCHISM velocity field components, lateral node coordinate, and vertical grid names to match what Parcels expects to see. Note that we intentionally create a ficticious vertical grid in this example; Parcels currently does not support the LSC2 vertical grid that is used in SCHISM and this is documented clearly in the tutorial.

Checklist

• 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): Claude code was used to copy edit the SCHISM tutorial to ensure we maintain similar tone and structure with other tutorials in the parcels documentation.

[erikvansebille]

Nice tutorial! I made some minor changes to the text in f1eb2a0

A few questions

1. Should StatusCodes become part of the public API? So users can import it as parcels.StatusCodes? @VeckoTheGecko, what do you think?
2. It seems that UXARRAY/uxarray#1525 is close to being fixed. Should we wait for it? Or merge this now and update when a new version of uxarray is released?
3. I'm getting a warning (below) in the pset.execute(), is this a problemm?

/Users/erik/Codes/parcels/src/parcels/_core/spatialhash.py:592: RuntimeWarning: invalid value encountered in cast
  xq = np.clip((xn * bitwidth).astype(np.uint32), 0, bitwidth)

[VeckoTheGecko]

1. Should StatusCodes become part of the public API? So users can import it as parcels.StatusCodes? @VeckoTheGecko, what do you think?

Given this line

Parcels/docs/user_guide/v4-migration.md

Line 10 in 6ef510d

- `particle.delete()` is no longer valid. Instead, use `particle.state = StatusCode.Delete`.

in the migration guide I think it should be part of the public API. Also I think its a good idea given how important states are for Parcels and users.

I just checked, it is already public API

[VeckoTheGecko]

for name, field in fieldset.fields.items():
    interp = getattr(field, "interp_method", None)
    print(
        f"{name:>4s} -> {type(field).__name__:<11s} interp={interp.__name__ if interp else '-'}"
    )

Just curious: I'm surprised that the interp_method is None sometimes here, is this from the vector fields?

[fluidnumericsJoe]

Just curious: I'm surprised that the interp_method is None sometimes here, is this from the vector fields?

Indeed, VectorField interpolator defaults to None and output from that cell is

   U -> Field       interp=UxLinearNodeLinearZF
   V -> Field       interp=UxLinearNodeLinearZF
  UV -> VectorField interp=-

If I recall correctly VectorField.eval falls back to component-wise interpolation when the VectorField interpolation method is None.

[fluidnumericsJoe]

@erikvansebille

I'm getting a warning (below) in the pset.execute(), is this a problemm?

/Users/erik/Codes/parcels/src/parcels/_core/spatialhash.py:592: RuntimeWarning: invalid value encountered in cast
  xq = np.clip((xn * bitwidth).astype(np.uint32), 0, bitwidth)

I'm 99% certain that these are coming from the particles that subsequently get removed from the simulation - they're lat/lon positions end up as NaN from interpolation when they run into ground.

We could suppress this warning moving the xq and yq calculations into the with np.errstate(invalid="ignore"): block, but it might be best to let this warning persist. The additional kernel I've added to delete these grounded particles does make the NaN positions benign.

[fluidnumericsJoe]

It seems that UXARRAY/uxarray#1525 is close to being fixed. Should we wait for it? Or merge this now and update when a new version of uxarray is released?

Maybe to prevent "documentation whiplash", it'd be good to keep this one open and wait for the uxarray fix to come in. Let's give it a couple of days to see how the uxarray PR progresses.