virtualship.expedition package¶

Everything for simulating an expedition.

class virtualship.expedition.ADCPConfig(**data)¶

Bases: BaseModel

Configuration for ADCP instrument.

Parameters:: data (Any)

max_depth_meter: float¶

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

num_bins: int¶

period: timedelta¶

class virtualship.expedition.ArgoFloatConfig(**data)¶

Bases: BaseModel

Configuration for argos floats.

Parameters:: data (Any)

cycle_days: float¶

drift_days: float¶

drift_depth_meter: float¶

max_depth_meter: float¶

min_depth_meter: float¶

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

vertical_speed_meter_per_second: float¶

class virtualship.expedition.CTDConfig(**data)¶

Bases: BaseModel

Configuration for CTD instrument.

Parameters:: data (Any)

max_depth_meter: float¶

min_depth_meter: float¶

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

stationkeeping_time: timedelta¶

class virtualship.expedition.DrifterConfig(**data)¶

Bases: BaseModel

Configuration for drifters.

Parameters:: data (Any)

depth_meter: float¶

lifetime: timedelta¶

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

class virtualship.expedition.InstrumentType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Types of instruments.

ARGO_FLOAT = 'ARGO_FLOAT'¶

CTD = 'CTD'¶

DRIFTER = 'DRIFTER'¶

class virtualship.expedition.Schedule(**data)¶

Bases: BaseModel

Schedule of the virtual ship.

Parameters:: data (Any)

classmethod from_yaml(file_path)¶

Load schedule from yaml file.

Parameters:: file_path (str | Path) – Path to the file to load from.
Return type:: Schedule
Returns:: The schedule.

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

to_yaml(file_path)¶

Write schedule to yaml file.

Parameters:: file_path (str | Path) – Path to the file to write to.
Return type:: None

waypoints: list[Waypoint]¶

class virtualship.expedition.ShipConfig(**data)¶

Bases: BaseModel

Configuration of the virtual ship.

Parameters:: data (Any)

adcp_config: ADCPConfig | None¶

ADCP configuration.

If None, no ADCP measurements will be performed.

argo_float_config: ArgoFloatConfig | None¶

Argo float configuration.

If None, no argo floats can be deployed.

ctd_config: CTDConfig | None¶

CTD configuration.

If None, no CTDs can be cast.

drifter_config: DrifterConfig | None¶

Drifter configuration.

If None, no drifters can be deployed.

classmethod from_yaml(file_path)¶

Load config from yaml file.

Parameters:: file_path (str | Path) – Path to the file to load from.
Return type:: ShipConfig
Returns:: The config.

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

ship_speed_meter_per_second: float¶: Velocity of the ship in meters per second.

ship_underwater_st_config: ShipUnderwaterSTConfig | None¶

Ship underwater salinity temperature measurementconfiguration.

If None, no ST measurements will be performed.

to_yaml(file_path)¶

Write config to yaml file.

Parameters:: file_path (str | Path) – Path to the file to write to.
Return type:: None

class virtualship.expedition.ShipUnderwaterSTConfig(**data)¶

Bases: BaseModel

Configuration for underwater ST.

Parameters:: data (Any)

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

period: timedelta¶

class virtualship.expedition.Waypoint(location, time=None, instrument=None)¶

Bases: object

A Waypoint to sail to with an optional time and an optional instrument.

Parameters:

location (Location)
time (datetime | None)
instrument (InstrumentType | list[InstrumentType] | None)

instrument: InstrumentType | list[InstrumentType] | None = None¶

location: Location¶

time: datetime | None = None¶

virtualship.expedition.do_expedition(expedition_dir)¶

Perform an expedition, providing terminal feedback and file output.

Parameters:: expedition_dir (str | Path) – The base directory for the expedition.
Return type:: None

Submodules¶

virtualship.expedition.checkpoint module¶

Checkpoint class.

class virtualship.expedition.checkpoint.Checkpoint(**data)¶

Bases: BaseModel

A checkpoint of schedule simulation.

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

Parameters:: data (Any)

classmethod from_yaml(file_path)¶

Load checkpoint from yaml file.

Parameters:: file_path (str | Path) – Path to the file to load from.
Return type:: Checkpoint
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)¶

Write checkpoint to yaml file.

