# phd-brown/cascade-entropy architecture

> Architecture diagram of the GitHub repository phd-brown/cascade-entropy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/phd-brown/cascade-entropy
- Repository: https://github.com/phd-brown/cascade-entropy

## Overview

cascade-entropy is a computational-physics research package for simulating cascading transmission-grid failures, evolving the network to generate blackout time series, and comparing electrical, statistical, and entropy-based diagnostics. Its main workflow builds a DC network, dispatches generation and served load, iterates outages and redispatch, then runs slow evolution and analyzes the resulting series. The README describes the physics and information-analysis streams as mostly separate, exchanging series through files; evolution’s documented entropy observable is an exception. Some links below rely on README descriptions or SOURCE INDEX references because excerpts are partial.

Main entry points: [`cascade_entropy/cascade.py`](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/cascade.py) (Daily cascade), [`cascade_entropy/analyse_entropie.py`](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/analyse_entropie.py) (Entropy analysis), [`cascade_entropy/entropie.py`](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/entropie.py) (Entropy measures), [`cascade_entropy/evolution.py`](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/evolution.py) (Slow evolution)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grid["Grid physics"]
  node_network["DC network<br/>[reseau.py]"]
  node_dispatch["Constrained dispatch<br/>[dispatch.py]"]
  node_regions["Carreras regions<br/>[carreras.py]"]
end

subgraph group_cascade["Failure simulation"]
  node_cascade_loop["Daily cascade<br/>[cascade.py]"]
  node_evolution["Slow evolution<br/>[evolution.py]"]
end

subgraph group_series["Series analysis"]
  node_reference_metrics["Reference indicators<br/>[indicateurs.py]"]
  node_series_analysis["Series analysis<br/>[analyse_series.py]"]
  node_replication["Carreras replication"]
end

subgraph group_info["Information diagnostics"]
  node_entropy["Entropy measures<br/>[entropie.py]"]
  node_entropy_analysis["Entropy analysis"]
  node_controls["Surrogate controls<br/>[controles.py]"]
  node_synthetic["Synthetic series<br/>[synthetiques.py]"]
  node_substitutes["Surrogate generators<br/>[substituts.py]"]
  node_validation["Input validation<br/>[_validation.py]"]
end

node_researcher(("Researcher"))
node_series_files["Series files"]
node_figures["Research figures<br/>[figures.py]"]

node_researcher -.->|"runs study"| node_replication
node_network -->|"supplies flows"| node_dispatch
node_regions -->|"sets demand"| node_cascade_loop
node_cascade_loop -->|"redispatches"| node_dispatch
node_cascade_loop -->|"calculates flows"| node_network
node_evolution -->|"simulates days"| node_cascade_loop
node_evolution -->|"computes observable"| node_entropy
node_replication -->|"runs cascades"| node_cascade_loop
node_evolution -.->|"writes series"| node_series_files
node_series_files -.->|"loads series"| node_series_analysis
node_series_files -.->|"loads series"| node_entropy_analysis
node_series_analysis -.->|"estimates Hurst"| node_reference_metrics
node_entropy_analysis -->|"calculates measures"| node_entropy
node_entropy_analysis -->|"uses surrogates"| node_substitutes
node_controls -->|"compares measures"| node_entropy
node_controls -->|"tests on series"| node_synthetic
node_entropy -->|"validates inputs"| node_validation
node_series_analysis -->|"validates inputs"| node_validation
node_entropy_analysis -.->|"plots results"| node_figures

