virtualship.expedition package#

Everything for simulating an expedition.

Bases: object

A collection of fieldsets that function as input data for simulation.

adcp_fieldset: FieldSet | None#

argo_float_fieldset: FieldSet | None#

ctd_bgc_fieldset: FieldSet | None#

ctd_fieldset: FieldSet | None#

drifter_fieldset: FieldSet | None#

classmethod load(directory: str | Path, load_adcp: bool, load_argo_float: bool, load_ctd: bool, load_ctd_bgc: bool, load_drifter: bool, load_xbt: 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.

Parameters:

directory – Input data directory.
load_adcp – Whether to load the ADCP fieldset.
load_argo_float – Whether to load the argo float fieldset.
load_ctd – Whether to load the CTD fieldset.
load_ctd_bgc – Whether to load the CTD BGC fieldset.
load_drifter – Whether to load the drifter fieldset.
load_ship_underwater_st – Whether to load the ship underwater ST fieldset.

Returns:

An instance of this class with loaded fieldsets.

ship_underwater_st_fieldset: FieldSet | None#

xbt_fieldset: FieldSet | None#

virtualship.expedition.do_expedition(expedition_dir: str | Path, input_data: Path | None = None) → None#

Perform an expedition, providing terminal feedback and file output.

Parameters:

expedition_dir – The base directory for the expedition.
input_data – Input data folder (override used for testing).

Submodules#

virtualship.expedition.checkpoint module#

Checkpoint class.

class virtualship.expedition.checkpoint.Checkpoint(*, past_schedule: Schedule)#

Bases: BaseModel

A checkpoint of schedule simulation.

Copy of the schedule until where the simulation proceeded without troubles.

classmethod from_yaml(file_path: str | Path) → Checkpoint#

Load checkpoint from yaml file.

Parameters:: file_path – Path to the file to load from.
Returns:: The checkpoint.

model_config: ClassVar[ConfigDict] = {}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

past_schedule: Schedule#

to_yaml(file_path: str | Path) → None#

Write checkpoint to yaml file.

Parameters:: file_path – Path to the file to write to.

verify(schedule: Schedule) → None#

Verify that the given schedule matches the checkpoint’s past schedule.

This method checks if the waypoints in the given schedule match the waypoints in the checkpoint’s past schedule up to the length of the past schedule. If there’s a mismatch, it raises a CheckpointError.

Parameters:: schedule (Schedule) – The schedule to verify against the checkpoint.
Raises:: CheckpointError – If the past waypoints in the given schedule have been changed compared to the checkpoint.
Returns:: None

virtualship.expedition.do_expedition module#

do_expedition function.

virtualship.expedition.do_expedition.do_expedition(expedition_dir: str | Path, input_data: Path | None = None) → None#

Perform an expedition, providing terminal feedback and file output.

Parameters:

expedition_dir – The base directory for the expedition.
input_data – Input data folder (override used for testing).

virtualship.expedition.expedition_cost module#

expedition_cost function.

virtualship.expedition.expedition_cost.expedition_cost(schedule_results: ScheduleOk, time_past: timedelta) → float#

Calculate the cost of the expedition in US$.

Parameters:

schedule_results – Results from schedule simulation.
time_past – Time the expedition took.

Returns:

The calculated cost of the expedition in US$.

virtualship.expedition.input_data module#

InputData class.

Bases: object

A collection of fieldsets that function as input data for simulation.

adcp_fieldset: FieldSet | None#

argo_float_fieldset: FieldSet | None#

ctd_bgc_fieldset: FieldSet | None#

ctd_fieldset: FieldSet | None#

drifter_fieldset: FieldSet | None#

Create an instance of this class from netCDF files.

For now this function makes a lot of assumption about file location and contents.

Parameters:

directory – Input data directory.
load_adcp – Whether to load the ADCP fieldset.
load_argo_float – Whether to load the argo float fieldset.
load_ctd – Whether to load the CTD fieldset.
load_ctd_bgc – Whether to load the CTD BGC fieldset.
load_drifter – Whether to load the drifter fieldset.
load_ship_underwater_st – Whether to load the ship underwater ST fieldset.

Returns:

An instance of this class with loaded fieldsets.

ship_underwater_st_fieldset: FieldSet | None#

xbt_fieldset: FieldSet | None#

virtualship.expedition.simulate_measurements module#

simulate_measurements function.

virtualship.expedition.simulate_measurements.simulate_measurements(expedition_dir: str | Path, ship_config: ShipConfig, input_data: InputData, measurements: MeasurementsToSimulate) → None#

Simulate measurements using Parcels.

Saves everything in expedition_dir/results.

Parameters:

expedition_dir – Base directory of the expedition.
ship_config – Ship configuration.
input_data – Input data for simulation.
measurements – The measurements to simulate.

Raises:

RuntimeError – In case fieldsets of configuration is not provided. Make sure to check this before calling this function.

virtualship.expedition.simulate_schedule module#

simulate_schedule function and supporting classes.

class virtualship.expedition.simulate_schedule.MeasurementsToSimulate#

Bases: object

The measurements to simulate, as concluded from schedule simulation.

adcps: list[Spacetime]#

argo_floats: list[ArgoFloat]#

ctd_bgcs: list[CTD_BGC]#

ctds: list[CTD]#

drifters: list[Drifter]#

ship_underwater_sts: list[Spacetime]#

xbts: list[XBT]#

class virtualship.expedition.simulate_schedule.ScheduleOk(time: datetime, measurements_to_simulate: MeasurementsToSimulate)#

Bases: object

Result of schedule that could be completed.

measurements_to_simulate: MeasurementsToSimulate#

time: datetime#

class virtualship.expedition.simulate_schedule.ScheduleProblem(time: datetime, failed_waypoint_i: int)#

Bases: object

Result of schedule that could not be fully completed.

failed_waypoint_i: int#

time: datetime#

virtualship.expedition.simulate_schedule.simulate_schedule(projection: Geod, ship_config: ShipConfig, schedule: Schedule) → ScheduleOk | ScheduleProblem#

Simulate a schedule.

Parameters:

projection – The projection to use for sailing.
ship_config – Ship configuration.
schedule – The schedule to simulate.

Returns:

Either the results of a successfully simulated schedule, or information on where the schedule became infeasible.