Parameters:: file_path (str | Path) – Path to the file to write to.
Return type:: None

virtualship.expedition.do_expedition module¶

do_expedition function.

virtualship.expedition.do_expedition.do_expedition(expedition_dir)¶

Perform an expedition, providing terminal feedback and file output.

Parameters:: expedition_dir (str | Path) – The base directory for the expedition.
Return type:: None

virtualship.expedition.expedition_cost module¶

expedition_cost function.

virtualship.expedition.expedition_cost.expedition_cost(schedule_results, time_past)¶

Calculate the cost of the expedition in US$.

Parameters:

schedule_results (ScheduleOk) – Results from schedule simulation.
time_past (timedelta) – Time the expedition took.

Return type:

float

Returns:

The calculated cost of the expedition in US$.

virtualship.expedition.input_data module¶

InputData class.

class virtualship.expedition.input_data.InputData(adcp_fieldset, argo_float_fieldset, ctd_fieldset, drifter_fieldset, ship_underwater_st_fieldset)¶

Bases: object

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

Parameters:

adcp_fieldset (FieldSet | None)
argo_float_fieldset (FieldSet | None)
ctd_fieldset (FieldSet | None)
drifter_fieldset (FieldSet | None)
ship_underwater_st_fieldset (FieldSet | None)

adcp_fieldset: FieldSet | None¶

argo_float_fieldset: FieldSet | None¶

ctd_fieldset: FieldSet | None¶

drifter_fieldset: FieldSet | None¶

classmethod load(directory, load_adcp, load_argo_float, load_ctd, load_drifter, load_ship_underwater_st)¶

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 (str | Path) – Base directory of the expedition.
load_adcp (bool) – Whether to load the ADCP fieldset.
load_argo_float (bool) – Whether to load the argo float fieldset.
load_ctd (bool) – Whether to load the CTD fieldset.
load_drifter (bool) – Whether to load the drifter fieldset.
load_ship_underwater_st (bool) – Whether to load the ship underwater ST fieldset.

Return type:

InputData

Returns:

An instance of this class with loaded fieldsets.

ship_underwater_st_fieldset: FieldSet | None¶

virtualship.expedition.instrument_type module¶

InstrumentType Enum.

class virtualship.expedition.instrument_type.InstrumentType(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)¶

Bases: Enum

Types of instruments.

ARGO_FLOAT = 'ARGO_FLOAT'¶

CTD = 'CTD'¶

DRIFTER = 'DRIFTER'¶

virtualship.expedition.schedule module¶

Schedule class.

class virtualship.expedition.schedule.Schedule(**data)¶

Bases: BaseModel

Schedule of the virtual ship.

Parameters:: data (Any)

classmethod from_yaml(file_path)¶

Load schedule from yaml file.

Parameters:: file_path (str | Path) – Path to the file to load from.
Return type:: Schedule
Returns:: The schedule.

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

to_yaml(file_path)¶

Write schedule to yaml file.

Parameters:: file_path (str | Path) – Path to the file to write to.
Return type:: None

waypoints: list[Waypoint]¶

virtualship.expedition.ship_config module¶

ShipConfig and supporting classes.

class virtualship.expedition.ship_config.ADCPConfig(**data)¶

Bases: BaseModel

Configuration for ADCP instrument.

Parameters:: data (Any)

max_depth_meter: float¶

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

num_bins: int¶

period: timedelta¶

class virtualship.expedition.ship_config.ArgoFloatConfig(**data)¶

Bases: BaseModel

Configuration for argos floats.

Parameters:: data (Any)

cycle_days: float¶

drift_days: float¶

drift_depth_meter: float¶

max_depth_meter: float¶

min_depth_meter: float¶

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

vertical_speed_meter_per_second: float¶

class virtualship.expedition.ship_config.CTDConfig(**data)¶

Bases: BaseModel

Configuration for CTD instrument.

Parameters:: data (Any)

max_depth_meter: float¶

min_depth_meter: float¶

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

stationkeeping_time: timedelta¶

class virtualship.expedition.ship_config.DrifterConfig(**data)¶

Bases: BaseModel

Configuration for drifters.

Parameters:: data (Any)

depth_meter: float¶

lifetime: timedelta¶

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

class virtualship.expedition.ship_config.ShipConfig(**data)¶

