Use depth dependence and a per-waypoint model for stationkeeping time by j-atkins · Pull Request #411 · Parcels-code/virtualship

j-atkins · 2026-10-19T13:15:10Z

Note

This PR is part of a stack of three related PRs (#410, #411, #412). Each one builds on the one before it. I will request reviews for each in turn.

This PR replaces the fixed, per-instrument stationkeeping time approach with a per-waypoint model. The time a waypoint adds to the schedule is now the sum of the ship's deceleration time (to come to a stop), the instrument deployment time, and the ship's acceleration time (to get back up to cruising speed). Waypoints with no instruments add no time, as the ship sails straight past without decelerating/accelerating.

Deceleration and acceleration time fields are added to the ShipConfig object in expedition.py (15 minutes each by default) and are intended as ballpark default estimates. Accordingly, they are added as configuration options in the virtualship plan tool.

All instruments must now also have a deployment_time classmethod, which determines how much time their deployment adds at the waypoint. This keeps the timing specific and configurable by developers to each instrument. At present, only CTDs add time beyond deceleration and acceleration. A CTD cast's duration depends on the water depth, using a new sea_depth_meter field on each waypoint and a new winch_speed_meter_per_second in the CTD config. When sea_depth_meter is left as null, the cast is assumed to reach the CTD's configured maximum depth rather than bathymetry (i.e. the slowest case). Incorporating the estimated sea depth from the MFP exports will be implemented in a subsequent PR (i.e. #412).

The total stationkeeping time calculation now lives in one place (Expedition.stationkeeping_time) and is used by both schedule verification and the simulation, which previously kept separate versions of the logic.

Overall, this PR instroduces a breaking change, in that the previous expedition.yaml files with per-instrument stationkeeping_time_minutes fields will be rejected.

Docs and tests have also been updated.

Other note(s)

The logic is such that waypoint-based deployments are considered as being made concurrently so only the slowest counts towards the total stationkeeping time (and this is what the docs explains). At present, this is not too relevant because it's only CTDs which add deployment time at a waypoint (depth dependence), but it means the docs will still accurate if new instruments are added which do also have added deployment times.
Concrete instrument subclass class checks, e.g. that it has sensor kernels class attribute and now, as of this PR, that it has a deployment_time abstract classmethod, have been moved to the @register_instrument decorator. This allows both class attributes (sensor kernels) and classmethods (deployment_time) to be checked at import (with messaging if something is wrong) before runtime/the instrument subclasses are instantiated.

Closes #249

…ing whether schedule or instr config; use more helper functions

…subclass__

…ependent on depth); add winch_speed to CTD config

…nkeeping_time = deceleration + deployment + acceleration time across codebase

… what MFP assumes

…o user

j-atkins · 2026-10-20T07:56:08Z

    instrument: InstrumentType | list[InstrumentType] | None = None
+    sea_depth_meter: float | None = pydantic.Field(
+        default=None, le=0.0
+    )  # estimated depth from MFP, if available. If None, instrument deployment times costed against configured max depth, thus over-estimateing rather than under-estimating than under-estimating.


Estimated depths from MFP will follow in #412

j-atkins · 2026-10-20T08:09:44Z

+    ) -> _InstrumentConfigMixin | None:
+        """The configuration for an instrument type, or None if it is not configured."""
+        return getattr(self, self._CONFIG_FIELDS[instrument_type])
+


Neater way of accessing the configuration for a given instrument

erikvansebille

Looks good - a few comments below

erikvansebille · 2026-10-20T08:15:58Z

+```
+
+```{important}
+Remember that MFP's default of 45 minutes per station may not be enough once your instruments are selected. Time at a station is made up of slowing the ship down, carrying out the deployments, and getting back up to speed again.


Be more explicit about how the total time is made up of these three aspects. I.e. explicitly mention the default 15+15 minutes of time needed for slow-down and speed-up?

erikvansebille · 2026-10-20T08:38:23Z

 DEFAULT_TS_CONFIG = {"period_minutes": 5.0}

+# ship config timings, edited in minutes in their own (collapsed by default) section
+SHIP_TIME_ATTRS = ("deceleration_time", "acceleration_time")


Maybe it's my physics-brain but when I see deceleration and acceleration, I think in terms of m s-2. Perhaps better to call it 'station_slowdown_time' and 'station_speedup_time'?

Yes good point, now changed throughout the code for consistency (in e7174b3). Note, I have used "waypoint" instead of "station" throughout, also just to keep it consistent with how we refer to them throughout the code.

erikvansebille · 2026-10-20T08:39:03Z