click node_network "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/reseau.py"
click node_dispatch "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/dispatch.py"
click node_regions "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/carreras.py"
click node_cascade_loop "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/cascade.py"
click node_evolution "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/evolution.py"
click node_reference_metrics "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/indicateurs.py"
click node_series_analysis "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/analyse_series.py"
click node_replication "https://github.com/phd-brown/cascade-entropy/blob/main/scripts/05_reproduction_carreras.py"
click node_entropy "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/entropie.py"
click node_entropy_analysis "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/analyse_entropie.py"
click node_controls "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/controles.py"
click node_synthetic "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/synthetiques.py"
click node_substitutes "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/substituts.py"
click node_validation "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/_validation.py"
click node_figures "https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/figures.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_network,node_dispatch,node_regions toneBlue
class node_cascade_loop,node_evolution toneAmber
class node_reference_metrics,node_series_analysis,node_replication toneMint
class node_entropy,node_entropy_analysis,node_controls,node_synthetic,node_substitutes,node_validation toneRose
class node_researcher,node_series_files toneIndigo
class node_figures toneTeal
```

## Components

### Grid physics

- [DC network](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/reseau.py): `cascade_entropy/reseau.py`
- [Constrained dispatch](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/dispatch.py): `cascade_entropy/dispatch.py`
- [Carreras regions](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/carreras.py): `cascade_entropy/carreras.py`

### Failure simulation

- [Daily cascade](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/cascade.py): `cascade_entropy/cascade.py`
- [Slow evolution](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/evolution.py): `cascade_entropy/evolution.py`

### Series analysis

- [Reference indicators](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/indicateurs.py): `cascade_entropy/indicateurs.py`
- [Series analysis](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/analyse_series.py): `cascade_entropy/analyse_series.py`
- [Carreras replication](https://github.com/phd-brown/cascade-entropy/blob/main/scripts/05_reproduction_carreras.py): `scripts/05_reproduction_carreras.py`

### Information diagnostics

- [Entropy measures](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/entropie.py): `cascade_entropy/entropie.py`
- [Entropy analysis](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/analyse_entropie.py): `cascade_entropy/analyse_entropie.py`
- [Surrogate controls](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/controles.py): `cascade_entropy/controles.py`
- [Synthetic series](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/synthetiques.py): `cascade_entropy/synthetiques.py`
- [Surrogate generators](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/substituts.py): `cascade_entropy/substituts.py`
- [Input validation](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/_validation.py): `cascade_entropy/_validation.py`

### Other components

- **Researcher**
- **Series files**
- [Research figures](https://github.com/phd-brown/cascade-entropy/blob/main/cascade_entropy/figures.py): `cascade_entropy/figures.py`

## Connections

- Researcher → Carreras replication: runs study (evidence: `README.md`)
- DC network → Constrained dispatch: supplies flows (evidence: `cascade_entropy/dispatch.py`)
- Carreras regions → Daily cascade: sets demand (evidence: `cascade_entropy/carreras.py`)
- Daily cascade → Constrained dispatch: redispatches (evidence: `cascade_entropy/cascade.py`)
- Daily cascade → DC network: calculates flows (evidence: `cascade_entropy/cascade.py`)
- Slow evolution → Daily cascade: simulates days (evidence: `cascade_entropy/evolution.py`)
- Slow evolution → Entropy measures: computes observable (evidence: `cascade_entropy/evolution.py`)
- Carreras replication → Daily cascade: runs cascades (evidence: `scripts/05_reproduction_carreras.py`)
- Slow evolution → Series files: writes series (evidence: `README.md`)
- Series files → Series analysis: loads series (evidence: `README.md`)
- Series files → Entropy analysis: loads series (evidence: `README.md`)
- Series analysis → Reference indicators: estimates Hurst (evidence: `README.md`)
- Entropy analysis → Entropy measures: calculates measures (evidence: `cascade_entropy/analyse_entropie.py`)
- Entropy analysis → Surrogate generators: uses surrogates (evidence: `cascade_entropy/analyse_entropie.py`)
- Surrogate controls → Entropy measures: compares measures (evidence: `cascade_entropy/controles.py`)
- Surrogate controls → Synthetic series: tests on series (evidence: `cascade_entropy/controles.py`)
- Entropy measures → Input validation: validates inputs (evidence: `cascade_entropy/entropie.py`)
- Series analysis → Input validation: validates inputs (evidence: `cascade_entropy/analyse_series.py`)
- Entropy analysis → Research figures: plots results