# stan-dev/stan architecture

> Architecture diagram of the GitHub repository stan-dev/stan, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stan-dev/stan
- Repository: https://github.com/stan-dev/stan

## Overview

##### Project Type & Purpose
- Stan is a C++ probabilistic programming library that provides full Bayesian inference (via the No-U-Turn Sampler, a variant of Hamiltonian Monte Carlo), approximate Bayesian inference using automatic differentiation variational inference (ADVI), and penalized maximum likelihood optimization (via L-BFGS).
- Its design is centered on high-performance statistical computation and automatic differentiation, with a clear separation between the modeling language, mathematical back-end (Stan Math), and various inference engines.

##### Main Architectural Components
a. Core Libraries & External Dependencies:
– Stan Math Library (providing autodiff, linear algebra, probability functions)
– RapidJSON (for JSON parsing and serialization in the IO components)
– External libraries like Intel TBB (for parallelism; note the licensing implications)
b. Subsystems within the Stan Code Base:
– Model & Language Parsing: The files in src/stan/lang indicate a domain-specific language parser that processes Stan models.
– Inference & Sampling Engines: Multiple directories under src/stan/mcmc (including hmc, nuts, static, etc.) represent the implementation of various sampling methods like HMC/NUTS.
– Variational Inference: The src/stan/variational directory houses the ADVI implementation.
– Optimization: The src/stan/optimization directory provides methods (e.g., L-BFGS, Newton) for penalized MLE.
– IO & Data Handling: Components in src/stan/io for reading, writing, and serializing data (including CSV and JSON support) are key to interfacing with models and external tools.
– Services Layer: Located in src/stan/services, these modules wrap specific tasks (diagnose, optimize, sample, pathfinder) that use the underlying model/sampler implementations.
– Callbacks & Logging: Support for handling output and logging is implemented in src/stan/callbacks.
c. Testing & Documentation:
– Extensive unit tests, integration tests, and Doxygen-based documentation (under src/doxygen and src/test) ensure robustness.
– The make and Jenkinsfile build configurations point to an organized CI/CD and documentation generation process.

##### Relationships and Data Flow
- The input (model definition in the Stan DSL) is parsed in the language module (src/stan/lang), which then constructs an internal model representation.
- The model is passed on to the inference subsystems, where different engines handle sampling (MCMC), variational inference (ADVI), or optimization.
- Underneath, the Stan Math library provides the gradient and autodiff capabilities needed by these engines.
- Data IO components manage input/output transfers, supporting JSON, CSV, and other formats.
- Callbacks and logging are integrated to capture the execution diagnostics and trace outputs through the pipeline.
- Finally, testing and documentation (including Doxygen) form supporting layers around the core components.

## Diagram (Mermaid)

```mermaid
graph TD
    %% External Interfaces
    E["External Interfaces (R,Python,Matlab)"]:::interface

    %% Modeling Layer
    MI["Model Input (Stan DSL)"]:::modeling
    MLP["Model & Language Parsing"]:::modeling

    %% Computational Core
    STMath["Stan Math Library"]:::computational
    RJSON["RapidJSON (IO Parsing)"]:::computational

    %% Inference Engines
    MCMC["Inference & Sampling Engines (MCMC/NUTS)"]:::inference
    ADVI["Variational Inference (ADVI)"]:::inference
    OPT["Optimization Engine (L-BFGS)"]:::inference

    %% IO and Services Layers
    IO["IO & Data Handling"]:::io
    SERV["Services Layer (diagnose,optimize,sample,pathfinder)"]:::services
    CALL["Callbacks & Logging"]:::callbacks

    %% Testing and Documentation
    TEST["Testing & Documentation"]:::testing

    %% Data Flow
    E -->|"inputs"| MI
    MI -->|"parses_to"| MLP
    MLP -->|"constructs_model"| MCMC
    MLP -->|"constructs_model"| ADVI
    MLP -->|"constructs_model"| OPT

    %% Computational Dependencies
    STMath -->|"provides_autodiff"| MCMC
    STMath -->|"provides_autodiff"| ADVI
    STMath -->|"provides_autodiff"| OPT
    RJSON -->|"parses_formats"| IO

    %% Output Flow
    MCMC -->|"outputs_data"| IO
    ADVI -->|"outputs_data"| IO
    OPT -->|"outputs_data"| IO

    IO -->|"feeds"| SERV
    SERV -->|"logs_via"| CALL

    %% Testing Integration
    TEST -->|"validates"| MLP
    TEST -->|"tests"| MCMC
    TEST -->|"tests"| ADVI
    TEST -->|"tests"| OPT
    TEST -->|"tests"| IO
    TEST -->|"tests"| SERV

    %% Click Events
    click STMath "https://github.com/stan-dev/stan/tree/develop/lib/stan_math"
    click RJSON "https://github.com/stan-dev/stan/blob/develop/lib/rapidjson_1.1.0"
    click MLP "https://github.com/stan-dev/stan/tree/develop/src/stan/lang"
    click MCMC "https://github.com/stan-dev/stan/tree/develop/src/stan/mcmc"
    click ADVI "https://github.com/stan-dev/stan/tree/develop/src/stan/variational"
    click OPT "https://github.com/stan-dev/stan/tree/develop/src/stan/optimization"
    click IO "https://github.com/stan-dev/stan/tree/develop/src/stan/io"
    click SERV "https://github.com/stan-dev/stan/tree/develop/src/stan/services"
    click CALL "https://github.com/stan-dev/stan/tree/develop/src/stan/callbacks"
    click TEST "https://github.com/stan-dev/stan/tree/develop/src/doxygen"
    click TEST "https://github.com/stan-dev/stan/tree/develop/src/test"

    %% Styles
    classDef interface fill:#FFDD99,stroke:#333,stroke-width:2px;
    classDef modeling fill:#AADDFF,stroke:#333,stroke-width:2px;
    classDef computational fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef inference fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef io fill:#DDEEFF,stroke:#333,stroke-width:2px;
    classDef services fill:#FFE6FF,stroke:#333,stroke-width:2px;
    classDef callbacks fill:#FFCFFC,stroke:#333,stroke-width:2px;
    classDef testing fill:#CCFFFF,stroke:#333,stroke-width:2px;
```
