virtualship 0.0.3.dev44__py3-none-any.whl

virtualship/__init__.py

@@ -0,0 +1,18 @@
+"""Code for the Virtual Ship Classroom, where Marine Scientists can combine Copernicus Marine Data with an OceanParcels ship to go on a virtual expedition."""
+
+from importlib.metadata import version as _version
+
+from .location import Location
+from .spacetime import Spacetime
+
+try:
+    __version__ = _version("virtualship")
+except Exception:
+    # Local copy or not installed with setuptools
+    __version__ = "unknown"
+
+__all__ = [
+    "Location",
+    "Spacetime",
+    "__version__",
+]

virtualship/_version_setup.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.0.3.dev44'
+__version_tuple__ = version_tuple = (0, 0, 3, 'dev44')

virtualship/cli/__init__.py

@@ -0,0 +1 @@
+"""Command line interface tools."""

virtualship/cli/commands.py

@@ -0,0 +1,40 @@
+from pathlib import Path
+
+import click
+
+from virtualship.expedition.do_expedition import do_expedition
+
+
+@click.command(
+    help="Initialize a directory for a new expedition, with an example configuration."
+)
+@click.argument(
+    "path",
+    type=click.Path(exists=False, file_okay=False, dir_okay=True),
+    # help="Expedition directory",
+)
+def init(path):
+    """Entrypoint for the tool."""
+    raise NotImplementedError("Not implemented yet.")
+
+
+@click.command(
+    help="Download the relevant data specified in an expedition directory (i.e., by the expedition config)."
+)
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, readable=True),
+)
+def fetch(path):
+    """Entrypoint for the tool."""
+    raise NotImplementedError("Not implemented yet.")
+
+
+@click.command(help="Do the expedition.")
+@click.argument(
+    "path",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, readable=True),
+)
+def run(path):
+    """Entrypoint for the tool."""
+    do_expedition(Path(path))

virtualship/cli/main.py

@@ -0,0 +1,17 @@
+import click
+
+from . import commands
+
+
+@click.group()
+@click.version_option()
+def cli():
+    pass
+
+
+cli.add_command(commands.init)
+cli.add_command(commands.fetch)
+cli.add_command(commands.run)
+
+if __name__ == "__main__":
+    cli()

virtualship/expedition/__init__.py

@@ -0,0 +1,28 @@
+"""Everything for simulating an expedition."""
+
+from .do_expedition import do_expedition
+from .instrument_type import InstrumentType
+from .schedule import Schedule
+from .ship_config import (
+    ADCPConfig,
+    ArgoFloatConfig,
+    CTDConfig,
+    DrifterConfig,
+    ShipConfig,
+    ShipUnderwaterSTConfig,
+)
+from .waypoint import Waypoint
+
+__all__ = [
+    "ADCPConfig",
+    "ArgoFloatConfig",
+    "CTDConfig",
+    "DrifterConfig",
+    "InstrumentType",
+    "Schedule",
+    "ShipConfig",
+    "ShipUnderwaterSTConfig",
+    "Waypoint",
+    "do_expedition",
+    "instruments",
+]

virtualship/expedition/checkpoint.py

