5. Model usage
Once the model is operational, it's time to put it to use.
Querying the model
Queries to the model happen through the Model Prediction endpoint. The accepted parameters and their units can be found in the reference.
A small example of a prediction query for relatively calm weather conditions for a SOG of 13 knots is shown below. See the "The Basics" interactive tutorial for more detailed instructions.
imo_number = 9999999
API_KEY = "your-api-key"
url = f"https://api.toqua.ai/ships/{imo_number}/models/latest/predict"
headers = {
"accept": "application/json",
"content-type": "application/json",
"X-API-Key": API_KEY,
}
api_input = {
"data": {
"sog": [13],
"wave_direction": [180],
"wave_height": [2],
"wind_direction": [90],
"wind_speed": [6],
"current_direction": [0],
"current_speed": [0.5],
"draft_avg": [20],
"trim": [-1],
"fuel_specific_energy": [41.5]
}
}
response = requests.post(url, json=api_input, headers=headers)
{
"sog": [
13.0
],
"stw": [
13.97192
],
"me_rpm": [
44.913151911934605
],
"me_power": [
11051.700231111769
],
"me_fo_consumption": [
46.458430017045956
],
"me_fo_emission": [
147.29645236904418
]
}
Input and output parameters
Depending on the quality and availability of the data, inputs and outputs between models can differ. The Metadata endpoint provides information about which inputs the model requires, and which outputs it produces. This information can be found under the parameters field.
For example, the snippet below shows a model that can take as input SOG, STW, RPM, Power and Fuel Consumption, and also produce these as output. Fuel Emissions can only be produced by the model as output. Next, we see that trim is not supported by the model. All other variables can be given only as input.
{
"updated_at": "2024-01-11T09:23:43+00:00",
"periods": [],
"parameters": {
"sog": {
"input": true,
"output": true,
"min": 7.0,
"max": 16.0,
"default": 12.0
},
"stw": {
"input": true,
"output": true,
"min": 7.0,
"max": 16.0,
"default": 12.0
},
"me_rpm": {
"input": true,
"output": true,
"min": 0.0,
"max": 100.0,
"default": 60.0
},
"me_power": {
"input": true,
"output": true,
"min": 0.0,
"max": 22000.0,
"default": 10000.0
},
"me_fo_consumption": {
"input": true,
"output": true,
"min": 0.0,
"max": 100.0,
"default": 50.0
},
"me_fo_emission": {
"input": false,
"output": true,
"min": null,
"max": null,
"default": 0.0
},
"draft_avg": {
"input": true,
"output": false,
"min": 6.0,
"max": 19.0,
"default": 19.0
},
"trim": {
"input": false,
"output": false,
"min": -1.0,
"max": 1.0,
"default": -1.0
},
"fuel_specific_energy": {
"input": true,
"output": false,
"min": 40.0,
"max": 42.7,
"default": 40.5
},
"ship_heading": {
"input": true,
"output": false,
"min": 0.0,
"max": 360.0,
"default": 0.0
},
"wave_direction": {
"input": true,
"output": false,
"min": 0.0,
"max": 360.0,
"default": 0.0
},
"wave_height": {
"input": true,
"output": false,
"min": 0.0,
"max": 7.0,
"default": 1.0
},
"current_speed": {
"input": true,
"output": false,
"min": 0.0,
"max": 2.0,
"default": 0.0
},
"current_direction": {
"input": true,
"output": false,
"min": 0.0,
"max": 360.0,
"default": 0.0
},
"wind_direction": {
"input": true,
"output": false,
"min": 0.0,
"max": 360.0,
"default": 0.0
},
"wind_speed": {
"input": true,
"output": false,
"min": 0.0,
"max": 20.0,
"default": 4.0
},
"sea_surface_temperature": {
"input": true,
"output": false,
"min": 0.0,
"max": 35.0,
"default": 16.0
},
"sea_surface_salinity": {
"input": true,
"output": false,
"min": 30.0,
"max": 40.0,
"default": 35.0
}
}
}
Note that min/max/default values are also provided for each of the parameters. They represent typical values the model has seen during training, but they are not enforced in any way.
Model limitations
Model operational limits are determined by the physical limitations of the vessel. E.g. the Max RPM and 90% MCR can never be exceeded. Exceeding these will result in errors being produced when predicting.
As an example, consider the first tab in the snippet below. It shows the output of a model when trying to predict for a Main Engine Power value that is outside of the 90% MCR range. Note how all values have been set to null on that index. The input is shown in the second tab.
{
"sog": [
null
],
"stw": [
null
],
"me_rpm": [
null
],
"me_power": [
null
],
"me_fo_consumption": [
null
],
"me_fo_emission": [
null
],
"errors": [
{
"error_code": "max_mcr_limit_exceeded",
"description": "90% Maximum MCR (19710 kW) exceeded.",
"indices": [
0
]
},
{
"error_code": "max_rpm_limit_exceeded",
"description": "Maximum RPM (60.0 RPM) exceeded.",
"indices": [
0
]
}
]
}
{
"date": "2022-10-14T23:28:39.518Z",
"data": {
"sea_surface_salinity": [
35
],
"sea_surface_temperature": [
16
],
"current_speed": [
0
],
"current_direction": [
0
],
"wave_height": [
1.2
],
"wave_direction": [
45
],
"wind_speed": [
5.5
],
"wind_direction": [
45
],
"trim": [
-1
],
"ship_heading": [
0
],
"draft_avg": [
19
],
"fuel_specific_energy": [
41.6
],
"me_power": [
"20000"
]
}
}
Historical predictions
As new data arrives, the model will be retrained automatically to reflect the latest data. It's also possible to "go back in time" and query the model historically by providing it with a date. This functionality allows keeping track of the performance of the ship over time.
The date may be provided as optional date parameter in the model input. All dates during a data period can be provided. These can be found in the periods field in the Model Metadata (see Model monitoring). When no date is provided, the date of the latest period is used.
See the input example below where 2023-01-01 is provided as date.
{
"date": "2023-01-01T00:00:00+00:00",
"data": {
"sog": [
13
],
"wave_direction": [
180
],
"wave_height": [
2
],
"wind_direction": [
90
],
"wind_speed": [
6
],
"current_direction": [
0
],
"current_speed": [
0.5
],
"draft_avg": [
20
],
"trim": [
-1
],
"fuel_specific_energy": [
41.5
]
}
}
Correcting a model
When an event takes place that alters the performance of the vessel, like when it gets cleaned or an ESD is installed, the Toqua Ship Kernel might not reflect the new vessel condition immediately. This could be because the data has not been uploaded yet or there's not enough data yet for the Ship Kernel to be sufficiently confident of the observed performance change.
The corrections currently applied to a model can be found through the Model Metadata endpoint. See the Event Correction tutorial for detailed instructions of this functionality.
What should I use these models for?
Let your imagination run wild!
Ship Kernels are designed as flexible building blocks so they can be used in many different ways.
These 'performance models' lie at the heart of almost every single simulation, visualization, optimization, etc. in shipping, so the possibilities are endless!
Some typical cases include:
- As speed-fuel description for commercial purposes
- As a base model to improve voyage optimization
- Assessing hull performance over time
- To manage data quality
- To validate savings of retrofits
For more inspiration, check out our customer case with Vroon, including a long-list of cases for Ship Kernels.
Further Reading
In the section Tutorials we provide some more extensive code examples of how to use the models for specific cases:
-The Basics tutorial: Shows the basics of using a Toqua Ship Kernel to make predictions
-Speed-Fuel Curve tutorial: Shows how to create a speed-fuel consumption curve in any custom condition.
-Grid Creation tutorial: Shows how to create a local lower-dimensional "copy" of a Toqua Ship Kernel. Can be used for routing when very high throughput with low latency is required.
Updated 24 days ago