Bases: BaseModel

Configuration of the virtual ship.

Parameters:: data (Any)

adcp_config: ADCPConfig | None¶

ADCP configuration.

If None, no ADCP measurements will be performed.

argo_float_config: ArgoFloatConfig | None¶

Argo float configuration.

If None, no argo floats can be deployed.

ctd_config: CTDConfig | None¶

CTD configuration.

If None, no CTDs can be cast.

drifter_config: DrifterConfig | None¶

Drifter configuration.

If None, no drifters can be deployed.

classmethod from_yaml(file_path)¶

Load config from yaml file.

Parameters:: file_path (str | Path) – Path to the file to load from.
Return type:: ShipConfig
Returns:: The config.

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

ship_speed_meter_per_second: float¶: Velocity of the ship in meters per second.

ship_underwater_st_config: ShipUnderwaterSTConfig | None¶

Ship underwater salinity temperature measurementconfiguration.

If None, no ST measurements will be performed.

to_yaml(file_path)¶

Write config to yaml file.

Parameters:: file_path (str | Path) – Path to the file to write to.
Return type:: None

class virtualship.expedition.ship_config.ShipUnderwaterSTConfig(**data)¶

Bases: BaseModel

Configuration for underwater ST.

Parameters:: data (Any)

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

period: timedelta¶

virtualship.expedition.simulate_measurements module¶

simulate_measurements function.

virtualship.expedition.simulate_measurements.simulate_measurements(expedition_dir, ship_config, input_data, measurements)¶

Simulate measurements using Parcels.

Saves everything in expedition_dir/results.

Parameters:

expedition_dir (str | Path) – Base directory of the expedition.
ship_config (ShipConfig) – Ship configuration.
input_data (InputData) – Input data for simulation.
measurements (MeasurementsToSimulate) – The measurements to simulate.

Raises:

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

Return type:

None

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]¶

ctds: list[CTD]¶

drifters: list[Drifter]¶

ship_underwater_sts: list[Spacetime]¶

class virtualship.expedition.simulate_schedule.ScheduleOk(time, measurements_to_simulate)¶

Bases: object

Result of schedule that could be completed.

Parameters:

time (datetime)
measurements_to_simulate (MeasurementsToSimulate)

measurements_to_simulate: MeasurementsToSimulate¶

time: datetime¶

class virtualship.expedition.simulate_schedule.ScheduleProblem(time, failed_waypoint_i)¶

Bases: object

Result of schedule that could not be fully completed.

Parameters:

time (datetime)
failed_waypoint_i (int)

failed_waypoint_i: int¶

time: datetime¶

virtualship.expedition.simulate_schedule.simulate_schedule(projection, ship_config, schedule)¶

Simulate a schedule.

Parameters:

projection (Geod) – The projection to use for sailing.
ship_config (ShipConfig) – Ship configuration.
schedule (Schedule) – The schedule to simulate.

Return type:

ScheduleOk | ScheduleProblem

Returns:

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

virtualship.expedition.verify_schedule module¶

verify_schedule function and supporting classes.

exception virtualship.expedition.verify_schedule.PlanningError¶

Bases: RuntimeError

An error in the schedule.

virtualship.expedition.verify_schedule.verify_schedule(projection, ship_config, schedule, input_data)¶

Verify waypoints are ordered by time, first waypoint has a start time, and that schedule is feasible in terms of time if no unexpected events happen.

Parameters:

projection (Geod) – projection used to sail between waypoints.
ship_config (ShipConfig) – The cruise ship_configuration.
schedule (Schedule) – The schedule to verify.
input_data (InputData) – Fieldsets that can be used to check for zero UV condition (is waypoint on land).

Raises:

PlanningError – If waypoints are not feasible or incorrect.
NotImplementedError – If instrument is in schedule that is not implememented.

Return type:

None

virtualship.expedition.waypoint module¶

Waypoint class.

class virtualship.expedition.waypoint.Waypoint(location, time=None, instrument=None)¶

Bases: object

A Waypoint to sail to with an optional time and an optional instrument.

Parameters:

location (Location)
time (datetime | None)
instrument (InstrumentType | list[InstrumentType] | None)

instrument: InstrumentType | list[InstrumentType] | None = None¶

location: Location¶

time: datetime | None = None¶