@@ -0,0 +1,51 @@
+"""Checkpoint class."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pydantic
+import yaml
+
+from .instrument_type import InstrumentType
+from .schedule import Schedule
+
+
+class _YamlDumper(yaml.SafeDumper):
+    pass
+
+
+_YamlDumper.add_representer(
+    InstrumentType, lambda dumper, data: dumper.represent_data(data.value)
+)
+
+
+class Checkpoint(pydantic.BaseModel):
+    """
+    A checkpoint of schedule simulation.
+
+    Copy of the schedule until where the simulation proceeded without troubles.
+    """
+
+    past_schedule: Schedule
+
+    def to_yaml(self, file_path: str | Path) -> None:
+        """
+        Write checkpoint to yaml file.
+
+        :param file_path: Path to the file to write to.
+        """
+        with open(file_path, "w") as file:
+            yaml.dump(self.model_dump(by_alias=True), file, Dumper=_YamlDumper)
+
+    @classmethod
+    def from_yaml(cls, file_path: str | Path) -> Checkpoint:
+        """
+        Load checkpoint from yaml file.
+
+        :param file_path: Path to the file to load from.
+        :returns: The checkpoint.
+        """
+        with open(file_path) as file:
+            data = yaml.safe_load(file)
+        return Checkpoint(**data)

virtualship/expedition/do_expedition.py

@@ -0,0 +1,150 @@
+"""do_expedition function."""
+
+import os
+import shutil
+from pathlib import Path
+
+import pyproj
+
+from .checkpoint import Checkpoint
+from .expedition_cost import expedition_cost
+from .input_data import InputData
+from .schedule import Schedule
+from .ship_config import ShipConfig
+from .simulate_measurements import simulate_measurements
+from .simulate_schedule import ScheduleProblem, simulate_schedule
+from .verify_schedule import verify_schedule
+
+
+def do_expedition(expedition_dir: str | Path) -> None:
+    """
+    Perform an expedition, providing terminal feedback and file output.
+
+    :param expedition_dir: The base directory for the expedition.
+    """
+    if isinstance(expedition_dir, str):
+        expedition_dir = Path(expedition_dir)
+
+    # load ship configuration
+    ship_config = _get_ship_config(expedition_dir)
+    if ship_config is None:
+        return
+
+    # load schedule
+    schedule = _get_schedule(expedition_dir)
+    if schedule is None:
+        return
+
+    # load last checkpoint
+    checkpoint = _load_checkpoint(expedition_dir)
+    if checkpoint is None:
+        checkpoint = Checkpoint(past_schedule=Schedule(waypoints=[]))
+
+    # verify that schedule and checkpoint match
+    if (
+        not schedule.waypoints[: len(checkpoint.past_schedule.waypoints)]
+        == checkpoint.past_schedule.waypoints
+    ):
+        print(
+            "Past waypoints in schedule have been changed! Restore past schedule and only change future waypoints."
+        )
+        return
+
+    # projection used to sail between waypoints
+    projection = pyproj.Geod(ellps="WGS84")
+
+    # load fieldsets
+    input_data = _load_input_data(
+        expedition_dir=expedition_dir, ship_config=ship_config
+    )
+
+    # verify schedule makes sense
+    verify_schedule(projection, ship_config, schedule, input_data)
+
+    # simulate the schedule
+    schedule_results = simulate_schedule(
+        projection=projection, ship_config=ship_config, schedule=schedule
+    )
+    if isinstance(schedule_results, ScheduleProblem):
+        print(
+            "Update your schedule and continue the expedition by running the tool again."
+        )
+        _save_checkpoint(
+            Checkpoint(
+                past_schedule=Schedule(
+                    waypoints=schedule.waypoints[: schedule_results.failed_waypoint_i]
+                )
+            ),
+            expedition_dir,
+        )
+        return
+
+    # delete and create results directory
+    if os.path.exists(expedition_dir.joinpath("results")):
+        shutil.rmtree(expedition_dir.joinpath("results"))
+    os.makedirs(expedition_dir.joinpath("results"))
+
+    # calculate expedition cost in US$
+    assert (
+        schedule.waypoints[0].time is not None
+    ), "First waypoint has no time. This should not be possible as it should have been verified before."
+    time_past = schedule_results.time - schedule.waypoints[0].time
+    cost = expedition_cost(schedule_results, time_past)
+    with open(expedition_dir.joinpath("results", "cost.txt"), "w") as file:
+        file.writelines(f"cost: {cost} US$")
+    print(f"This expedition took {time_past} and would have cost {cost:,.0f} US$.")
+
+    # simulate measurements
+    print("Simulating measurements. This may take a while..")
+    simulate_measurements(
+        expedition_dir,
+        ship_config,
+        input_data,
+        schedule_results.measurements_to_simulate,
+    )
+    print("Done simulating measurements.")
+
+    print("Your expedition has concluded successfully!")
+    print("Your measurements can be found in the results directory.")
+
+
+def _get_ship_config(expedition_dir: Path) -> ShipConfig | None:
+    file_path = expedition_dir.joinpath("ship_config.yaml")
+    try:
+        return ShipConfig.from_yaml(file_path)
+    except FileNotFoundError:
+        print(f'Schedule not found. Save it to "{file_path}".')
+        return None
+
+
+def _load_input_data(expedition_dir: Path, ship_config: ShipConfig) -> InputData:
+    return InputData.load(
+        directory=expedition_dir.joinpath("input_data"),
+        load_adcp=ship_config.adcp_config is not None,
+        load_argo_float=ship_config.argo_float_config is not None,
+        load_ctd=ship_config.ctd_config is not None,
+        load_drifter=ship_config.drifter_config is not None,
+        load_ship_underwater_st=ship_config.ship_underwater_st_config is not None,
+    )
+
+
+def _get_schedule(expedition_dir: Path) -> Schedule | None:
+    file_path = expedition_dir.joinpath("schedule.yaml")
+    try:
+        return Schedule.from_yaml(file_path)
+    except FileNotFoundError:
+        print(f'Schedule not found. Save it to "{file_path}".')
+        return None
+
+
+def _load_checkpoint(expedition_dir: Path) -> Checkpoint | None:
+    file_path = expedition_dir.joinpath("checkpoint.yaml")
+    try:
+        return Checkpoint.from_yaml(file_path)
+    except FileNotFoundError:
+        return None
+
+
+def _save_checkpoint(checkpoint: Checkpoint, expedition_dir: Path) -> None:
+    file_path = expedition_dir.joinpath("checkpoint.yaml")
+    checkpoint.to_yaml(file_path)

virtualship/expedition/expedition_cost.py

@@ -0,0 +1,27 @@
+"""expedition_cost function."""
+
+from datetime import timedelta
+
+from .simulate_schedule import ScheduleOk
+
+
+def expedition_cost(schedule_results: ScheduleOk, time_past: timedelta) -> float:
+    """
+    Calculate the cost of the expedition in US$.
+
+    :param schedule_results: Results from schedule simulation.
+    :param time_past: Time the expedition took.
+    :returns: The calculated cost of the expedition in US$.
+    """
+    SHIP_COST_PER_DAY = 30000
+    DRIFTER_DEPLOY_COST = 2500
+    ARGO_DEPLOY_COST = 15000
+
+    ship_cost = SHIP_COST_PER_DAY / 24 * time_past.total_seconds() // 3600
+    num_argos = len(schedule_results.measurements_to_simulate.argo_floats)
+    argo_cost = num_argos * ARGO_DEPLOY_COST
+    num_drifters = len(schedule_results.measurements_to_simulate.drifters)
+    drifter_cost = num_drifters * DRIFTER_DEPLOY_COST
+
+    cost = ship_cost + argo_cost + drifter_cost
+    return cost

virtualship/expedition/input_data.py

@@ -0,0 +1,177 @@
+"""InputData class."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from parcels import Field, FieldSet
+
+
+@dataclass
+class InputData:
+    """A collection of fieldsets that function as input data for simulation."""
+
+    adcp_fieldset: FieldSet | None
+    argo_float_fieldset: FieldSet | None
+    ctd_fieldset: FieldSet | None
+    drifter_fieldset: FieldSet | None
+    ship_underwater_st_fieldset: FieldSet | None
+
+    @classmethod
+    def load(
+        cls,
+        directory: str | Path,
+        load_adcp: bool,
+        load_argo_float: bool,
+        load_ctd: bool,
+        load_drifter: bool,
+        load_ship_underwater_st: bool,
+    ) -> InputData:
+        """
+        Create an instance of this class from netCDF files.
+
+        For now this function makes a lot of assumption about file location and contents.
+
+        :param directory: Base directory of the expedition.
+        :param load_adcp: Whether to load the ADCP fieldset.
+        :param load_argo_float: Whether to load the argo float fieldset.
+        :param load_ctd: Whether to load the CTD fieldset.
+        :param load_drifter: Whether to load the drifter fieldset.
+        :param load_ship_underwater_st: Whether to load the ship underwater ST fieldset.
+        :returns: An instance of this class with loaded fieldsets.
+        """
+        if load_drifter:
+            drifter_fieldset = cls._load_drifter_fieldset(directory)
+        else:
+            drifter_fieldset = None
+        if load_argo_float:
+            argo_float_fieldset = cls._load_argo_float_fieldset(directory)
+        else:
+            argo_float_fieldset = None
+        if load_adcp or load_ctd or load_ship_underwater_st:
+            default_fieldset = cls._load_default_fieldset(directory)
+        if load_adcp:
+            adcp_fieldset = default_fieldset
+        else:
+            adcp_fieldset = None
+        if load_ctd:
+            ctd_fieldset = default_fieldset
+        else:
+            ctd_fieldset = None
+        if load_ship_underwater_st:
+            ship_underwater_st_fieldset = default_fieldset
+        else:
+            ship_underwater_st_fieldset = None
+
+        return InputData(
+            adcp_fieldset=adcp_fieldset,
+            argo_float_fieldset=argo_float_fieldset,
+            ctd_fieldset=ctd_fieldset,
+            drifter_fieldset=drifter_fieldset,
+            ship_underwater_st_fieldset=ship_underwater_st_fieldset,
+        )
+
+    @classmethod
+    def _load_default_fieldset(cls, directory: str | Path) -> FieldSet:
+        filenames = {
+            "U": directory.joinpath("default_uv.nc"),
+            "V": directory.joinpath("default_uv.nc"),
+            "S": directory.joinpath("default_s.nc"),
+            "T": directory.joinpath("default_t.nc"),
+        }
+        variables = {"U": "uo", "V": "vo", "S": "so", "T": "thetao"}
+        dimensions = {
+            "lon": "longitude",
+            "lat": "latitude",
+            "time": "time",
+            "depth": "depth",
+        }
+
+        # create the fieldset and set interpolation methods
+        fieldset = FieldSet.from_netcdf(
+            filenames, variables, dimensions, allow_time_extrapolation=True
+        )
+        fieldset.T.interp_method = "linear_invdist_land_tracer"
+        fieldset.S.interp_method = "linear_invdist_land_tracer"
+
+        # make depth negative
+        for g in fieldset.gridset.grids:
+            g.depth = -g.depth
+
+        # add bathymetry data
+        bathymetry_file = directory.joinpath("bathymetry.nc")
+        bathymetry_variables = ("bathymetry", "deptho")
+        bathymetry_dimensions = {"lon": "longitude", "lat": "latitude"}
+        bathymetry_field = Field.from_netcdf(
+            bathymetry_file, bathymetry_variables, bathymetry_dimensions
+        )
+        # make depth negative
+        bathymetry_field.data = -bathymetry_field.data
+        fieldset.add_field(bathymetry_field)
+
+        # read in data already
+        fieldset.computeTimeChunk(0, 1)
+
+        return fieldset
+
+    @classmethod
+    def _load_drifter_fieldset(cls, directory: str | Path) -> FieldSet:
+        filenames = {
+            "U": directory.joinpath("drifter_uv.nc"),
+            "V": directory.joinpath("drifter_uv.nc"),
+            "T": directory.joinpath("drifter_t.nc"),
+        }
+        variables = {"U": "uo", "V": "vo", "T": "thetao"}
+        dimensions = {
+            "lon": "longitude",
+            "lat": "latitude",
+            "time": "time",
+            "depth": "depth",
+        }
+
+        fieldset = FieldSet.from_netcdf(
+            filenames, variables, dimensions, allow_time_extrapolation=False
+        )
+        fieldset.T.interp_method = "linear_invdist_land_tracer"
+
+        # make depth negative
+        for g in fieldset.gridset.grids:
+            g.depth = -g.depth
+
+        # read in data already
+        fieldset.computeTimeChunk(0, 1)
+
+        return fieldset
+
+    @classmethod
+    def _load_argo_float_fieldset(cls, directory: str | Path) -> FieldSet:
+        filenames = {
+            "U": directory.joinpath("argo_float_uv.nc"),
+            "V": directory.joinpath("argo_float_uv.nc"),
+            "S": directory.joinpath("argo_float_s.nc"),
+            "T": directory.joinpath("argo_float_t.nc"),
+        }
+        variables = {"U": "uo", "V": "vo", "S": "so", "T": "thetao"}
+        dimensions = {
+            "lon": "longitude",
+            "lat": "latitude",
+            "time": "time",
+            "depth": "depth",
+        }
+
+        fieldset = FieldSet.from_netcdf(
+            filenames, variables, dimensions, allow_time_extrapolation=False
+        )
+        fieldset.T.interp_method = "linear_invdist_land_tracer"
+        fieldset.S.interp_method = "linear_invdist_land_tracer"
+
+        # make depth negative
+        for g in fieldset.gridset.grids:
+            if max(g.depth) > 0:
+                g.depth = -g.depth
+
+        # read in data already
+        fieldset.computeTimeChunk(0, 1)
+
+        return fieldset

