Workflows

Short end-to-end recipes for common tasks. Each one assumes you already have OMRAT open and a project loaded. If any step refers to a tab or field you don’t recognise, see User Guide.

Build a project from scratch (no AIS)

  1. Route tab – Add Route, click waypoints on the map, Stop Route.

  2. Traffic tab – for every segment, select direction and enter the Frequency / Speed / Draught / Height / Beam matrix manually. A single busy ship type row is enough for a first pass.

  3. Depths tab – load a shapefile or use Get GEBCO Depths with your OpenTopography key.

  4. Objects tab – load a shapefile with a height attribute or draw polygons manually.

  5. Settings -> Drift settings – check the wind rose (default is uniform) and the repair distribution (default is lognormal with IWRAP defaults). Adjust if you have local data.

  6. Distributions tab – for every segment, check the PDF plot. Adjust mean1_1 / std1_1 / weight1_1 until the plot matches the expected track spread.

  7. Results tab -> Run Model.

Build a project from AIS

  1. Settings -> AIS connection settings – fill in the database parameters.

  2. Digitise the route as above (Route tab).

  3. Select each segment in turn and click Update AIS. This fires a PostgreSQL query against your AIS schema; OMRAT populates the traffic matrix for both directions automatically.

  4. Continue from step 3 of the “from scratch” recipe.

Tip: the AIS queries can be slow on large schemas. The time per leg is written to the QGIS log tab.

Import an existing IWRAP XML

If you have an existing IWRAP Mk2 project:

  1. File -> Import from IWRAP XML.

  2. Select the .xml file.

OMRAT parses the IWRAP schema and fills in segments, traffic, obstacles, and causation factors. Lateral distributions are converted from IWRAP’s (mean, std) per segment.

Cross-validate by running the risk and comparing against IWRAP. Small differences (few percent) are expected – OMRAT uses analytical CDF integration where IWRAP uses Monte Carlo.

Export for use in IWRAP

  1. File -> Export to IWRAP XML.

  2. Pick a location and filename.

The emitted XML is IWRAP Mk2 compatible. Anything OMRAT computes that has no IWRAP counterpart (e.g. the anchoring branch) is dropped from the export.

Inspect the dominant obstacle on a risk number

If a result is surprisingly high, you usually want to know which single polygon is contributing the most.

  1. Run the model.

  2. Click View next to the result field of interest (e.g. Drift Grounding).

  3. A dialog opens with per-obstacle contributions sorted by probability.

Alternatively, inspect the Drifting grounding results layer on the map – it is coloured by contribution (red = highest). Click any polygon to open its attribute row with per-leg and per-direction totals.

Debug why a number looks wrong

Enable the debug trace:

  1. Open the saved .omrat JSON in a text editor, or set it from the UI if your release exposes the flag: drift.debug_trace = true.

  2. Run the model again.

  3. Open the auto-generated Markdown report – its path is shown in the QGIS log tab (look for Drifting report written to:). The report now has a Debug Obstacles section listing every (leg, direction, obstacle) triple with its contribution, distance, probability hole, \(P_{NR}\), exposure factor, rose probability, base exposure, and frequency.

For the most forensic view, use the worked-example scripts in drifting/debug/level_1 … level_5 which recompute a single scenario end-to-end and print every intermediate variable. These are the same examples referenced from Drifting Risk Calculations.

Speed up a slow calculation

OMRAT already uses most of the reasonable optimisations (shadow caching, batched CDF calls, vectorised ray-casting). If a run takes longer than you expect:

  1. Look in the QGIS log tab. A log line tells you the largest phase (shadow precompute, bucket memo, cascade, …).

  2. The shadow precompute phase is dominated by obstacle polygon complexity. If you have a coastline polygon with tens of thousands of vertices, consider simplifying it in QGIS (Vector -> Geometry Tools -> Simplify) before loading.

  3. The analytical probability holes phase scales with n_slices (default 100) x number of obstacles x number of legs x 8 directions. You can reduce n_slices in compute_probability_holes_analytical() for a quick-and-dirty estimate, at the cost of some accuracy.

  4. For very complex projects, run the analysis track instead (Drift Analysis tab). It skips the risk integration entirely and just draws the corridors – orders of magnitude cheaper.

Reproduce an old result

OMRAT is deterministic when using the analytical probability path (the default). Given the same .omrat file and the same code version, Run Model produces bit-identical numbers on any machine.

The Monte Carlo path (use_analytical=False) is not deterministic unless you set a random seed before invoking it.

Run a calculation without the QGIS UI (headless)

The risk calculation doesn’t intrinsically depend on QGIS. You can load an .omrat file, build the calculation object, and run it from a Python script. See tests/diagnostics/profile_drifting_e2e.py for a minimal example (it’s also what was used to produce the end-to-end benchmark numbers in Code Flow: From “Run Model” to Results).

The UI-free path is useful for batch runs (sweeping parameters over a scenario tree) or for integrating OMRAT into a larger pipeline.

Compare two result sets

There is no built-in diff tool, but the pattern is:

  1. Run the first scenario, File -> Save as scenario_a.omrat.

  2. Change whatever you want (e.g. reduce traffic on one leg).

  3. Run again, File -> Save as scenario_b.omrat.

  4. Open both JSON files in a diff tool (git diff --no-index, VS Code’s built-in diff, etc.). Every result field is in the results section, and the full per-obstacle drifting report is in drifting_report.