# campusai/hamiltonian-generative-networks architecture

> Architecture diagram of the GitHub repository campusai/hamiltonian-generative-networks, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/campusai/hamiltonian-generative-networks
- Repository: https://github.com/campusai/hamiltonian-generative-networks

## Overview

##### Project type and purpose
- This is a research-oriented Python codebase implementing Hamiltonian Generative Networks (HGN). It provides:
- Physical environment simulators (“environments/”) for data generation.
- Neural network modules (“networks/”) for the encoder, transformer, Hamiltonian, and decoder.
- Utility functions (“utilities/”) for integration, data loading, logging, and loss computation.
- CLI scripts for dataset generation (generate_data.py), model definition (hamiltonian_generative_network.py), training (train.py), and sampling rollouts (sample_rollouts.py).
- Purpose: generate or load simulated physics datasets, train an HGN model end-to-end, and evaluate it.

##### File structure
- Top-level CLI scripts:
- generate_data.py → data creation (online/offline)
- train.py → orchestrates training with configs and CLI args
- sample_rollouts.py → model inference / visualization
- Core packages:
- environments/ → physical systems and a factory to instantiate them
- networks/ → PyTorch modules: encoder, transformer, Hamiltonian, decoder
- utilities/ → data conversions, integrator, loader, losses, logger, statistics
- Configuration:
- experiment_params/ → YAML templates for datasets, environments, and training
- Tests:
- tests/ → unit and gradient tests for modules and utilities

