Configuration

Configuration of the Weather Routing Tool can be done by providing a json file. An example is given by config.example.json.

The configuration file has to be provided when calling the Weather Routing Tool from the command line:

python3 WeatherRoutingTool/cli.py -f <path>/config.json

Additionally, it’s possible to define files for logging (separately for info and warning level) and if debugging mode should be used. Check the help text to get an overview of all CLI arguments:

$ python WeatherRoutingTool/cli.py --help
usage: cli.py [-h] -f FILE [--warnings-log-file WARNINGS_LOG_FILE] [--info-log-file INFO_LOG_FILE] [--debug DEBUG] [--filter-warnings FILTER_WARNINGS]

Weather Routing Tool

options:
  -h, --help            show this help message and exit
  -f FILE, --file FILE  Config file name (absolute path)
  --warnings-log-file WARNINGS_LOG_FILE
                        Logging file name (absolute path) for warnings and above.
  --info-log-file INFO_LOG_FILE
                        Logging file name (absolute path) for info and above.
  --debug DEBUG         Enable debug mode. <True|False>. Defaults to 'False'.
  --filter-warnings FILTER_WARNINGS
                        Filter action. <default|error|ignore|always|module|once>.Defaults to 'default'.

Some variables have to be set using environment variables (see below).

Config file

The following lists contain information on each variable which can be set. The categorisation into required, recommended and optional variables has been chosen such that the requirements of the default settings for the algorithm type (Isofuel algorithm) and the fuel consumption model (Direct Power Method) are met.

Required variables:

Name

Description

DEFAULT_MAP

bbox in which route optimization is performed (lat_min, lon_min, lat_max, lon_max)

DEFAULT_ROUTE

start and end point of the route (lat_start, lon_start, lat_end, lon_end)

DEPARTURE_TIME

start time of travelling, format: ‘yyyy-mm-ddThh:mmZ’

DEPTH_DATA

path to depth data e.g. /user/path-to-data/depth.nc

ROUTE_PATH

path to json file to which the route will be written

WEATHER_DATA

path to weather data e.g. /user/path-to-data/weather.nc

BOAT_BREADTH

ship breadth (m)

BOAT_FUEL_RATE

fuel rate at service propulsion point (g/kWh)

BOAT_HBR

height of top superstructure (bridge etc.) (m)

BOAT_LENGTH

overall length (m)

BOAT_SMCR_POWER

Specific Maximum Continuous Rating power (kWh)

BOAT_SMCR_SPEED

average speed at SMCR power (m/s)

BOAT_SPEED

boat speed (m/s)

Required variables in specific cases:

Name

Description

COURSES_FILE

path to file that acts as intermediate storage for courses per routing step; it is required if BOAT_TYPE="CBT"

Recommended variables:

Name

Description

BOAT_TYPE

fuel consumption modul; options: ‘direct_power_method’, ‘CBT’ (maripower), ‘SAL’ (maripower), ‘speedy_isobased’ (The latter shall only for testing; default: ‘direct_power_method’)

BOAT_ROUGHNESS_DISTRIBUTION_LEVEL

numeric value (default: 1)

BOAT_ROUGHNESS_LEVEL

numeric value (default: 1)

Optional variables:

Name

Description

ARRIVAL_TIME

arrival time at destination, format: ‘yyyy-mm-ddThh:mmZ’

AIR_MASS_DENSITY

mass density of air used for direct power method (default: 1.2225 kg/m^3)

BOAT_AOD

lateral projected area of superstructures etc. on deck (m)

BOAT_AXV

area of maximum transverse section exposed to the winds (m)

BOAT_AYV

projected lateral area above the waterline (m)

BOAT_BS1

breadth of substructure (m)

BOAT_CMC

horizontal distance from midship section to centre of lateral projected area AYV (m)

BOAT_DRAUGHT_AFT

aft draught (draught at rudder, default: 10m)

BOAT_DRAUGHT_FORE

fore draught (draught at forward perpendicular, default: 10m)

BOAT_HC

height of waterline to centre of lateral projected area Ayv (m)

BOAT_HS1

height of substructure 1 assumed for simple geometry (m)

BOAT_HS2

height of substructure 2 assumed for simple geometry (m)

BOAT_LS1

length of substructure 1 assumed for simple geometry (m)

BOAT_LS2

length of substructure 2 assumed for simple geometry (m)

BOAT_OVERLOAD_FACTOR

overload factor used for direct power method (default: 0)

BOAT_PROPULSION_EFFICIENCY

propulsion efficiency coefficient in ideal conditions (default: 0.63)

BOAT_FACTOR_CALM_WATER

multiplication factor for the calm water resistance model of maripower (default: 1)

BOAT_FACTOR_WAVE_FORCES

