API Reference¶
This chapter provides a reference for OMRAT’s key modules, classes, and functions.
compute.basic_equations¶
Core mathematical formulas for risk calculations.
Source file: compute/basic_equations.py (View on GitHub)
Drifting Functions¶
- get_Fcoll(na, pc)¶
Calculate accident frequency from candidates and causation factor.
- Parameters:
na – Number of accident candidates
pc – Causation probability
- Returns:
Accident frequency (\(F = N_A \times P_C\))
Line: 5 | Source
- get_drifting_prob(Fb, line_length, ship_speed)¶
Calculate the probability of a blackout during transit.
- Parameters:
Fb – Blackout frequency (events/year)
line_length – Leg length (metres)
ship_speed – Ship speed (m/s)
- Returns:
Blackout probability
Uses: \(P = 1 - \exp(-F_b / (24 \times 365) \times h)\)
Line: 9 | Source
- get_drift_time(distance, drift_speed)¶
Estimate the time to drift a given distance.
- Parameters:
distance – Drift distance (metres)
drift_speed – Drift speed (m/s)
- Returns:
Drift time (seconds)
Line: 14 | Source
- get_not_repaired(data, drift_speed, dist)¶
Get the probability that the engine is not repaired before drifting distance
dist.- Parameters:
data – Repair time parameters dict
drift_speed – Drift speed (m/s)
dist – Distance to obstacle (metres)
- Returns:
Probability of not being repaired
Line: 30 | Source
Ship-Ship Collision Functions¶
- get_head_on_collision_candidates(Q1, Q2, V1, V2, mu1, mu2, sigma1, sigma2, B1, B2, L_w)¶
Calculate geometric head-on collision candidates (Hansen Eq. 4.2–4.4).
- Parameters:
Q2 (Q1,) – Traffic volumes (ships/year)
V2 (V1,) – Ship speeds (m/s)
mu2 (mu1,) – Mean lateral positions (m)
sigma2 (sigma1,) – Standard deviations (m)
B2 (B1,) – Ship beams (m)
L_w – Leg length (m)
- Returns:
Geometric collision candidates per year
Line: 46 | Source
- get_overtaking_collision_candidates(Q_fast, Q_slow, V_fast, V_slow, mu_fast, mu_slow, sigma_fast, sigma_slow, B_fast, B_slow, L_w)¶
Calculate geometric overtaking collision candidates (Hansen Eq. 4.5). Returns 0 if
V_fast <= V_slow.- Returns:
Geometric collision candidates per year
Line: 147 | Source
- get_crossing_collision_candidates(Q1, Q2, V1, V2, L1, L2, B1, B2, theta)¶
Calculate geometric crossing collision candidates (Hansen Eq. 4.6). Returns 0 if legs are parallel (
sin(theta) ~ 0).- Parameters:
theta – Crossing angle (radians)
- Returns:
Geometric collision candidates per year
Line: 238 | Source
Powered Grounding Functions¶
- get_recovery_distance(position_check_minutes, ship_speed)¶
Calculate recovery distance \(a = \lambda \times V\).
- Parameters:
position_check_minutes – Check interval (minutes)
ship_speed – Ship speed (m/s)
- Returns:
Recovery distance (metres)
Line: 408 | Source
- get_powered_grounding_cat1(Q, Pc, prob_in_obstacle)¶
Category I powered grounding – ships sailing directly into obstacle.
- Parameters:
Q – Traffic volume (ships/year)
Pc – Causation factor
prob_in_obstacle – Fraction of distribution overlapping obstacle
- Returns:
Expected groundings per year
Line: 432 | Source
- get_powered_grounding_cat2(Q, Pc, prob_at_position, distance_to_obstacle, position_check_interval, ship_speed)¶
Category II powered grounding – ships failing to turn at bend.
- Parameters:
distance_to_obstacle – Distance from bend (metres)
position_check_interval – Check interval (minutes)
- Returns:
Expected groundings per year
Line: 470 | Source
compute.run_calculations¶
Source file: compute/run_calculations.py (View on GitHub)
- class Calculation(omrat)¶
Main calculation orchestrator.
Line: 44 | Source
Composed from mixins:
DriftingModelMixin,ShipCollisionModelMixin,PoweredModelMixin,DriftingReportMixin,VisualizationMixin(run_calculations.py:34-50)- run_drifting_model(data)¶
Execute the complete drifting risk calculation pipeline: drift corridor generation, Monte Carlo probability integration, repair time application, wind rose weighting.
- run_ship_collision_model(data)¶
Calculate ship-ship collision frequencies for all encounter types.
- run_powered_grounding_model(data)¶
Calculate powered grounding (Category I and II).
Implementation details:
- Groups draughts into effective depth bins based on depth
contours.
Reuses cached shadow/ray-casting computations per bin.
Emits progress updates per obstacle-bin step for long runs.
- run_powered_allision_model(data)¶
Calculate powered allision with structures.
- run_drift_visualization(data)¶
Generate drift corridor visualisation layers without full probability calculation.
geometries.drift¶
Source file: geometries/drift/generator.py (View on GitHub)
Drift Corridor Generation¶
- class DriftCorridorGenerator(omrat)¶
Main orchestrator for drift corridor generation.
Line: 25 | Source
- precollect_data(depth_threshold, height_threshold)¶
Pre-collect data from UI in the main thread.
- generate_corridors(depth_threshold, height_threshold, target_prob=1e-3)¶
Generate corridors for all legs and 8 directions.
- Returns:
List of corridor dicts with keys:
direction,angle,leg_index,polygon,anchor_polygon,deep_polygon
Corridor Construction¶
- create_base_surface(leg, half_width)¶
Create the base distribution rectangle for a leg.
- create_projected_corridor(leg, half_width, drift_angle_deg, projection_dist)¶
Create the full unclipped corridor by projecting the base surface.
- create_obstacle_shadow(obstacle, drift_angle_deg, corridor_bounds)¶
Create the blocking shadow zone behind an obstacle.
- clip_corridor_at_obstacles(corridor, obstacles, drift_angle_deg)¶
Clip corridor by removing all shadow zones.
Distribution Utilities¶
- get_projection_distance(repair_params, drift_speed_ms, target_prob=1e-3, max_distance=50000)¶
Calculate maximum drift distance from repair time distribution.
- get_distribution_width(std, coverage=0.99)¶
Calculate lateral strip width for given distribution coverage.
Coordinate Utilities¶
- get_utm_crs(lon, lat)¶
Return the appropriate UTM CRS for a geographic location.
- transform_geometry(geom, from_crs, to_crs)¶
Transform a Shapely geometry between coordinate reference systems.
- compass_to_vector(angle_deg, distance)¶
Convert compass angle and distance to (dx, dy) vector in UTM.
geometries.calculate_probability_holes¶
- compute_probability_holes(lines, distributions, weights, objs_gdf_list, distance, progress_callback=None)¶
Compute probability that vessels will hit each obstacle using Monte Carlo integration with parallel execution.
- Parameters:
lines – List of leg LineStrings (UTM)
distributions – List of distribution parameter lists
weights – List of weight lists
objs_gdf_list – List of obstacle polygon lists (one per direction)
distance – Maximum drift distance (metres)
progress_callback – Optional
(completed, total, msg) -> bool
- Returns:
3D array
[leg][direction][obstacle]of probabilities
Line: 642 | Source
geometries.result_layers¶
- create_result_layers(report, structures, depths, add_to_project=True)¶
Create QGIS vector layers with per-segment probability attributes.
- Parameters:
report – Drifting report dict from calculation
structures – List of structure dicts
depths – List of depth dicts
- Returns:
(allision_layer, grounding_layer)
omrat_utils¶
Key data management classes:
- class Traffic(omrat, widget)¶
Manages the traffic data table UI and underlying data structures.
- class OObject(omrat)¶
Manages depth and structure obstacle layers and data.
- class DriftSettings(omrat)¶
Manages drift parameters (wind rose, speed, repair time).
- class CausationFactors(omrat)¶
Manages causation factor values.
- class Distributions(omrat)¶
Manages lateral traffic distribution parameters and visualisation.
- class AIS(omrat)¶
Manages AIS database connections and traffic data import.
- class GatherData(omrat)¶
Collects all data for save/load and populates from saved data.
- class Storage(omrat)¶
Handles project file I/O (
.omratJSON format).
- class ShipCategories(omrat)¶
Manages ship type and size bin definitions.