# mit-realm/neuralfaultdetector architecture

> Architecture diagram of the GitHub repository mit-realm/neuralfaultdetector, 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/mit-realm/neuralfaultdetector
- Repository: https://github.com/mit-realm/neuralfaultdetector

## Overview

FTneuralCBF is a research toolbox for learning safe control and fault detection/isolation (FDI), illustrated with Crazyflie dynamics. The principal workflow is to define a control-affine system, train a control-barrier-function (CBF) and controller or train an FDI model from simulated fault trajectories, then evaluate FDI performance. The graph distinguishes those domain stages and the shared trainer/data/model layer. The README documents the broader workflow; sampled excerpts support Crazyflie simulation, trajectory-buffer use, and Gamma training, but do not establish every training script’s internal wiring.

Main entry points: [`train/CF_train_Gamma_Output.py`](https://github.com/mit-realm/neuralfaultdetector/blob/main/train/CF_train_Gamma_Output.py) (Gamma FDI training), [`trainer/trainer.py`](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/trainer.py) (Optimization trainer), [`train/Crazyflie_train_new.py`](https://github.com/mit-realm/neuralfaultdetector/blob/main/train/Crazyflie_train_new.py) (CBF + control training), [`dynamics/Crazyflie.py`](https://github.com/mit-realm/neuralfaultdetector/blob/main/dynamics/Crazyflie.py) (Crazyflie model)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_system["System dynamics"]
  node_base_dynamics["Control-affine base"]
  node_crazyflie["Crazyflie model<br/>[Crazyflie.py]"]
end

subgraph group_control["Safe control"]
  node_control_training["CBF + control training"]
  node_cbf["CBF model<br/>[CBF.py]"]
end

subgraph group_fdi["Fault isolation"]
  node_fdi_training["Gamma FDI training"]
  node_fdi_variants["Gamma variants"]
  node_fdi_evaluation["FDI evaluation"]
end

subgraph group_learning["Learning internals"]
  node_trainer["Optimization trainer<br/>[trainer.py]"]
  node_networks["Neural architectures<br/>[NNfuncgrad_CF.py]"]
  node_dataset[("Trajectory buffer<br/>[datagen.py]")]
  node_constraints["Barrier constraints"]
  node_lie["Lie derivatives<br/>[lie_der.py]"]
  node_utilities["Training utilities<br/>[utils.py]"]
end

node_engineer(("Researcher"))

node_engineer -->|"defines system"| node_base_dynamics
node_engineer -->|"configures training"| node_control_training
node_engineer -->|"configures training"| node_fdi_training
node_engineer -->|"runs evaluation"| node_fdi_evaluation
node_crazyflie -->|"extends dynamics"| node_base_dynamics
node_control_training -->|"simulates system"| node_crazyflie
node_control_training -->|"trains CBF/control"| node_trainer
node_control_training -->|"uses barrier model"| node_cbf
node_fdi_training -->|"simulates fault trajectories"| node_crazyflie
node_fdi_training -->|"adds trajectories"| node_dataset
node_fdi_training -->|"trains Gamma"| node_trainer
node_fdi_training -->|"instantiates Gamma"| node_networks
node_fdi_training -->|"loads CBF weights"| node_cbf
node_fdi_variants -.->|"defines variants"| node_networks
node_fdi_evaluation -.->|"evaluates models"| node_networks
node_trainer -->|"samples batches"| node_dataset
node_trainer -->|"updates models"| node_networks
node_trainer -->|"computes dynamics"| node_crazyflie
node_constraints -->|"computes derivatives"| node_lie

click node_base_dynamics "https://github.com/mit-realm/neuralfaultdetector/blob/main/dynamics/control_affine_system_new.py"
click node_crazyflie "https://github.com/mit-realm/neuralfaultdetector/blob/main/dynamics/Crazyflie.py"
click node_control_training "https://github.com/mit-realm/neuralfaultdetector/blob/main/train/Crazyflie_train_new.py"
click node_cbf "https://github.com/mit-realm/neuralfaultdetector/blob/main/train/CBF.py"
click node_fdi_training "https://github.com/mit-realm/neuralfaultdetector/blob/main/train/CF_train_Gamma_Output.py"
click node_fdi_variants "https://github.com/mit-realm/neuralfaultdetector/tree/main/train"
click node_fdi_evaluation "https://github.com/mit-realm/neuralfaultdetector/blob/main/test/CF_test_Gamma_compare_NNs_output.py"
click node_trainer "https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/trainer.py"
click node_networks "https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/NNfuncgrad_CF.py"
click node_dataset "https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/datagen.py"
click node_constraints "https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/constraints_crazy.py"
click node_lie "https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/lie_der.py"
click node_utilities "https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/utils.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_base_dynamics,node_crazyflie toneBlue
class node_control_training,node_cbf toneAmber
class node_fdi_training,node_fdi_variants,node_fdi_evaluation toneMint
class node_trainer,node_networks,node_dataset,node_constraints,node_lie,node_utilities toneRose
class node_engineer toneIndigo
```

## Components

### System dynamics

- [Control-affine base](https://github.com/mit-realm/neuralfaultdetector/blob/main/dynamics/control_affine_system_new.py): `dynamics/control_affine_system_new.py`
- [Crazyflie model](https://github.com/mit-realm/neuralfaultdetector/blob/main/dynamics/Crazyflie.py): `dynamics/Crazyflie.py`

### Safe control

- [CBF + control training](https://github.com/mit-realm/neuralfaultdetector/blob/main/train/Crazyflie_train_new.py): `train/Crazyflie_train_new.py`
- [CBF model](https://github.com/mit-realm/neuralfaultdetector/blob/main/train/CBF.py): `train/CBF.py`

### Fault isolation

- [Gamma FDI training](https://github.com/mit-realm/neuralfaultdetector/blob/main/train/CF_train_Gamma_Output.py): `train/CF_train_Gamma_Output.py`
- [Gamma variants](https://github.com/mit-realm/neuralfaultdetector/tree/main/train): `train`
- [FDI evaluation](https://github.com/mit-realm/neuralfaultdetector/blob/main/test/CF_test_Gamma_compare_NNs_output.py): `test/CF_test_Gamma_compare_NNs_output.py`

### Learning internals

- [Optimization trainer](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/trainer.py): `trainer/trainer.py`
- [Neural architectures](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/NNfuncgrad_CF.py): `trainer/NNfuncgrad_CF.py`
- [Trajectory buffer](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/datagen.py): `trainer/datagen.py`
- [Barrier constraints](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/constraints_crazy.py): `trainer/constraints_crazy.py`
- [Lie derivatives](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/lie_der.py): `trainer/lie_der.py`
- [Training utilities](https://github.com/mit-realm/neuralfaultdetector/blob/main/trainer/utils.py): `trainer/utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Control-affine base: defines system
- Researcher → CBF + control training: configures training
- Researcher → Gamma FDI training: configures training
- Researcher → FDI evaluation: runs evaluation
- Crazyflie model → Control-affine base: extends dynamics
- CBF + control training → Crazyflie model: simulates system
- CBF + control training → Optimization trainer: trains CBF/control
- CBF + control training → CBF model: uses barrier model
- Gamma FDI training → Crazyflie model: simulates fault trajectories
- Gamma FDI training → Trajectory buffer: adds trajectories
- Gamma FDI training → Optimization trainer: trains Gamma
- Gamma FDI training → Neural architectures: instantiates Gamma
- Gamma FDI training → CBF model: loads CBF weights
- Gamma variants → Neural architectures: defines variants
- FDI evaluation → Neural architectures: evaluates models
- Optimization trainer → Trajectory buffer: samples batches
- Optimization trainer → Neural architectures: updates models
- Optimization trainer → Crazyflie model: computes dynamics
- Barrier constraints → Lie derivatives: computes derivatives