+                # advanced settings, which most users can leave as the defaults
+                with Collapsible(
+                    title="Ship deceleration & acceleration times",


Also make explicit that this is at stations?

erikvansebille · 2026-10-20T08:39:55Z

-        # TODO: docs suggest that add individual instrument stationkeeping times are cumulative, which is at odds with measurements being done simultaneously onboard here
-        # TODO: update one or the other?
-        return max(time_costs)
+        return self._expedition.stationkeeping_time(waypoint)


For my information, is this also relevant for ports?

Ports do not currently get slow down and speed up times, which is perhaps less realistic because of course a ship must still speed up from departure and slow down to arrival... At the moment this means the code is simpler because the Ports can simply be treated as waypoints with no instruments (and therefore no need to slow down/speed up), which sometimes users may specify so that logic would exist anyway. Do you reckon it's worth adding another rule for the Ports?

No worries, I don't think it's worth the extra code complexity. Let's leave then as is for now

erikvansebille · 2026-10-20T08:47:31Z



 def register_instrument(instrument_type):
+    """Register a concrete instrument class, refusing if doesn't meet the full Instrument contract."""


These words 'contract' and 'concrete' are quite different lingo than we use elsewhere. Rephrase?

Yes good point, will change

Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>

…for deployment, XBTs do not need to

…els/virtualship into depth-dependent-stationkeeping

…onkeeping

j-atkins · 2026-10-20T11:51:59Z

I have now addressed the comments @erikvansebille.

Please note, I have also made a few changes to the docs (quickstart and sail_the_ship guide; in 801b4cf), which go into a bit more detail on the timings associated with each instrument, plus links to the Research_proposal_intro.ipynb doc which has more information on the timings.

erikvansebille

Looks good - only one comment left. Otherwise good to go!

erikvansebille · 2026-10-20T12:18:44Z

Does drifters now have the same new sentence twice? o is that a rendering mistake in my git diff?

Oops that's my mistake, good spot thanks!

j-atkins added 10 commits October 19, 2026 14:51

move verify methods up to Expedition model; give method names reflect…

a8a1e0a

…ing whether schedule or instr config; use more helper functions

move sensor_kernels check to register_instrument rather than __init__…

8d35fc7

…subclass__

add deceleration and acceleration times to ship config

69d429a

enforce each instrument has an abstract deployment_time method (CTD d…

f5f59ec

…ependent on depth); add winch_speed to CTD config

move stationkeeping_time to Expedition model; use new model of statio…

952ce82

…nkeeping_time = deceleration + deployment + acceleration time across codebase

remove now redundant INSTRUMENT_CONFIG_MAP

45b9ed5

remove stationkeeping_time fields from instrument configs

d1aad15

update docs to reflect new stationkeeping_time model + information on…

9e0b3ff

… what MFP assumes

update test for updated stationkeeping time calcs

6051b8b

remove unnecessary messaging and remove references to now deleted

df4a9c2

j-atkins changed the title ~~Use depth dependent stationkeeping at waypoints~~ Use depth dependence and a per-waypoint model for stationkeeping time Oct 19, 2026

j-atkins changed the base branch from main to expedition-verification October 19, 2026 13:24

add ship deceleration and acceleration times to the plan tool

9b9d755

This was referenced Oct 19, 2026

Ingest sea depth from MFP export #412

Merged

Refactor: move verification methods up to Expedition class #410

Merged

j-atkins added 2 commits October 19, 2026 16:32

revert plan tool changes, need to consider how want to present this t…

49b301f

…o user

add deceleration and acceleration fields to plan TUI

8cdcb14

j-atkins commented Oct 20, 2026

View reviewed changes

j-atkins marked this pull request as ready for review October 20, 2026 08:11

j-atkins requested a review from erikvansebille October 20, 2026 08:11

erikvansebille reviewed Oct 20, 2026

View reviewed changes

Base automatically changed from expedition-verification to main October 20, 2026 08:56

j-atkins and others added 7 commits October 20, 2026 11:02

Apply suggestion from @erikvansebille

28e8a21

Co-authored-by: Erik van Sebille <erikvansebille@gmail.com>

explicit about default times for slow down and speed up

171de72

"deceleration"/"acceleration" -> "slow-down"/"speed-up" times

e7174b3

"station" -> "waypoint"

677f905

new class attribute allowing specify whether ship needs to slow down …

4f794b2

…for deployment, XBTs do not need to

Merge branch 'depth-dependent-stationkeeping' of github.com:OceanParc…

149e623

…els/virtualship into depth-dependent-stationkeeping

make docstring more consistent with rest of codebase lingo

15ade71

j-atkins added 3 commits October 20, 2026 13:27

add more docs info on times stationkeeping time per instrument

801b4cf

Merge remote-tracking branch 'origin/main' into depth-dependent-stati…

a0e6b07

…onkeeping

typos and make differences between ctd and xbt timings clearer

4883e28

j-atkins requested a review from erikvansebille October 20, 2026 11:52

erikvansebille approved these changes Oct 20, 2026

View reviewed changes

fix duplication mistake

20210d2

j-atkins merged commit dd3cd96 into main Oct 20, 2026
12 checks passed

j-atkins deleted the depth-dependent-stationkeeping branch October 20, 2026 13:49



		def register_instrument(instrument_type):
		"""Register a concrete instrument class, refusing if doesn't meet the full Instrument contract."""

Conversation

j-atkins commented Oct 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Other note(s)

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

erikvansebille left a comment

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!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

j-atkins commented Oct 20, 2026

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!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

j-atkins commented Oct 19, 2026 •

edited

Loading