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 (no default values provided):

  • 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 (no default values provided):

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

Recommended variables:

  • 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 (default values provided and don’t need to be changed normally):

  • 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_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: 3000kg)

  • DELTA_TIME_FORECAST: time resolution of weather forecast (default: 3h)

  • FACTOR_CALM_WATER: multiplication factor for the calm water resistance model

  • FACTOR_WAVE_FORCES: multiplication factor for the added resistance in waves model

  • 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’; default: ‘grid_based’)

  • 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_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](https://www.unidata.ucar.edu/software/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