Skip to content

Update underway - #360

Merged
j-atkins merged 28 commits into
migrate-v4from
update-underway
Jul 31, 2026
Merged

Update underway#360
j-atkins merged 28 commits into
migrate-v4from
update-underway

Conversation

@j-atkins

@j-atkins j-atkins commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator

This PR implements a move to using Field.eval for underway instrument simulations (ADCP, UnderwaterST). This is enabled by Parcels v4 and delivers much faster performance.

To facilitate this, there is a new abstract/intermediate class for underway instruments in base.py: UnderwayInstrument, which the ADCP and UnderwaterST concrete subclasses inherit from. Plus a new UnderwayCoordinates dataclass for housing the final sampling locations and timings. There are new tests for these in test_base.py

Also, underway instruments still have 'kernels' but are not traditional Parcels kernels. Instead, they are standard functions which make the Field.eval call. This means underway instruments continue to meet the requirements for all instruments to have sampling kernels associated with sensors.


Closes #231

@j-atkins
j-atkins marked this pull request as ready for review July 30, 2026 08:54
@j-atkins
j-atkins requested a review from erikvansebille July 30, 2026 08:55

@erikvansebille erikvansebille left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good; a few questions/suggestions below

Comment thread src/virtualship/instruments/adcp.py Outdated
Comment on lines +87 to +89
_time_ref_key = next(iter(self.variables))
_time_ref_field = getattr(fieldset, _time_ref_key)
fieldset_starttime = _time_ref_field.data.time.isel(time=0).values

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you also use fieldset.time_interval.left here?

Comment thread src/virtualship/instruments/base.py Outdated

@dataclass(frozen=True)
class UnderwayCoordinates:
"""1D evaluation grid arrays for underway instruments."""

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what do you mean with "grid arrays" here?

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, perhaps this is confusing, will update

Comment thread src/virtualship/instruments/base.py Outdated
"y": pa.array(coords.lats.astype(np.float32)),
"x": pa.array(coords.lons.astype(np.float32)),
"particle_id": pa.array(
np.arange(n, dtype=np.int64)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it not make sense to give all data the same particle ID (interpreting the ship as one particle)?

origin_str = str(fieldset_time_origin).replace("T", " ")
t_metadata = {"units": f"seconds since {origin_str}", "calendar": "standard"}

# base schema mirroring Parcels ParticleFile schema, not yet with sampled variables

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would it make sense to also open a parcels.ParticleFile object to check if the schemes are the same - and error out if they are not? In that way, we can spot when the schemas start to deviate

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have now added a new unit test for this (in ccd0ae3). The scheme is not in the public API for parcels.PartileFile so I have done it by executing a simple Parcels simulation and comparing the scheme of the resultant output against the UnderwayInstrument output.

Comment thread src/virtualship/instruments/ship_underwater_st.py Outdated
@j-atkins

Copy link
Copy Markdown
Collaborator Author

Thanks for the comments @erikvansebille, I have now made the changes in response 👍

@erikvansebille erikvansebille left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Three small points/questions; looks good otherwise!

Comment thread tests/instruments/test_base.py Outdated
Comment thread tests/instruments/test_base.py Outdated
Comment thread src/virtualship/instruments/base.py Outdated
Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>
@j-atkins
j-atkins merged commit 4dfa96f into migrate-v4 Jul 31, 2026
6 of 7 checks passed
@j-atkins
j-atkins deleted the update-underway branch July 31, 2026 09:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants