Add Statuscodes guide v4 #2402
Add Statuscodes guide v4 #2402
Conversation
| through_surface = particles.state == parcels.StatusCode.ErrorThroughSurface | ||
|
|
||
| # move particles to surface | ||
| particles[through_surface].dz = fieldset.W.grid.depth[0] - particles[through_surface].z |
There was a problem hiding this comment.
This line may be a bit magical to new users. Does this need a bit of information why this works?
Or even replace with
| particles[through_surface].dz = fieldset.W.grid.depth[0] - particles[through_surface].z | |
| particles[through_surface].z = fieldset.W.grid.depth[0] | |
| particles[through_surface].dz = 0 |
even though we advice not to change particles.z directly?
There was a problem hiding this comment.
I have expanded both the description before the code-cell and the comment slightly. I personally like adapting dz because I might forget the second line in your suggestion otherwise and would worry others do the same, but it does make things cleaner.
|
|
||
| If we advect particles with the `AdvectionRK2_3D` kernel, Parcels will raise a `FieldOutOfBoundSurfaceError`: | ||
|
|
||
| ```{code-cell} |
There was a problem hiding this comment.
Will it be a problem for the GitHub Action that this cell fails?
There was a problem hiding this comment.
The raises-exception tag in the following line is recognized by ReadTheDocs, and all checks pass, so I think it’s fine
| particles[out_of_bounds].state = parcels.StatusCode.Evaluate | ||
| ``` | ||
|
|
||
| Or, if you want to make sure that particles don't escape through the water surface |
There was a problem hiding this comment.
| Or, if you want to make sure that particles don't escape through the water surface | |
| When `particles.dz` is too large, they will be displaced through the surface, throwing an `ErrorThroughSurface`. We can adapt the particles.dz of these particles to move no further than the surface: |
| # find particles that move through the surface | ||
| through_surface = particles.state == parcels.StatusCode.ErrorThroughSurface | ||
|
|
||
| # move particles to surface |
There was a problem hiding this comment.
| # move particles to surface | |
| # move particles from current z exactly to the surface |
Co-authored-by: Erik van Sebille <[email protected]>
| ``` | ||
|
|
||
| ```{note} | ||
| Kernels that control what to do with `particles.state` should typically be added at the _end_ of the Kernel list, because otherwise later Kernels may overwrite the `particles.state` or the `particles.dlon` variables (see [Kernel loop explanation](explanation_kernelloop.md)). |
There was a problem hiding this comment.
The link doesn't work; tries to go to #explanation_kernelloop on the page itself?
erikvansebille
left a comment
erikvansebille
left a comment
There was a problem hiding this comment.
Apart from the broken link, it's good to go!
There was a bit of documentation on statuscodes in the kernel loop explanation, but we thought it should be its own page. Since we are mainly showing how to use them in Kernels, I have written this as a how-to guide rather than an explanation. I have added an example of how the
KeepInOceanKernel stops particles from going through the surface.I think it might be worth writing some extra text explaining the different statuscodes, either here or in an explainer. I would like to hear your thoughts on how and when to write this explanation.