Merge branch 'delete-spacetime' into joss-paper

Author: j-atkins

docs/user-guide/documentation/pre_download_data.md

@@ -20,6 +20,10 @@ In addition, all pre-downloaded data must be split into separate files per times
 **Monthly data**: when using monthly data, ensure that your final .nc file download is for the month *after* your expedition schedule end date. This is to ensure that a Parcels FieldSet can be generated under-the-hood which fully covers the expedition period. For example, if your expedition runs from 1st May to 15th May, your final monthly data file should be in June. Daily data files only need to cover the expedition period exactly.
 ```
 
+```{note}
+**Argo and Drifter data**: if using Argo floats or Drifters in your expedition, ensure that: 1) the temporal extent of the downloaded data also accounts for the full *lifetime* of the instruments, not just the expedition period, and 2) the spatial bounds of the downloaded data also accounts for the likely drift distance of the instruments over their lifetimes. Otherwise, simulations will end prematurely (out-of-bounds errors) when the data runs out.
+```
+
 Further, VirtualShip expects pre-downloaded data to be organised in a specific directory & filename structure within the specified local data directory. The expected structure is as outlined in the subsequent sections.
 
 #### Directory structure

src/virtualship/cli/_plan.py

@@ -138,15 +138,15 @@ def log_exception_to_file(
             {"name": "cycle_days"},
             {"name": "drift_days"},
             {"name": "stationkeeping_time", "minutes": True},
-            {"name": "lifetime", "minutes": True},
+            {"name": "lifetime", "days": True},
         ],
     },
     "drifter_config": {
         "class": DrifterConfig,
         "title": "Drifter",
         "attributes": [
             {"name": "depth_meter"},
-            {"name": "lifetime", "minutes": True},
+            {"name": "lifetime", "days": True},
             {"name": "stationkeeping_time", "minutes": True},
         ],
     },
@@ -264,7 +264,10 @@ def compose(self) -> ComposeResult:
                         with Container(classes="instrument-config"):
                             for attr_meta in attributes:
                                 attr = attr_meta["name"]
-                                is_minutes = attr_meta.get("minutes", False)
+                                is_minutes, is_days = (
+                                    attr_meta.get("minutes", False),
+                                    attr_meta.get("days", False),
+                                )
                                 validators = group_validators(config_class, attr)
                                 if config_instance:
                                     raw_value = getattr(config_instance, attr, "")
@@ -275,16 +278,23 @@ def compose(self) -> ComposeResult:
                                             )
                                         except AttributeError:
                                             value = str(raw_value)
+                                    elif is_days and raw_value != "":
+                                        try:
+                                            value = str(
+                                                raw_value.total_seconds() / 86400.0
+                                            )
+                                        except AttributeError:
+                                            value = str(raw_value)
                                     else:
                                         value = str(raw_value)
                                 else:
                                     value = ""
                                 label = f"{attr.replace('_', ' ').title()}:"
-                                yield Label(
-                                    label
-                                    if not is_minutes
-                                    else label.replace(":", " Minutes:")
-                                )
+                                if is_minutes:
+                                    label = label.replace(":", " Minutes:")
+                                elif is_days:
+                                    label = label.replace(":", " Days:")
+                                yield Label(label)
                                 yield Input(
                                     id=f"{instrument_name}_{attr}",
                                     type=type_to_textual(
@@ -392,11 +402,14 @@ def _update_instrument_configs(self):
             for attr_meta in attributes:
                 attr = attr_meta["name"]
                 is_minutes = attr_meta.get("minutes", False)
+                is_days = attr_meta.get("days", False)
                 input_id = f"{instrument_name}_{attr}"
                 value = self.query_one(f"#{input_id}").value
                 field_type = get_field_type(config_class, attr)
                 if is_minutes and field_type is datetime.timedelta:
                     value = datetime.timedelta(minutes=float(value))
+                elif is_days and field_type is datetime.timedelta:
+                    value = datetime.timedelta(days=float(value))
                 else:
                     value = field_type(value)
                 kwargs[attr] = value

src/virtualship/instruments/base.py

@@ -149,20 +149,17 @@ def _get_copernicus_ds(
         depth_max = self._get_spec_value("limit", "depth_max", None)
         spatial_constraint = self._get_spec_value("limit", "spatial", True)
 
+        min_lon_bound = self.min_lon - latlon_buffer if spatial_constraint else None
+        max_lon_bound = self.max_lon + latlon_buffer if spatial_constraint else None
+        min_lat_bound = self.min_lat - latlon_buffer if spatial_constraint else None
+        max_lat_bound = self.max_lat + latlon_buffer if spatial_constraint else None
+
         return copernicusmarine.open_dataset(
             dataset_id=product_id,
-            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,
+            minimum_longitude=min_lon_bound,
+            maximum_longitude=max_lon_bound,
+            minimum_latitude=min_lat_bound,
+            maximum_latitude=max_lat_bound,
             variables=[var],
             start_datetime=self.min_time,
             end_datetime=self.max_time + timedelta(days=time_buffer),
@@ -182,8 +179,6 @@ def _generate_fieldset(self) -> FieldSet:
 
         time_buffer = self._get_spec_value("buffer", "time", 0.0)
 
-        # TODO: also limit from-data to spatial domain?
-
         for key in keys:
             var = self.variables[key]
             if self.from_data is not None:  # load from local data

src/virtualship/models/expedition.py

@@ -14,7 +14,7 @@
 from virtualship.utils import (
     _get_bathy_data,
     _get_waypoint_latlons,
-    _validate_numeric_mins_to_timedelta,
+    _validate_numeric_to_timedelta,
 )
 
 from .location import Location
@@ -214,8 +214,8 @@ class ArgoFloatConfig(pydantic.BaseModel):
     cycle_days: float = pydantic.Field(gt=0.0)
     drift_days: float = pydantic.Field(gt=0.0)
     lifetime: timedelta = pydantic.Field(
-        serialization_alias="lifetime_minutes",
-        validation_alias="lifetime_minutes",
+        serialization_alias="lifetime_days",
+        validation_alias="lifetime_days",
         gt=timedelta(),
     )
 
@@ -227,19 +227,19 @@ class ArgoFloatConfig(pydantic.BaseModel):
 
     @pydantic.field_serializer("lifetime")
     def _serialize_lifetime(self, value: timedelta, _info):
-        return value.total_seconds() / 60.0
+        return value.total_seconds() / 86400.0  # [days]
 
     @pydantic.field_validator("lifetime", mode="before")
     def _validate_lifetime(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "days")
 
     @pydantic.field_serializer("stationkeeping_time")
     def _serialize_stationkeeping_time(self, value: timedelta, _info):
         return value.total_seconds() / 60.0
 
     @pydantic.field_validator("stationkeeping_time", mode="before")
     def _validate_stationkeeping_time(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "minutes")
 
     model_config = pydantic.ConfigDict(populate_by_name=True)
 
@@ -263,7 +263,7 @@ def _serialize_period(self, value: timedelta, _info):
 
     @pydantic.field_validator("period", mode="before")
     def _validate_period(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "minutes")
 
 
 class CTDConfig(pydantic.BaseModel):
@@ -285,7 +285,7 @@ def _serialize_stationkeeping_time(self, value: timedelta, _info):
 
     @pydantic.field_validator("stationkeeping_time", mode="before")
     def _validate_stationkeeping_time(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "minutes")
 
 
 class CTD_BGCConfig(pydantic.BaseModel):
@@ -307,7 +307,7 @@ def _serialize_stationkeeping_time(self, value: timedelta, _info):
 
     @pydantic.field_validator("stationkeeping_time", mode="before")
     def _validate_stationkeeping_time(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "minutes")
 
 
 class ShipUnderwaterSTConfig(pydantic.BaseModel):
@@ -327,16 +327,16 @@ def _serialize_period(self, value: timedelta, _info):
 
     @pydantic.field_validator("period", mode="before")
     def _validate_period(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "minutes")
 
 
 class DrifterConfig(pydantic.BaseModel):
     """Configuration for drifters."""
 
     depth_meter: float = pydantic.Field(le=0.0)
     lifetime: timedelta = pydantic.Field(
-        serialization_alias="lifetime_minutes",
-        validation_alias="lifetime_minutes",
+        serialization_alias="lifetime_days",
+        validation_alias="lifetime_days",
         gt=timedelta(),
     )
     stationkeeping_time: timedelta = pydantic.Field(
@@ -349,19 +349,19 @@ class DrifterConfig(pydantic.BaseModel):
 
     @pydantic.field_serializer("lifetime")
     def _serialize_lifetime(self, value: timedelta, _info):
-        return value.total_seconds() / 60.0
+        return value.total_seconds() / 86400.0  # [days]
 
     @pydantic.field_validator("lifetime", mode="before")
     def _validate_lifetime(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "days")
 
     @pydantic.field_serializer("stationkeeping_time")
     def _serialize_stationkeeping_time(self, value: timedelta, _info):
         return value.total_seconds() / 60.0
 
     @pydantic.field_validator("stationkeeping_time", mode="before")
     def _validate_stationkeeping_time(cls, value: int | float | timedelta) -> timedelta:
-        return _validate_numeric_mins_to_timedelta(value)
+        return _validate_numeric_to_timedelta(value, "minutes")
 
 
 class XBTConfig(pydantic.BaseModel):

src/virtualship/static/expedition.yaml

@@ -43,7 +43,7 @@ instruments_config:
     min_depth_meter: 0.0
     vertical_speed_meter_per_second: -0.1
     stationkeeping_time_minutes: 20.0
-    lifetime_minutes: 90720.0
+    lifetime_days: 63.0
   ctd_config:
     max_depth_meter: -2000.0
     min_depth_meter: -11.0
@@ -54,7 +54,7 @@ instruments_config:
     stationkeeping_time_minutes: 50.0
   drifter_config:
     depth_meter: -1.0
-    lifetime_minutes: 60480.0
+    lifetime_days: 42.0
     stationkeeping_time_minutes: 20.0
   xbt_config:
     max_depth_meter: -285.0

src/virtualship/utils.py

@@ -186,11 +186,16 @@ def mfp_to_yaml(coordinates_file_path: str, yaml_output_path: str):  # noqa: D41
     expedition.to_yaml(yaml_output_path)
 
 
-def _validate_numeric_mins_to_timedelta(value: int | float | timedelta) -> timedelta:
-    """Convert minutes to timedelta when reading."""
+def _validate_numeric_to_timedelta(
+    value: int | float | timedelta, unit: str
+) -> timedelta:
+    """Convert to timedelta when reading."""
     if isinstance(value, timedelta):
         return value
-    return timedelta(minutes=value)
+    if unit == "minutes":
+        return timedelta(minutes=float(value))
+    elif unit == "days":
+        return timedelta(days=float(value))
 
 
 def _get_expedition(expedition_dir: Path) -> Expedition:

tests/expedition/expedition_dir/expedition.yaml

@@ -30,7 +30,7 @@ instruments_config:
     min_depth_meter: 0.0
     vertical_speed_meter_per_second: -0.1
     stationkeeping_time_minutes: 20.0
-    lifetime_minutes: 90720.0
+    lifetime_days: 63.0
   ctd_config:
     max_depth_meter: -2000.0
     min_depth_meter: -11.0
@@ -41,7 +41,7 @@ instruments_config:
     stationkeeping_time_minutes: 50.0
   drifter_config:
     depth_meter: -1.0
-    lifetime_minutes: 40320.0
+    lifetime_days: 28.0
     stationkeeping_time_minutes: 20.0
   ship_underwater_st_config:
     period_minutes: 5.0