Remove spacetime-region by j-atkins · Pull Request #264 · Parcels-code/virtualship

j-atkins · 2025-12-09T08:42:03Z

Overview

This PR removes SpaceTimeRegion from the expedition config. Now, instead, space-time boundaries are defined in reference to the extremes of the waypoints when building fieldsets (i.e. the minimum/maximum latitude/longitude/time across all waypoints). This avoids divergence between user defined waypoints and the prescribed space-time region (i.e. #259).

I also experimented with not defining any spatial limits at all for the fieldset generation. For instruments which require data at depth (Argos, CTDs, XBTs, ADCP) this is still too slow/memory intensive, so I have kept the lat, lon subsetting in copernicusmarine.open_dataset(..). However, for surface-only instruments (Drifters), the lat, lon subsetting can be relaxed. This is a big advantage because it removes out-of-bounds issues for Drifters. The bathymetry fields also require no lat, lon bounds.

Otherwise of interest - and happily - I think there could a speed boost as result of the changes in this PR (with e.g. Argo floats and the underway instruments), but I haven't confirmed this nor diagnosed exactly why this might be happening.

Drifter/Argo lifetimes

Drifters

The logic for determining the temporal extent for drifter fieldsets has changed. Before there was a generic 41+21 day time buffer added.
Now, the drifter lifetime parameter (in InstrumentConfig) also controls the endtime of the fieldset (so it will be the last waypoint time + the drifter lifetime).
This, in combination the relaxed lat, lon bounds, means that users can set whatever lifetime they wish without hitting out-of-bounds errors.

Argo floats

Previously Argo float lifetimes were controlled by the temporal extent of the fieldset.
There is a now a lifetime parameter added to the Argo configuration (in InstrumentConfig), giving more control to the user. This defaults to 3 months.
Now, similarly to Drifters, the fieldset endtime is controlled by the lifetime parameter, rather than the other way round.
Because we cannot yet relax the lat, lon bounds for the Argos, it is still possible to hit out-of-bounds errors with Argos. Though, this is not very common and I think less likely than was previously the case with Drifters at the surface.
Parcels v4 could allow us to relax the lat, lon bounds on all instruments, so this may not even be problem for Argos in the future (?)
- This would allow VirtualShip Argos to match real-life Argo lifetimes in theory...

Closes SpaceTimeRegion problems when changing waypoints after initialisation #259
Tests updated

…pacetime domain

…n object

erikvansebille

Looks good! Great improvement which will reduce annoying outofbounds errors and thereby increase authenticity!

A few comments below

erikvansebille · 2025-12-09T12:07:10Z

src/virtualship/cli/_plan.py

            {"name": "cycle_days"},
            {"name": "drift_days"},
            {"name": "stationkeeping_time", "minutes": True},
+            {"name": "lifetime", "minutes": True},


Not sure what "minutes' here means, but would this not be more logical in days?

erikvansebille · 2025-12-09T12:10:18Z

src/virtualship/instruments/base.py

+            minimum_longitude=self.min_lon - latlon_buffer
+            if spatial_constraint
+            else None,
+            maximum_longitude=self.max_lon + latlon_buffer
+            if spatial_constraint
+            else None,
+            minimum_latitude=self.min_lat - latlon_buffer
+            if spatial_constraint
+            else None,
+            maximum_latitude=self.max_lat + latlon_buffer
+            if spatial_constraint
+            else None,


Is this correct python code? Looks strange, without indents etc

Yes agree it doesn't look great, ruff auto-formatted to this. I'll adjust it anyway 👍

erikvansebille · 2025-12-09T12:12:43Z

src/virtualship/models/expedition.py


+    @pydantic.field_serializer("lifetime")
+    def _serialize_lifetime(self, value: timedelta, _info):
+        return value.total_seconds() / 60.0


Again, would this not make more sense in days?

src/virtualship/static/expedition.yaml

erikvansebille · 2025-12-09T12:13:30Z

src/virtualship/static/expedition.yaml

    min_depth_meter: 0.0
    vertical_speed_meter_per_second: -0.1
    stationkeeping_time_minutes: 20.0
+    lifetime_minutes: 90720.0


erikvansebille · 2025-12-09T12:16:05Z

tests/test_utils.py

+        schedule_start=datetime.datetime(1995, 6, 1, 0, 0, 0),
+        schedule_end=datetime.datetime(1995, 6, 30, 0, 0, 0),


Perhaps not relevant for this PR< but at some point it might be good to transition to numpy.datimetime64 throughout the code in order to better align with Parcels v4?

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

…p into delete-spacetime

…etime in minutes

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

…p into delete-spacetime

…time bounds

j-atkins · 2026-01-05T12:30:27Z

I have made the suggested edits to this PR, mainly changing the drifter/argo lifetime specification to days.

Docs build was also failing but I have now updated the broken links 👍

erikvansebille

Looks good! One final comment below

erikvansebille · 2026-01-05T12:44:32Z

src/virtualship/utils.py

+    if unit == "minutes":
+        return timedelta(minutes=float(value))
+    elif unit == "days":
+        return timedelta(days=float(value))


Do we need to raise an error here if unit is not "minutes' or "days"? E.g. that we don't support "months" or "years"?

Good point, I've added this now

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

j-atkins added 10 commits December 2, 2025 10:59

first round, delete SpaceTimeRegion object and related classes/methods

2ba9073

remove space time region from _plan

e9dbd78

update base and instrument class logic to use waypoint extremes for s…

5a5e056

…pacetime domain

clean up _plan methods

b5eea49

extend latlon buffer for drifters

ffe07fc

set time buffer from drifter lifetime config

a5d692a

shift testing to use waypoint space-times instead of space-time-regio…

6ebb41b

…n object

fix assert error messaging

1f778ea

remove spatial constraint on fieldset ingestion

14b8833

Merge branch 'main' into delete-spacetime

1affd50

j-atkins marked this pull request as draft December 9, 2025 08:42

j-atkins added 4 commits December 9, 2025 10:02

add control over whether to constrain spatial region in fieldset

714b0bf

give argos a prescribed lifetime

e820584

add lifetime field to expedition models and _plan

7369f46

update test with argo lifetime

15848f3

j-atkins force-pushed the delete-spacetime branch from ade2622 to 15848f3 Compare December 9, 2025 10:15

j-atkins marked this pull request as ready for review December 9, 2025 11:24

j-atkins requested review from VeckoTheGecko, ammedd and erikvansebille December 9, 2025 11:24

remove temporary debugging tools

ba3793b

j-atkins force-pushed the delete-spacetime branch from 113a3c0 to ba3793b Compare December 9, 2025 12:17

erikvansebille reviewed Dec 9, 2025

View reviewed changes

pre-commit-ci bot and others added 3 commits December 9, 2025 12:18

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

340d940

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

update argo endtime and give depth lim in fieldset generation

7eff191

remove depth lim on fieldset generation

fd6a3f6

j-atkins mentioned this pull request Dec 10, 2025

JOSS manuscript #265

Merged

j-atkins mentioned this pull request Dec 19, 2025

Argo floats in shallow waters #262

Closed

j-atkins added 2 commits December 19, 2025 12:50

Merge branch 'main' into delete-spacetime

edf8149

clean up comment

b00c85c

j-atkins and others added 10 commits December 23, 2025 16:28

Merge branch 'delete-spacetime' of github.com:OceanParcels/virtualshi…

86fa3f6

…p into delete-spacetime

change lifetime in expedition model to be in days units

ff43127

update _plan logic (+ more changes to expedition model) to handle lif…

87de210

…etime in minutes

small refactor for readability

593e0f2

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

6ae1317

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

remove broken links

2e8c14a

Merge branch 'delete-spacetime' of github.com:OceanParcels/virtualshi…

4fd2d77

…p into delete-spacetime

update pre-downloaded data documentation to explain argo/drifter life…

984d441

…time bounds

fix docs build?

009f09f

another broken link

af3ec8c

j-atkins requested a review from erikvansebille January 5, 2026 12:30

erikvansebille reviewed Jan 5, 2026

View reviewed changes

j-atkins and others added 2 commits January 5, 2026 14:10

add error messaging for unsuported time units

982e52e

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

18d29f2

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

erikvansebille approved these changes Jan 5, 2026

View reviewed changes

j-atkins merged commit 4b3b543 into main Jan 5, 2026
10 checks passed

j-atkins deleted the delete-spacetime branch January 5, 2026 13:26

j-atkins mentioned this pull request Jan 30, 2026

TimeRange handling in _plan #254

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Remove spacetime-region#264

Remove spacetime-region#264
j-atkins merged 32 commits intomainfrom
delete-spacetime

j-atkins commented Dec 9, 2025 •

edited

Loading

Uh oh!

erikvansebille left a comment

Uh oh!

erikvansebille Dec 9, 2025

Uh oh!

erikvansebille Dec 9, 2025

Uh oh!

j-atkins Dec 9, 2025

Uh oh!

erikvansebille Dec 9, 2025

Uh oh!

Uh oh!

erikvansebille Dec 9, 2025

Uh oh!

erikvansebille Dec 9, 2025

Uh oh!

j-atkins commented Jan 5, 2026

Uh oh!

erikvansebille left a comment

Uh oh!

erikvansebille Jan 5, 2026

Uh oh!

j-atkins Jan 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		schedule_start=datetime.datetime(1995, 6, 1, 0, 0, 0),
		schedule_end=datetime.datetime(1995, 6, 30, 0, 0, 0),

Conversation

j-atkins commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Drifter/Argo lifetimes

Drifters

Argo floats

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!

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!

j-atkins commented Jan 5, 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

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

j-atkins commented Dec 9, 2025 •

edited

Loading