##### README for additional insights
- Dependencies: PyTorch, YAML, numpy, etc.
- Training modes:
- Online: simulate on the fly via environments + DataLoader
- Offline: load pre-generated datasets via loader utilities
- Core architecture described: encoder → transformer → Hamiltonian net → integrator → decoder

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        GD["generate_data.py"]:::scriptRect
        TR["train.py"]:::scriptRect
        SR["sample_rollouts.py"]:::scriptRect
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        direction TB
        DO["dataset_offline_default.yaml"]:::doc
        DI["dataset_online_default.yaml"]:::doc
        subgraph "Environment Params"
            direction TB
            CEP["chaotic_pendulum.yaml"]:::doc
            DEP["damped_spring.yaml"]:::doc
            PEN["pendulum.yaml"]:::doc
            SPR["spring.yaml"]:::doc
            TBODY["three_bodies.yaml"]:::doc
            UBODY["two_bodies.yaml"]:::doc
        end
        TD["train_config_default.yaml"]:::doc
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        EB["environment.py"]:::module
        EF["environment_factory.py"]:::module
        subgraph "Simulators"
            direction TB
            PENV["pendulum.py"]:::module
            CPENV["chaotic_pendulum.py"]:::module
            SPENV["spring.py"]:::module
            GVENV["gravity.py"]:::module
            DSENV["datasets.py"]:::module
        end
        DL["loader.py"]:::module
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        ENC["encoder_net.py"]:::module
        TRF["transformer_net.py"]:::module
        HAM["hamiltonian_net.py"]:::module
        DEC["decoder_net.py"]:::module
        DBG["debug_networks.py"]:::module
    end

    %% Computation Layer
    subgraph "Computation Layer"
        direction TB
        INTG["integrator.py"]:::util
    end

    %% Utility Functions
    subgraph "Utility Functions"
        direction TB
        CONV["conversions.py"]:::util
        GRAD["gradient_flow_utils.py"]:::util
        LOS["losses.py"]:::util
        STAT["statistics.py"]:::util
        LOG["training_logger.py"]:::util
        RES["hgn_result.py"]:::util
    end

    %% Test/Evaluation Layer
    subgraph "Test/Evaluation Layer"
        direction TB
        CG["check_gradients.py"]:::test
        GS["grid_search.py"]:::test
        TC["test_conversions.py"]:::test
        TDCP["test_decoder.py"]:::test
        TINF["test_inference_net.py"]:::test
        TLS["test_losses.py"]:::test
        TNW["test_networks.py"]:::test
    end

    %% External Dependencies
    subgraph "External Services"
        direction TB
        PT["PyTorch"]:::external
        YML["YAML Parser"]:::external
        FS["File System"]:::external
        NP["NumPy/SciPy"]:::external
    end

    %% Connections
    %% CLI reads config
    DO -->|reads| GD
    DI -->|reads| GD
    CEP -->|reads| GD
    TD -->|reads| TR
    %% CLI to Data Layer
    GD -->|instantiates via| EF
    TR -->|loads data via| DL
    SR -->|loads model & env| EF

    %% Environment Factory relations
    EF --> EB
    EF --> PENV
    EF --> CPENV
    EF --> SPENV
    EF --> GVENV
    EF --> DSENV

    %% Data to Model
    DL --> ENC
    DL --> TRF
    DL --> HAM
    DL --> DEC

    %% Model Pipeline
    ENC --> TRF
    TRF --> HAM
    HAM --> INTG
    INTG --> DEC

    %% Utilities in Training
    LOS --> TR
    GRAD --> TR
    CONV --> GD
    STAT --> TR
    LOG --> TR
    RES --> TR

    %% External deps usage
    ENC --> PT
    TRF --> PT
    HAM --> PT
    DEC --> PT
    INTG --> NP
    EB --> NP
    DO --> FS
    DI --> FS
    TD --> FS

    %% Evaluation tests
    CG --> HAM
    GS --> TR
    TC --> CONV
    TDCP --> DEC
    TINF --> ENC
    TLS --> LOS
    TNW --> DBG

    %% Sample rollouts
    SR --> DEC
    SR --> EF

    %% Click Events
    click GD "https://github.com/campusai/hamiltonian-generative-networks/blob/master/generate_data.py"
    click TR "https://github.com/campusai/hamiltonian-generative-networks/blob/master/train.py"
    click SR "https://github.com/campusai/hamiltonian-generative-networks/blob/master/sample_rollouts.py"
    click DO "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/dataset_offline_default.yaml"
    click DI "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/dataset_online_default.yaml"
    click CEP "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/default_environments/chaotic_pendulum.yaml"
    click DEP "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/default_environments/damped_spring.yaml"
    click PEN "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/default_environments/pendulum.yaml"
    click SPR "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/default_environments/spring.yaml"
    click TBODY "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/default_environments/three_bodies.yaml"
    click UBODY "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/default_environments/two_bodies.yaml"
    click TD "https://github.com/campusai/hamiltonian-generative-networks/blob/master/experiment_params/train_config_default.yaml"
    click EB "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/environment.py"
    click EF "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/environment_factory.py"
    click PENV "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/pendulum.py"
    click CPENV "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/chaotic_pendulum.py"
    click SPENV "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/spring.py"
    click GVENV "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/gravity.py"
    click DSENV "https://github.com/campusai/hamiltonian-generative-networks/blob/master/environments/datasets.py"
    click DL "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/loader.py"
    click ENC "https://github.com/campusai/hamiltonian-generative-networks/blob/master/networks/encoder_net.py"
    click TRF "https://github.com/campusai/hamiltonian-generative-networks/blob/master/networks/transformer_net.py"
    click HAM "https://github.com/campusai/hamiltonian-generative-networks/blob/master/networks/hamiltonian_net.py"
    click DEC "https://github.com/campusai/hamiltonian-generative-networks/blob/master/networks/decoder_net.py"
    click DBG "https://github.com/campusai/hamiltonian-generative-networks/blob/master/networks/debug_networks.py"
    click INTG "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/integrator.py"
    click CONV "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/conversions.py"
    click GRAD "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/gradient_flow_utils.py"
    click LOS "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/losses.py"
    click STAT "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/statistics.py"
    click LOG "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/training_logger.py"
    click RES "https://github.com/campusai/hamiltonian-generative-networks/blob/master/utilities/hgn_result.py"
    click CG "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/check_gradients.py"
    click GS "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/grid_search.py"
    click TC "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/test_conversions.py"
    click TDCP "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/test_decoder.py"
    click TINF "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/test_inference_net.py"
    click TLS "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/test_losses.py"
    click TNW "https://github.com/campusai/hamiltonian-generative-networks/blob/master/tests/test_networks.py"

    %% Styles
    classDef scriptRect fill:#FFD700,stroke:#333,stroke-width:1px;
    classDef doc fill:#F0E68C,stroke:#333,stroke-width:1px;
    classDef module fill:#87CEFA,stroke:#333,stroke-width:1px;
    classDef util fill:#90EE90,stroke:#333,stroke-width:1px;
    classDef test fill:#FFB6C1,stroke:#333,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#333,stroke-width:1px;
```