multiplication factor for added resistance in waves model of maripower (default: 1)

BOAT_FACTOR_WIND_FORCES

multiplication factor for the added resistance in wind model of maripower (default: 1)

BOAT_SPEED_MAX

maximum possible boat speed (m/s)

BOAT_UNDER_KEEL_CLEARANCE

vertical distance between keel and ground (default: 20m)

ALGORITHM_TYPE

options: ‘isofuel’, ‘genetic’, ‘speedy_isobased’ (The latter shall only for testing; default: ‘direct_power_method’; default: ‘isofuel’)

CONSTRAINTS_LIST

options: ‘land_crossing_global_land_mask’, ‘land_crossing_polygons’, ‘seamarks’, ‘water_depth’, ‘on_map’, ‘via_waypoints’, ‘status_error’ (default: [‘land_crossing_global_land_mask’, ‘water_depth’, ‘on_map’])

DELTA_FUEL

amount of fuel per routing step (default: 3000 kg)

DELTA_TIME_FORECAST

time resolution of weather forecast (default: 3h)

DIJKSTRA_MASK_FILE

path to the global land mask file; if the Python package is installed the file should already be available. It can be found with find ~ -type f -name globe_combined_mask_compressed.npz. Alternatively, it can be downloaded via GitHub

DIJKSTRA_NOF_NEIGHBORS

number of neighbors to use when creating a graph from the grid, defaults to 1

DIJKSTRA_STEP

step used to save final route to prevent very dense waypoints, defaults to 1

FACTOR_CALM_WATER

multiplication factor for the calm water resistance model

FACTOR_WAVE_FORCES

multiplication factor for the added resistance in waves model

GCR_SLIDER_ANGLE_STEP

angle step in degrees, defaults to 30

GCR_SLIDER_DISTANCE_MOVE

move distance in m, defaults to 10000

GCR_SLIDER_DYNAMIC_PARAMETERS

update parameters (e.g. move distance) dynamically, defaults to True

GCR_SLIDER_LAND_BUFFER

land buffer in m, defaults to 1000

GCR_SLIDER_INTERPOLATE

interpolate final route, defaults to True

GCR_SLIDER_INTERP_DIST

interpolation distance, defaults to 0.1

GCR_SLIDER_INTERP_NORMALIZED

normalized interpolation, defaults to True

GCR_SLIDER_THRESHOLD

segment length threshold in m below which segments are not split, defaults to 10000

FACTOR_WIND_FORCES

multiplication factor for the added resistance in wind model

GENETIC_MUTATION_TYPE

type for mutation (options: ‘grid_based’)

GENETIC_NUMBER_GENERATIONS

number of generations for genetic algorithm (default: 20)

GENETIC_NUMBER_OFFSPRINGS

number of offsprings for genetic algorithm (default: 2)

GENETIC_POPULATION_SIZE

population size for genetic algorithm (default: 20)

GENETIC_POPULATION_TYPE

type for initial population (options: ‘grid_based’, ‘from_geojson’, ‘isofuel’, ‘gcrslider’; default: ‘isofuel’)

GENETIC_POPULATION_PATH

path to initial population

GENETIC_REPAIR_TYPE

repair strategy for genetic algorithm (options: ‘waypoints_infill’, ‘constraint_violation’, ‘no_repair’, default: ‘waypoints_infill’ and ‘constraint_violation’)

GENETIC_MUTATION_TYPE

options: ‘random’, ‘rndm_walk’, ‘rndm_plateau’, ‘route_blend’, ‘no_mutation’ (default: ‘random’)

GENETIC_CROSSOVER_TYPE

options: ‘random’, ‘speed’ (default: ‘random’)

GENETIC_CROSSOVER_PATCHER

patching strategy for crossover (options: ‘gcr’, ‘isofuel’, default: ‘isofuel’)

GENETIC_FIX_RANDOM_SEED

options: True, False (default: False)

INTERMEDIATE_WAYPOINTS

coordinates for intermediate waypoints [[lat_one,lon_one], [lat_two,lon_two] … ] (default: [])

ISOCHRONE_MAX_ROUTING_STEPS

maximum number of routing steps. Applies also if more than one route is searched! (default: 100)

ISOCHRONE_MINIMISATION_CRITERION

options: ‘dist’, ‘squareddist_over_disttodest’ (default: ‘squareddist_over_disttodest’)

ISOCHRONE_NUMBER_OF_ROUTES

integer specifying how many routes should be searched (default: 1)

ISOCHRONE_PRUNE_GROUPS

can be ‘courses’, ‘larger_direction’, ‘branch’ (default: ‘larger_direction’)

ISOCHRONE_PRUNE_SECTOR_DEG_HALF

