# n-gao/neural-pfaffian architecture

> Architecture diagram of the GitHub repository n-gao/neural-pfaffian, 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/n-gao/neural-pfaffian
- Repository: https://github.com/n-gao/neural-pfaffian

## Overview

##### Project Type and Purpose
- This is a scientific computing and machine learning project for quantum chemistry applications. Its purpose is to provide various neural network architectures (like FermiNet, PsiFormer, and Moon) to model electron wave functions accurately.
- The README emphasizes different calculation types (single structure, PES surfaces, etc.) that set off different configurations.

##### Main Components
a. Command Interfaces:
- The main entry point is through the “neural_pfaffian” command (executed via the __main__.py entrypoint in src/neural_pfaffian). Illustrate how command-line arguments (configuration files) trigger the execution.

b. Configuration and Modular System:
- Configuration hierarchy split into “configs/models”, “configs/systems”, and “configs/seml”. These files dictate which model (e.g., psiformer, pesnet, ferminet) and experiment setup (e.g., single or PES-based calculations) are run.
- Mention the modular design that allows the user to swap configurations freely, tailoring the wave functions and system properties.

c. Core Computational Modules:
- Data handling (src/neural_pfaffian/data) with datasets like “deeperwin” for geometries and other quantum properties.
- Model and neural network definitions (under src/neural_pfaffian/nn). Include components such as antisymmetrizers (pfaffian.py, slater.py), embedding modules (for each of FermiNet, PsiFormer, Moon) and other network utilities.
- Physics-related routines such as the Hamiltonian, MCMC sampling (mcmc.py), variational Monte Carlo (vmc.py), and preconditioning.
- Utility modules (logger, linear algebra, optimization, etc.) that support the core calculations.

d. Execution and Experiment Management:

e. Testing and CI/CD:
- Automated workflows located in .github/workflows (pre-commit and test pipelines). Also include test directories that verify the functionality of different computational modules.

##### Relationships and Data Flow
- That through the command-line interface, the application dispatches work to:
- Data loading -> Neural network computations (embedding, antisymmetrizer) -> Physical solvers (Hamiltonian, MCMC, VMC) -> Output/logging.
- That the experimental manager (“seml”) coordinates the overall experiment life-cycle, interfacing with the core pipeline.

##### Architectural Patterns and Relevant Technologies
- A modular architecture that separates configuration, data handling, model building, and physical simulations.
- That the project also includes continuous integration and adherence to a configuration-driven design (YAML files in config and pyproject.toml indicate structured dependency management).
- Design principles such as separation-of-concerns (e.g., neural network models vs. physical simulations), flexibility via configuration, and an extensible testing framework.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Layer
    subgraph "Configuration"
        conf1["Project Config (config/models, config/systems, config/seml)"]:::config
        conf2["Default Config (src/neural_pfaffian/config/default.yaml)"]:::config
    end

    %% Command Interface Layer
    subgraph "Command Interface"
        cli["neural_pfaffian Command (__main__.py)"]:::cli
    end

    %% Experiment Management Layer
    subgraph "Experiment Management"
        seml["Experiment Manager (seml) (config/seml/train_n2.yaml)"]:::exp
    end

    %% Core Computational Modules Layer
    subgraph "Core Computational Modules"
        dh["Data Handling Module (src/neural_pfaffian/data)"]:::data

        subgraph "Neural Network Module"
            nn["Core NN Definitions (src/neural_pfaffian/nn)"]:::nn
            antisym_pf["Antisymmetrizer: Pfaffian (src/neural_pfaffian/nn/antisymmetrizer/pfaffian.py)"]:::antisym
            antisym_sl["Antisymmetrizer: Slater (src/neural_pfaffian/nn/antisymmetrizer/slater.py)"]:::antisym
            embed_f["Embedding: FermiNet (src/neural_pfaffian/nn/embedding/ferminet.py)"]:::embedding
            embed_p["Embedding: PsiFormer (src/neural_pfaffian/nn/embedding/psiformer.py)"]:::embedding
            embed_m["Embedding: Moon (src/neural_pfaffian/nn/embedding/moon.py)"]:::embedding
        end

        subgraph "Physics Routines"
            ham["Hamiltonian Solver (src/neural_pfaffian/hamiltonian.py)"]:::physics
            mcmc["MCMC Engine (src/neural_pfaffian/mcmc.py)"]:::physics
            vmc["VMC Engine (src/neural_pfaffian/vmc.py)"]:::physics
        end

        subgraph "Utility Modules"
            log["Logger (src/neural_pfaffian/logger.py)"]:::util
            lin["Linear Algebra (src/neural_pfaffian/linalg.py)"]:::util
            util["Utils (src/neural_pfaffian/utils)"]:::util
        end
    end

    %% Testing and CI/CD Layer
    subgraph "Testing & CI/CD"
        cwf["CI/CD Workflows (.github/workflows)"]:::ci
        test["Test Suite (test)"]:::ci
    end

    %% Relationships and Data Flow
    conf1 --> cli
    conf2 --> cli
    seml --> cli

    cli --> dh
    cli --> nn
    cli --> ham
    cli --> mcmc
    cli --> vmc

    dh --> nn
    nn --> ham
    nn --> mcmc
    nn --> vmc

    ham --> log
    mcmc --> log
    vmc --> log

    %% Click Events
    click cli "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/__main__.py"
    click conf1 "https://github.com/n-gao/neural-pfaffian/tree/main/config/models"
    click conf1 "https://github.com/n-gao/neural-pfaffian/tree/main/config/systems"
    click conf1 "https://github.com/n-gao/neural-pfaffian/tree/main/config/seml"
    click conf2 "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/config/default.yaml"
    click dh "https://github.com/n-gao/neural-pfaffian/tree/main/src/neural_pfaffian/data"
    click nn "https://github.com/n-gao/neural-pfaffian/tree/main/src/neural_pfaffian/nn"
    click antisym_pf "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/nn/antisymmetrizer/pfaffian.py"
    click antisym_sl "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/nn/antisymmetrizer/slater.py"
    click embed_f "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/nn/embedding/ferminet.py"
    click embed_p "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/nn/embedding/psiformer.py"
    click embed_m "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/nn/embedding/moon.py"
    click ham "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/hamiltonian.py"
    click mcmc "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/mcmc.py"
    click vmc "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/vmc.py"
    click log "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/logger.py"
    click lin "https://github.com/n-gao/neural-pfaffian/blob/main/src/neural_pfaffian/linalg.py"
    click util "https://github.com/n-gao/neural-pfaffian/tree/main/src/neural_pfaffian/utils"
    click seml "https://github.com/n-gao/neural-pfaffian/blob/main/config/seml/train_n2.yaml"
    click cwf "https://github.com/n-gao/neural-pfaffian/tree/main/.github/workflows"
    click test "https://github.com/n-gao/neural-pfaffian/tree/main/test"

    %% Styles
    classDef cli fill:#D5F5E3,stroke:#1D8348,stroke-width:2px;
    classDef config fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef exp fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef data fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef nn fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef antisym fill:#F5CBA7,stroke:#943126,stroke-width:2px;
    classDef embedding fill:#FCF3CF,stroke:#B9770E,stroke-width:2px;
    classDef physics fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef util fill:#D6EAF8,stroke:#2E86C1,stroke-width:2px;
    classDef ci fill:#F5B7B1,stroke:#C0392B,stroke-width:2px;
```
