# 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

repairtime_function(data, x)

  Evaluate the repair time CDF at time `x`.

  Parameters:

    - data – Repair parameters dict

    - x – Time (hours)

  Returns:

    Cumulative repair probability

  Line: 18 | 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

get_bend_collision_candidates(Q, P_no_turn, L, B, theta)

  Calculate bend collision candidates at waypoints.

  Parameters:

    - Q – Traffic volume (ships/year)

    - P_no_turn – Probability of not turning (default 0.01)

    - theta – Bend angle (radians)

  Returns:

    Bend collision candidates per year

  Line: 331 | 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 (`.omrat` JSON format).

class ShipCategories(omrat)

  Manages ship type and size bin definitions.