half of the angular range of azimuth angle considered for pruning; not used for branch-based pruning (default: 91)

ISOCHRONE_PRUNE_SEGMENTS

total number of azimuth bins used for pruning in prune sector; not used for branch-based pruning (default: 20)

ISOCHRONE_PRUNE_SYMMETRY_AXIS

symmetry axis for pruning. Can be ‘gcr’ or ‘headings_based’; not used for branch-based pruning (default: ‘gcr’)

ROUTER_HDGS_INCREMENTS_DEG

increment of headings (default: 6)

ROUTER_HDGS_SEGMENTS

total number of headings (put even number!!); headings are oriented around the great circle from current point to (temporary - i.e. next waypoint if used) destination (default: 30)

ROUTE_POSTPROCESSING

enable route postprocessing to follow the Traffic Separation Scheme in route postprocessing (default: False)

TIME_FORECAST

forecast hours weather (default: 90h)

Environment variables

Credentials for the Copernicus Marine Environment Monitoring Service (CMEMS) to download weather/ocean data:

  • CMEMS_USERNAME

  • CMEMS_PASSWORD

If not provided DATA_MODE='automatic' cannot be used.

Configuration parameters for the database which stores OpenSeaMap data (optional):

  • WRT_DB_HOST

  • WRT_DB_PORT

  • WRT_DB_DATABASE

  • WRT_DB_USERNAME

  • WRT_DB_PASSWORD

If not provided the ‘land_crossing_polygons’ and ‘seamarks’ options of CONSTRAINTS_LIST and ROUTE_POSTPROCESSING=True cannot be used.

Path for storing figures (mainly for debugging purposes):

  • WRT_FIGURE_PATH

If not set or the path doesn’t exist or access rights are wrong, no figures will be saved.

You can define the environment variables in a separate .env file and call the provided shell script:

source <path-to-WRT>/load_wrt.sh

Logging and Debugging

All log messages are sent to stdout by default. In addition, info and warning logs can be saved separately to file. Debugging mode can be enabled (disabled by default) which sets the stream (stdout) logging level to debug.

The top-level logger is named “WRT”. Child loggers are following the scheme “WRT.<child-name>”. They inherit the top-level loggers’ logging level.

Input data

The WRT currently requires data for the water depth as well as the following environmental parameters:

  • u-component_of_wind_height_above_ground (u-component of wind @ Specified height level above ground)

  • v-component_of_wind_height_above_ground (v-component of wind @ Specified height level above ground)

  • vtotal (Northward total velocity: Eulerian + Waves + Tide)

  • utotal (Eastward total velocity: Eulerian + Waves + Tide)

  • VHMO (spectral significant wave height @ sea surface)

  • VMDR (mean wave direction @ sea surface)

  • VTPK (wave period at spectral peak)

  • thetao (potential temperature)

  • Pressure_reduced_to_MSL_msl (pressure reduced to mean sea level)

  • Temperature_surface (temperature at the water surface)

  • so (salinity)

Thereby, the depth data and the weather data need to be wrapped in separate netCDF files. If no input data is provided but the config parameters DEPTH_DATA and WEATHER_DATA are set to valid paths, the data is downloaded automatically from

In principle, the WRT can also be used without providing depth data but to it is highly recommended to provide depth information to obtain realistic routes. If no depth data is provided, the water_depth option of CONSTRAINTS_LIST can not be used.

sequence_diagram_installation_workflow

Fig. 1: Basic installation workflow for the WeatherRoutingTool.

Output data

The characteristics of the most optimal route(s) that has been/have been found by the routing algorithm are written to a json file. Thereby, a route is a collection of individual route segments for which the ship is assumed to travel under constant environmental conditions as well as constant ship parameters. The characteristics of a route segment are always tied to the starting coordinates of the route segment when written to json file. Therefore, all parameters but time and coordinates are set to arbitrary values (-99) for the last entry in the output file. The following parameters are written to file:

  • coordinates; format: [lon, lat]

  • time; format: ‘yyyy-mm-dd hh:mm:ss’

  • speed (m/s)

  • engine power (kW)

  • fuel consumption (mt/h)

  • fuel type

  • propeller revolution (Hz)

  • calm water resistance (N)

  • wind resistance (N)

  • wave resistance (N)

  • shallow water resistance (N)

  • hull roughness resistance (N)

  • status; potential status code for validity of hydrodynamic modelling

  • wave height (m)

  • wave direction (radian)

  • wave period (s)

  • u component of ocean currents (m/s)

  • v component of ocean currents (m/s)

  • u component of wind speed (m/s)

  • v component of wind speed (m/s)

  • air pressure (Pa)

  • air temperature (°C)

  • water temperature (°C)

  • salinity