# lambrooo/tirociniouni architecture

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

- Interactive diagram: https://gitdiagram.com/lambrooo/tirociniouni
- Repository: https://github.com/lambrooo/tirociniouni

## Overview

This repository is a thesis research testbed for Active Inference control under compromised sensors in a simulated IIoT plant. The main workflow is to run paired fixed and adaptive agents against shared scenario traces, simulate plant control and verification, then retain run logs and event records for metric and statistical analysis. The README also documents a second scoring condition without the entropy term, archived reproducibility data, parameter exploration, and figure generation. Some subsystem links rely on README descriptions because their implementation was not sampled.

Main entry points: [`run_confirmatory_experiments.py`](https://github.com/lambrooo/tirociniouni/blob/main/run_confirmatory_experiments.py) (Confirmatory Runner), [`pytorch_simulation/simulation.py`](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py) (Plant Simulation), [`confirmatory_experiments/run_20260901_193850`](https://github.com/lambrooo/tirociniouni/tree/main/confirmatory_experiments/run_20260901_193850) (Campaign Archive), [`pytorch_simulation/active_inference_agent.py`](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/active_inference_agent.py) (Fixed Inference)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plant["IIoT Simulation"]
  node_plant_sim["Plant Simulation<br/>[simulation.py]"]
  node_scenario_traces["Scenario Traces<br/>[scenario_trace.py]"]
  node_sensors["Compromised Sensors<br/>[simulation.py]"]
  node_actuators["Actuators<br/>[simulation.py]"]
end

subgraph group_agents["Control Agents"]
  node_fixed_agent["Fixed Inference"]
  node_adaptive_agent["Adaptive Inference"]
  node_q_agent["Q-Learning Baseline<br/>[qlearning_agent.py]"]
  node_curriculum["Curriculum Attacks"]
end

subgraph group_campaign["Experiments"]
  node_campaign_runner["Confirmatory Runner"]
  node_campaign_data[("Campaign Archive")]
  node_no_entropy_data[("No-Entropy Archive")]
  node_replay_data[("Reproducibility Archive")]
end

subgraph group_analysis["Research Outputs"]
  node_metrics["Run Metrics<br/>[simulation.py]"]
  node_statistics["Statistical Analysis"]
  node_dashboard["Experiment Dashboard<br/>[dashboard.py]"]
  node_thesis_figures["Thesis Figures<br/>[genera_figure.py]"]
  node_exploration["Parameter Exploration"]
  node_verification["Thesis Verification<br/>[verify_thesis.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts campaign"| node_campaign_runner
node_campaign_runner -->|"generates traces"| node_scenario_traces
node_campaign_runner -->|"runs fixed agent"| node_fixed_agent
node_campaign_runner -->|"runs adaptive agent"| node_adaptive_agent
node_campaign_runner -->|"runs simulation"| node_plant_sim
node_plant_sim -->|"samples readings"| node_sensors
node_sensors -->|"provides observations"| node_fixed_agent
node_sensors -->|"provides observations"| node_adaptive_agent
node_fixed_agent -->|"issues controls"| node_actuators
node_adaptive_agent -->|"issues controls"| node_actuators
node_plant_sim -->|"returns run data"| node_campaign_runner
node_campaign_runner -->|"writes run artifacts"| node_campaign_data
node_researcher -->|"reviews results"| node_no_entropy_data
node_campaign_runner -.->|"stores second condition"| node_no_entropy_data
node_campaign_runner -->|"collects metrics"| node_metrics
node_metrics -->|"analyzes outcomes"| node_statistics
node_researcher -->|"explores results"| node_dashboard
node_researcher -->|"runs exploration"| node_exploration
node_campaign_data -->|"supplies archived CSVs"| node_thesis_figures
node_researcher -->|"generates figures"| node_thesis_figures
node_campaign_data -->|"checks archived data"| node_verification
node_replay_data -->|"compares replay"| node_verification
node_researcher -.->|"selects baseline"| node_q_agent
node_researcher -.->|"configures attack stages"| node_curriculum

click node_campaign_runner "https://github.com/lambrooo/tirociniouni/blob/main/run_confirmatory_experiments.py"
click node_plant_sim "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py"
click node_scenario_traces "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/scenario_trace.py"
click node_sensors "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py"
click node_actuators "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py"
click node_fixed_agent "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/active_inference_agent.py"
click node_adaptive_agent "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/active_inference_agent.py"
click node_q_agent "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/qlearning_agent.py"
click node_curriculum "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/curriculum_learning.py"
click node_campaign_data "https://github.com/lambrooo/tirociniouni/tree/main/confirmatory_experiments/run_20260901_193850"
click node_no_entropy_data "https://github.com/lambrooo/tirociniouni/tree/main/confirmatory_experiments/run_20260926_senza_entropia"
click node_replay_data "https://github.com/lambrooo/tirociniouni/tree/main/reproducibility/review_20260925"
click node_metrics "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py"
click node_statistics "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/statistical_analysis.py"
click node_dashboard "https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/dashboard.py"
click node_thesis_figures "https://github.com/lambrooo/tirociniouni/blob/main/scripts/genera_figure.py"
click node_exploration "https://github.com/lambrooo/tirociniouni/blob/main/scripts/esplora_parametri.py"
click node_verification "https://github.com/lambrooo/tirociniouni/blob/main/scripts/verify_thesis.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_plant_sim,node_scenario_traces,node_sensors,node_actuators toneBlue
class node_fixed_agent,node_adaptive_agent,node_q_agent,node_curriculum toneAmber
class node_campaign_runner,node_campaign_data,node_no_entropy_data,node_replay_data toneMint
class node_metrics,node_statistics,node_dashboard,node_thesis_figures,node_exploration,node_verification toneRose
class node_researcher toneIndigo
```

## Components

### IIoT Simulation

- [Plant Simulation](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py): `pytorch_simulation/simulation.py`
- [Scenario Traces](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/scenario_trace.py): `pytorch_simulation/scenario_trace.py`
- [Compromised Sensors](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py): `pytorch_simulation/simulation.py`
- [Actuators](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py): `pytorch_simulation/simulation.py`

### Control Agents

- [Fixed Inference](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/active_inference_agent.py): `pytorch_simulation/active_inference_agent.py`
- [Adaptive Inference](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/active_inference_agent.py): `pytorch_simulation/active_inference_agent.py`
- [Q-Learning Baseline](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/qlearning_agent.py): `pytorch_simulation/qlearning_agent.py`
- [Curriculum Attacks](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/curriculum_learning.py): `pytorch_simulation/curriculum_learning.py`

### Experiments

- [Confirmatory Runner](https://github.com/lambrooo/tirociniouni/blob/main/run_confirmatory_experiments.py): `run_confirmatory_experiments.py`
- [Campaign Archive](https://github.com/lambrooo/tirociniouni/tree/main/confirmatory_experiments/run_20260901_193850): `confirmatory_experiments/run_20260901_193850`
- [No-Entropy Archive](https://github.com/lambrooo/tirociniouni/tree/main/confirmatory_experiments/run_20260926_senza_entropia): `confirmatory_experiments/run_20260926_senza_entropia`
- [Reproducibility Archive](https://github.com/lambrooo/tirociniouni/tree/main/reproducibility/review_20260925): `reproducibility/review_20260925`

### Research Outputs

- [Run Metrics](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/simulation.py): `pytorch_simulation/simulation.py`
- [Statistical Analysis](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/statistical_analysis.py): `pytorch_simulation/statistical_analysis.py`
- [Experiment Dashboard](https://github.com/lambrooo/tirociniouni/blob/main/pytorch_simulation/dashboard.py): `pytorch_simulation/dashboard.py`
- [Thesis Figures](https://github.com/lambrooo/tirociniouni/blob/main/scripts/genera_figure.py): `scripts/genera_figure.py`
- [Parameter Exploration](https://github.com/lambrooo/tirociniouni/blob/main/scripts/esplora_parametri.py): `scripts/esplora_parametri.py`
- [Thesis Verification](https://github.com/lambrooo/tirociniouni/blob/main/scripts/verify_thesis.py): `scripts/verify_thesis.py`

### Other components

- **Researcher**

## Connections

- Researcher → Confirmatory Runner: starts campaign
- Confirmatory Runner → Scenario Traces: generates traces
- Confirmatory Runner → Fixed Inference: runs fixed agent
- Confirmatory Runner → Adaptive Inference: runs adaptive agent
- Confirmatory Runner → Plant Simulation: runs simulation
- Plant Simulation → Compromised Sensors: samples readings
- Compromised Sensors → Fixed Inference: provides observations
- Compromised Sensors → Adaptive Inference: provides observations
- Fixed Inference → Actuators: issues controls
- Adaptive Inference → Actuators: issues controls
- Plant Simulation → Confirmatory Runner: returns run data
- Confirmatory Runner → Campaign Archive: writes run artifacts
- Researcher → No-Entropy Archive: reviews results
- Confirmatory Runner → No-Entropy Archive: stores second condition
- Confirmatory Runner → Run Metrics: collects metrics
- Run Metrics → Statistical Analysis: analyzes outcomes
- Researcher → Experiment Dashboard: explores results
- Researcher → Parameter Exploration: runs exploration
- Campaign Archive → Thesis Figures: supplies archived CSVs
- Researcher → Thesis Figures: generates figures
- Campaign Archive → Thesis Verification: checks archived data
- Reproducibility Archive → Thesis Verification: compares replay
- Researcher → Q-Learning Baseline: selects baseline
- Researcher → Curriculum Attacks: configures attack stages