# adamjamessheppard/lorenz-training-set architecture

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

- Interactive diagram: https://gitdiagram.com/adamjamessheppard/lorenz-training-set
- Repository: https://github.com/adamjamessheppard/lorenz-training-set

## Overview

This is a numerical-research solver for the forecast step of a continuous-discrete Bayesian filter on stochastic Lorenz-63, with sequential data-assimilation and dataset-generation capabilities. The main workflow is truth simulation and observations, density forecast, Bayesian analysis, then feeding the posterior into the next forecast; accepted forecast pairs can be exported into trajectory-safe datasets. The graph also shows positivity treatment and validation. Some solver internals and experiment wiring are unsampled, so those links are omitted unless documented in the README or shown in excerpts.

Main entry points: [`lorenz_fpe/dataset.py`](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/dataset.py) (Trajectory dataset), [`lorenz_fpe/core.py`](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py) (DG forecast solver), [`lorenz_fpe/validation.py`](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/validation.py) (Analytic and MC validation), [`solver.py`](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/solver.py) (Forecast entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model["Model and states"]
  node_truth["Truth simulator<br/>[core.py]"]
  node_observation["Observation model<br/>[core.py]"]
  node_density["Density state<br/>[core.py]"]
end

subgraph group_numerics["Forecast numerics"]
  node_forecast["DG forecast solver<br/>[core.py]"]
  node_positivity["Positivity limiter<br/>[afc.py]"]
  node_localqp["Local QP projection"]
  node_afc["AFC update<br/>[afc.py]"]
  node_forecast_cli["Forecast entry point<br/>[solver.py]"]
end

subgraph group_assimilation["Data assimilation"]
  node_analysis["Bayesian analysis<br/>[core.py]"]
end

subgraph group_data["Dataset and validation"]
  node_dataset["Trajectory dataset<br/>[dataset.py]"]
  node_dataset_cli["Dataset entry point"]
  node_validation["Analytic and MC validation<br/>[validation.py]"]
  node_finitevolume["Finite-volume reference<br/>[finite_volume.py]"]
end

node_user(("Research user"))

node_user -->|"runs forecast"| node_forecast_cli
node_forecast_cli -->|"invokes solver"| node_forecast
node_forecast -->|"advances density"| node_density
node_forecast -->|"limits density"| node_positivity
node_user -->|"starts generation"| node_dataset_cli
node_dataset_cli -->|"creates dataset"| node_dataset
node_dataset -->|"simulates truth"| node_truth
node_dataset -->|"configures observations"| node_observation
node_dataset -->|"forecasts posterior"| node_forecast
node_dataset -->|"updates forecast"| node_analysis
node_analysis -->|"returns posterior"| node_density
node_forecast -->|"projects Q2 state"| node_localqp
node_afc -->|"uses local projection"| node_localqp
node_validation -->|"validates solver"| node_forecast
node_validation -->|"compares reference"| node_finitevolume
node_dataset -->|"exports tensors"| node_density

click node_truth "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py"
click node_observation "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py"
click node_density "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py"
click node_forecast "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py"
click node_positivity "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/afc.py"
click node_localqp "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/local_projection.py"
click node_afc "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/afc.py"
click node_analysis "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py"
click node_dataset "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/dataset.py"
click node_dataset_cli "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/generate_dataset.py"
click node_validation "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/validation.py"
click node_finitevolume "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/finite_volume.py"
click node_forecast_cli "https://github.com/adamjamessheppard/lorenz-training-set/blob/main/solver.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_truth,node_observation,node_density,node_user toneBlue
class node_forecast,node_positivity,node_localqp,node_afc,node_forecast_cli toneAmber
class node_analysis toneMint
class node_dataset,node_dataset_cli,node_validation,node_finitevolume toneRose
```

## Components

### Model and states

- [Truth simulator](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py): `lorenz_fpe/core.py`
- [Observation model](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py): `lorenz_fpe/core.py`
- [Density state](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py): `lorenz_fpe/core.py`

### Forecast numerics

- [DG forecast solver](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py): `lorenz_fpe/core.py`
- [Positivity limiter](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/afc.py): `lorenz_fpe/afc.py`
- [Local QP projection](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/local_projection.py): `lorenz_fpe/local_projection.py`
- [AFC update](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/afc.py): `lorenz_fpe/afc.py`
- [Forecast entry point](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/solver.py): `solver.py`

### Data assimilation

- [Bayesian analysis](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/core.py): `lorenz_fpe/core.py`

### Dataset and validation

- [Trajectory dataset](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/dataset.py): `lorenz_fpe/dataset.py`
- [Dataset entry point](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/generate_dataset.py): `generate_dataset.py`
- [Analytic and MC validation](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/validation.py): `lorenz_fpe/validation.py`
- [Finite-volume reference](https://github.com/adamjamessheppard/lorenz-training-set/blob/main/lorenz_fpe/finite_volume.py): `lorenz_fpe/finite_volume.py`

### Other components

- **Research user**

## Connections

- Research user → Forecast entry point: runs forecast (evidence: `README.md`)
- Forecast entry point → DG forecast solver: invokes solver (evidence: `solver.py`)
- DG forecast solver → Density state: advances density (evidence: `README.md`)
- DG forecast solver → Positivity limiter: limits density (evidence: `README.md`)
- Research user → Dataset entry point: starts generation (evidence: `README.md`)
- Dataset entry point → Trajectory dataset: creates dataset (evidence: `generate_dataset.py`)
- Trajectory dataset → Truth simulator: simulates truth (evidence: `lorenz_fpe/dataset.py`)
- Trajectory dataset → Observation model: configures observations (evidence: `lorenz_fpe/dataset.py`)
- Trajectory dataset → DG forecast solver: forecasts posterior (evidence: `README.md`)
- Trajectory dataset → Bayesian analysis: updates forecast (evidence: `README.md`)
- Bayesian analysis → Density state: returns posterior (evidence: `README.md`)
- DG forecast solver → Local QP projection: projects Q2 state (evidence: `lorenz_fpe/local_projection.py`)
- AFC update → Local QP projection: uses local projection (evidence: `lorenz_fpe/afc.py`)
- Analytic and MC validation → DG forecast solver: validates solver (evidence: `lorenz_fpe/validation.py`)
- Analytic and MC validation → Finite-volume reference: compares reference (evidence: `lorenz_fpe/validation.py`)
- Trajectory dataset → Density state: exports tensors (evidence: `README.md`)
