Methods - Vessel Performance¶
Vessel Overview¶
All of the functionality that relates to the specific vehicle traversing our meshed environment model is contained within the vessel_performance directory.
This directory contains a VesselPerformanceModeller class that initialises one of the vessel classes in vessels and uses this to determine which cells
in a given mesh are inaccessible for that particular vessel and what its performance will be in each of the accessible cells.
The sea ice concentration (a), speed (b) and fuel consumption (c) for the SDA across the Weddell Sea. The latter two quantities are derived from the former.
The vessel performance subsystem
Vessel Performance Modeller¶
Class for modelling the vessel performance. Takes both an environmental mesh and vessel config as input in json format and modifies the input mesh to include vessel specifics.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
env_mesh_json
|
dict
|
a dictionary loaded from an environmental mesh json file |
required |
vessel_config
|
dict
|
a dictionary loaded from a vessel config json file |
required |
custom_vessel
|
class
|
a custom vessel object that specifies a set of performance and accessibility models |
None
|
filter_nans()
¶
Method to check for NaNs in the input cell boxes and zero them if present
get_all_neighbours(cell_id)
¶
Method to get a list of all neighbouring cell ids for a particular cell within the environmental mesh
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cell_id
|
str
|
Cell ID to find the neighbours around |
required |
Returns: neighbours (list): List of IDs of neighbouring cells
model_accessibility()
¶
Method to determine the accessibility of cells in the environmental mesh and remove inaccessible cells from the neighbour graph.
model_performance()
¶
Method to calculate the relevant vessel performance values for each cell in the environmental mesh and update the mesh accordingly.
split_neighbouring_cells(inaccessible_nodes)
¶
Method to split any accessible cells that neighbour inaccessible cells until their sizes match
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
inaccessible_nodes
|
list
|
List of inaccessible nodes to split around |
required |
to_json()
¶
Method to return the modified mesh in json format.
Returns:
| Name | Type | Description |
|---|---|---|
j_mesh |
dict
|
a dictionary representation of the modified mesh. |
options: merge_init_into_class: true members: - model_performance - model_accessibility - to_json
Vessel Factory¶
Factory class to produce initialised vessel objects.
get_vessel(config)
classmethod
¶
Method to return an initialised instance of a vessel class designed for performance modelling
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
config
|
dict
|
a vessel config dictionary |
required |
Returns:
| Name | Type | Description |
|---|---|---|
vessel |
an instance of a vessel class designed for performance modelling |
options: members: - get_vessel
Abstract Vessel¶
Interface to define the abstract methods required for any vessel class to work within the VesselPerformanceModeller.
Initialise the vessel object with parameters from the config.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
vessel parameters from the vessel config file |
required |
model_accessibility(cellbox)
abstractmethod
¶
Determine accessibility of the input cell for the given vessel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
cell in which accessibility is being determined |
required |
Returns:
| Name | Type | Description |
|---|---|---|
access_values |
dict
|
values for the accessibility and other related booleans |
model_performance(cellbox)
abstractmethod
¶
Calculate performance parameters for the given vessel.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
cell in which performance is being modelled |
required |
Returns:
| Name | Type | Description |
|---|---|---|
performance_values |
dict
|
values for relevant performance parameters |
options: merge_init_into_class: true members: - model_performance - model_accessibility
Abstract Ship¶
Bases: AbstractVessel
Abstract class to define the methods and attributes common to any vessel that is a ship
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
vessel parameters from the vessel config file |
required |
extreme_ice(cellbox)
¶
Method to determine if a cell is inaccessible based on configured max ice concentration
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns: ext_ice (bool): boolean that is True if the cell is inaccessible due to ice
extreme_waves(cellbox)
¶
Method to determine if a cell is inaccessible based on configured max wave height. Args: cellbox (AggregatedCellBox): input cell from environmental mesh Returns: ext_wave (bool): boolean that is True if the cell is inaccessible due to waves
invert_resistance(cellbox)
abstractmethod
¶
Method to determine the speed that reduces the resistance force on the ship to an acceptable value
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns: speed (float): Safe vessel speed in km/h
land(cellbox)
¶
Method to determine if a cell is land based on configured minimum depth
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns: land (bool): boolean that is True if the cell is inaccessible due to land
model_accessibility(cellbox)
¶
Method to determine if a given cell is accessible to the ship
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
access_values |
dict
|
boolean values for the modelled accessibility criteria |
model_fuel(cellbox)
abstractmethod
¶
Method to determine the fuel consumption rate of the ship in a given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with fuel consumption values |
model_performance(cellbox)
¶
Method to determine the performance characteristics for the ship
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
performance_values |
dict
|
the value of the modelled performance characteristics for the ship |
model_resistance(cellbox)
abstractmethod
¶
Method to determine the resistance force acting on the ship in a given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with resistance values |
model_speed(cellbox)
abstractmethod
¶
Method to determine the maximum speed that the ship can traverse the given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with speed values |
options: merge_init_into_class: true members: - model_performance - model_accessibility - land - extreme_ice
SDA¶
Bases: AbstractShip
Vessel class with methods specifically designed to model the performance of the British Antarctic Survey research and supply ship, the RRS Sir David Attenborough (SDA)
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
vessel parameters from the vessel config file |
required |
ice_resistance(cellbox)
¶
Method to find the ice resistance force acting on the SDA at a given speed in a given cell
The input cellbox should contain the following values
velocity (float): The speed of the vessel in km/h sic (float): The average sea ice concentration in the cell as a percentage thickness (float): The average ice thickness in the cell in m density (float): The average ice density in the cell in kg/m^3
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
resistance |
float
|
Resistance force in N |
invert_resistance(cellbox)
¶
Method to find the vessel speed that keeps the ice resistance force below a given threshold in a given cell
The input cellbox should contain the following values
sic (float) - The average sea ice concentration in the cell as a percentage
thickness (float) - The average ice thickness in the cell in m
density (float) - The average ice density in the cell in kg/m^3
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
new_speed |
float
|
Safe vessel speed in km/h |
model_fuel(cellbox)
¶
Method to determine the fuel consumption rate of the SDA in a given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with fuel consumption values |
model_resistance(cellbox)
¶
Method to determine the resistance force acting on the SDA in a given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with resistance values |
model_speed(cellbox)
¶
Method to determine the maximum speed that the SDA can traverse the given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with speed values |
wave_resistance(w_height)
¶
Method to calculate the wave resistance given the wave height and vessel geometry. Recommended by the ITTC for small wave heights: https://ittc.info/media/1936/75-04-01-012.pdf
options: merge_init_into_class: true members: - model_speed - model_fuel - model_resistance - invert_resistance
Abstract Glider¶
Bases: AbstractVessel
Abstract class to model the performance of an underwater glider
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
vessel parameters from the vessel config file |
required |
extreme_ice(cellbox)
¶
Method to determine if a cell is inaccessible based on configured max ice concentration
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
ext_ice |
bool
|
boolean that is True if the cell is inaccessible due to ice |
land(cellbox)
¶
Method to determine if a cell is land based on sea level
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns: land (bool): boolean that is True if the cell is inaccessible due to land
model_accessibility(cellbox)
¶
Method to determine if a given cell is accessible to the underwater glider
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns: access_values (dict): boolean values for the modelled accessibility criteria
model_battery(cellbox)
abstractmethod
¶
Method to determine the battery consumption rate of the glider in a given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with battery consumption values |
model_performance(cellbox)
¶
Method to determine the performance characteristics for the underwater glider
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
model_speed(cellbox)
abstractmethod
¶
Method to determine the maximum speed that the glider can traverse the given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with speed values |
shallow(cellbox)
¶
Method to determine if the water in a cell is too shallow for a glider based on configured minimum depth
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns: shallow (bool): boolean that is True if the cell is too shallow for a glider
options: merge_init_into_class: true members: - model_performance - model_accessibility - land - shallow - extreme_ice
Slocum Glider¶
Bases: AbstractGlider
Vessel class with methods specifically designed to model the performance of the Slocum G2 Glider
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
params
|
dict
|
vessel parameters from the vessel config file |
required |
model_battery(cellbox)
¶
Method to determine the rate of battery usage in a given cell in Ah/day
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with battery consumption values |
model_speed(cellbox)
¶
Method to determine the maximum speed that the glider can traverse the given cell
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cellbox
|
AggregatedCellBox
|
input cell from environmental mesh |
required |
Returns:
| Name | Type | Description |
|---|---|---|
cellbox |
AggregatedCellBox
|
updated cell with speed values |
options: merge_init_into_class: true members: - model_speed - model_battery