# borisimo/tmr4240_group_12 architecture

> Architecture diagram of the GitHub repository borisimo/tmr4240_group_12, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/borisimo/tmr4240_group_12
- Repository: https://github.com/borisimo/tmr4240_group_12

## Overview

This repository is a teaching simulator for designing and evaluating a 3-DOF dynamic-positioning system for R/V Gunnerus. The main workflow is to configure and run a Part 1 or Part 2 scenario: the simulation engine advances the vessel, obtains control and environmental loads, allocates thrust, and records results for plotting. Part 2 adds measured-pose feedback with observer estimates, constrained actuators, irregular-wave loads, and thrust-utilisation analysis. The README documents these capabilities; source excerpts show key Part 1 wiring and selected model behavior, while some Part 2 connections are supported by the source index or README rather than inspected implementation excerpts.

Main entry points: [`simulation/simulation_part_2.py`](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/simulation_part_2.py) (Part 2 loop), [`simulation/simulation_part_1.py`](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/simulation_part_1.py) (Part 1 loop), [`run_case_part_2.py`](https://github.com/borisimo/tmr4240_group_12/blob/main/run_case_part_2.py) (Part 2 runner), [`models/thruster_dynamics.py`](https://github.com/borisimo/tmr4240_group_12/blob/main/models/thruster_dynamics.py) (Thruster dynamics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_scenario["Scenario design"]
  node_runner1["Part 1 runner<br/>[run_case_part1.py]"]
  node_runner2["Part 2 runner<br/>[run_case_part_2.py]"]
end

subgraph group_part1["Part 1 design"]
  node_p1controller["DP controller<br/>[controller.py]"]
  node_p1current["Current model<br/>[current.py]"]
  node_p1wind["Wind model<br/>[wind.py]"]
  node_p1reference["Reference model<br/>[reference.py]"]
  node_p1allocation["Thrust allocation"]
  node_p1config["Part 1 config<br/>[config.py]"]
end

subgraph group_part2["Part 2 design"]
  node_utilization["Thrust metrics<br/>[utilization.py]"]
  node_p2controller["DP controller<br/>[controller.py]"]
  node_p2current["Current model<br/>[current.py]"]
  node_p2wind["Wind model<br/>[wind.py]"]
  node_p2reference["Reference model<br/>[reference.py]"]
  node_p2allocation["Thrust allocation"]
  node_observer["State observers<br/>[observer.py]"]
  node_p2config["Part 2 config<br/>[config.py]"]
end

subgraph group_runtime["Simulation runtime"]
  node_sim1["Part 1 loop"]
  node_sim2["Part 2 loop"]
  node_plant["Open-loop plant<br/>[plant.py]"]
  node_plot1["Shared plotting<br/>[plotter.py]"]
  node_plot2["Part 2 plotting<br/>[plotter_part_2.py]"]
  node_capability["Capability sweep<br/>[capability.py]"]
end

subgraph group_models["Vessel and environment"]
  node_vessel["Gunnerus model<br/>[gunnerus_3dof.py]"]
  node_thrusters["Thruster dynamics"]
  node_sensors["Pose sensors<br/>[sensors.py]"]
  node_waves["Wave loads<br/>[waves.py]"]
  node_wave_data[("Vessel wave data")]
  node_wind_data["Wind coefficients<br/>[wind_coeff.csv]"]
end

node_engineer(("Engineer"))

node_engineer -->|"configures"| node_runner1
node_engineer -->|"configures"| node_runner2
node_runner1 -->|"runs"| node_sim1
node_runner2 -->|"runs"| node_sim2
node_runner1 -->|"plots results"| node_plot1
node_runner2 -->|"plots results"| node_plot2
node_runner2 -->|"runs sweep"| node_capability
node_sim1 -->|"advances"| node_vessel
node_sim1 -->|"steps actuators"| node_thrusters
node_sim1 -->|"requests wrench"| node_p1controller
node_sim1 -->|"updates reference"| node_p1reference
node_sim1 -->|"allocates thrust"| node_p1allocation
node_sim1 -->|"reads current"| node_p1current
node_sim1 -->|"reads wind loads"| node_p1wind
node_sim2 -->|"uses plant"| node_plant
node_sim2 -->|"advances"| node_vessel
node_sim2 -->|"steps actuators"| node_thrusters
node_sim2 -->|"measures pose"| node_sensors
node_sim2 -->|"estimates state"| node_observer
node_sim2 -->|"requests wrench"| node_p2controller
node_sim2 -->|"updates reference"| node_p2reference
node_sim2 -->|"allocates thrust"| node_p2allocation
node_sim2 -->|"reads current"| node_p2current
node_sim2 -->|"reads wind loads"| node_p2wind
node_sim2 -->|"gets wave loads"| node_waves
node_waves -->|"loads data"| node_wave_data
node_p1wind -->|"loads coefficients"| node_wind_data
node_p1allocation -->|"uses limits"| node_thrusters
node_p2allocation -->|"uses limits"| node_thrusters
node_p1controller -->|"uses gains"| node_p1config
node_p2controller -->|"uses gains"| node_p1config
node_capability -->|"computes metrics"| node_utilization
node_plot2 -.->|"plots logs"| node_sim2

click node_runner1 "https://github.com/borisimo/tmr4240_group_12/blob/main/run_case_part1.py"
click node_runner2 "https://github.com/borisimo/tmr4240_group_12/blob/main/run_case_part_2.py"
click node_sim1 "https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/simulation_part_1.py"
click node_sim2 "https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/simulation_part_2.py"
click node_plant "https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/plant.py"
click node_plot1 "https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/plotter.py"
click node_plot2 "https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/plotter_part_2.py"
click node_capability "https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/capability.py"
click node_utilization "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/utilization.py"
click node_vessel "https://github.com/borisimo/tmr4240_group_12/blob/main/models/gunnerus_3dof.py"
click node_thrusters "https://github.com/borisimo/tmr4240_group_12/blob/main/models/thruster_dynamics.py"
click node_sensors "https://github.com/borisimo/tmr4240_group_12/blob/main/models/sensors.py"
click node_waves "https://github.com/borisimo/tmr4240_group_12/blob/main/models/waves.py"
click node_wave_data "https://github.com/borisimo/tmr4240_group_12/blob/main/data/gunnerus_vessel.json"
click node_wind_data "https://github.com/borisimo/tmr4240_group_12/blob/main/data/wind_coeff.csv"
click node_p1controller "https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/controller.py"
click node_p1current "https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/current.py"
click node_p1wind "https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/wind.py"
click node_p1reference "https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/reference.py"
click node_p1allocation "https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/thrust_allocation.py"
click node_p1config "https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/config.py"
click node_p2controller "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/controller.py"
click node_p2current "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/current.py"
click node_p2wind "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/wind.py"
click node_p2reference "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/reference.py"
click node_p2allocation "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/thrust_allocation.py"
click node_observer "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/observer.py"
click node_p2config "https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner1,node_runner2 toneBlue
class node_p1controller,node_p1current,node_p1wind,node_p1reference,node_p1allocation,node_p1config toneAmber
class node_utilization,node_p2controller,node_p2current,node_p2wind,node_p2reference,node_p2allocation,node_observer,node_p2config toneMint
class node_sim1,node_sim2,node_plant,node_plot1,node_plot2,node_capability toneRose
class node_vessel,node_thrusters,node_sensors,node_waves,node_wave_data,node_wind_data,node_engineer toneIndigo
```

## Components

### Scenario design

- [Part 1 runner](https://github.com/borisimo/tmr4240_group_12/blob/main/run_case_part1.py): `run_case_part1.py`
- [Part 2 runner](https://github.com/borisimo/tmr4240_group_12/blob/main/run_case_part_2.py): `run_case_part_2.py`

### Part 1 design

- [DP controller](https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/controller.py): `part_1/controller.py`
- [Current model](https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/current.py): `part_1/current.py`
- [Wind model](https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/wind.py): `part_1/wind.py`
- [Reference model](https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/reference.py): `part_1/reference.py`
- [Thrust allocation](https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/thrust_allocation.py): `part_1/thrust_allocation.py`
- [Part 1 config](https://github.com/borisimo/tmr4240_group_12/blob/main/part_1/config.py): `part_1/config.py`

### Part 2 design

- [Thrust metrics](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/utilization.py): `part_2/utilization.py`
- [DP controller](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/controller.py): `part_2/controller.py`
- [Current model](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/current.py): `part_2/current.py`
- [Wind model](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/wind.py): `part_2/wind.py`
- [Reference model](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/reference.py): `part_2/reference.py`
- [Thrust allocation](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/thrust_allocation.py): `part_2/thrust_allocation.py`
- [State observers](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/observer.py): `part_2/observer.py`
- [Part 2 config](https://github.com/borisimo/tmr4240_group_12/blob/main/part_2/config.py): `part_2/config.py`

### Simulation runtime

- [Part 1 loop](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/simulation_part_1.py): `simulation/simulation_part_1.py`
- [Part 2 loop](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/simulation_part_2.py): `simulation/simulation_part_2.py`
- [Open-loop plant](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/plant.py): `simulation/plant.py`
- [Shared plotting](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/plotter.py): `simulation/plotter.py`
- [Part 2 plotting](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/plotter_part_2.py): `simulation/plotter_part_2.py`
- [Capability sweep](https://github.com/borisimo/tmr4240_group_12/blob/main/simulation/capability.py): `simulation/capability.py`

### Vessel and environment

- [Gunnerus model](https://github.com/borisimo/tmr4240_group_12/blob/main/models/gunnerus_3dof.py): `models/gunnerus_3dof.py`
- [Thruster dynamics](https://github.com/borisimo/tmr4240_group_12/blob/main/models/thruster_dynamics.py): `models/thruster_dynamics.py`
- [Pose sensors](https://github.com/borisimo/tmr4240_group_12/blob/main/models/sensors.py): `models/sensors.py`
- [Wave loads](https://github.com/borisimo/tmr4240_group_12/blob/main/models/waves.py): `models/waves.py`
- [Vessel wave data](https://github.com/borisimo/tmr4240_group_12/blob/main/data/gunnerus_vessel.json): `data/gunnerus_vessel.json`
- [Wind coefficients](https://github.com/borisimo/tmr4240_group_12/blob/main/data/wind_coeff.csv): `data/wind_coeff.csv`

### Other components

- **Engineer**

## Connections

- Engineer → Part 1 runner: configures (evidence: `README.md`)
- Engineer → Part 2 runner: configures (evidence: `README.md`)
- Part 1 runner → Part 1 loop: runs (evidence: `run_case_part1.py`)
- Part 2 runner → Part 2 loop: runs (evidence: `run_case_part_2.py`)
- Part 1 runner → Shared plotting: plots results (evidence: `run_case_part1.py`)
- Part 2 runner → Part 2 plotting: plots results (evidence: `run_case_part_2.py`)
- Part 2 runner → Capability sweep: runs sweep (evidence: `run_case_part_2.py`)
- Part 1 loop → Gunnerus model: advances (evidence: `simulation/simulation_part_1.py`)
- Part 1 loop → Thruster dynamics: steps actuators (evidence: `simulation/simulation_part_1.py`)
- Part 1 loop → DP controller: requests wrench (evidence: `simulation/simulation_part_1.py`)
- Part 1 loop → Reference model: updates reference (evidence: `simulation/simulation_part_1.py`)
- Part 1 loop → Thrust allocation: allocates thrust (evidence: `simulation/simulation_part_1.py`)
- Part 1 loop → Current model: reads current (evidence: `simulation/simulation_part_1.py`)
- Part 1 loop → Wind model: reads wind loads (evidence: `simulation/simulation_part_1.py`)
- Part 2 loop → Open-loop plant: uses plant (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Gunnerus model: advances (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Thruster dynamics: steps actuators (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Pose sensors: measures pose (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → State observers: estimates state (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → DP controller: requests wrench (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Reference model: updates reference (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Thrust allocation: allocates thrust (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Current model: reads current (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Wind model: reads wind loads (evidence: `simulation/simulation_part_2.py`)
- Part 2 loop → Wave loads: gets wave loads (evidence: `README.md`)
- Wave loads → Vessel wave data: loads data (evidence: `README.md`)
- Wind model → Wind coefficients: loads coefficients (evidence: `part_1/wind.py`)
- Thrust allocation → Thruster dynamics: uses limits (evidence: `part_1/thrust_allocation.py`)
- Thrust allocation → Thruster dynamics: uses limits (evidence: `part_2/thrust_allocation.py`)
- DP controller → Part 1 config: uses gains (evidence: `part_1/controller.py`)
- DP controller → Part 1 config: uses gains (evidence: `part_2/controller.py`)
- Capability sweep → Thrust metrics: computes metrics (evidence: `simulation/capability.py`)
- Part 2 plotting → Part 2 loop: plots logs