virtualship/expedition/instrument_type.py

@@ -0,0 +1,11 @@
+"""InstrumentType Enum."""
+
+from enum import Enum
+
+
+class InstrumentType(Enum):
+    """Types of instruments."""
+
+    CTD = "CTD"
+    DRIFTER = "DRIFTER"
+    ARGO_FLOAT = "ARGO_FLOAT"

virtualship/expedition/schedule.py

@@ -0,0 +1,44 @@
+"""Schedule class."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pydantic
+import yaml
+
+from .waypoint import Waypoint
+
+
+class Schedule(pydantic.BaseModel):
+    """Schedule of the virtual ship."""
+
+    waypoints: list[Waypoint]
+
+    model_config = pydantic.ConfigDict(extra="forbid")
+
+    def to_yaml(self, file_path: str | Path) -> None:
+        """
+        Write schedule to yaml file.
+
+        :param file_path: Path to the file to write to.
+        """
+        with open(file_path, "w") as file:
+            yaml.dump(
+                self.model_dump(
+                    by_alias=True,
+                ),
+                file,
+            )
+
+    @classmethod
+    def from_yaml(cls, file_path: str | Path) -> Schedule:
+        """
+        Load schedule from yaml file.
+
+        :param file_path: Path to the file to load from.
+        :returns: The schedule.
+        """
+        with open(file_path) as file:
+            data = yaml.safe_load(file)
+        return Schedule(**data)