# thomasple/fennol architecture

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

- Interactive diagram: https://gitdiagram.com/thomasple/fennol
- Repository: https://github.com/thomasple/fennol

## Overview

##### Project type and purpose
- FeNNol is a Python library (full-stack library/tool) for:
– Building, training, and running neural network potentials for molecular simulations
– Leveraging JAX as its primary execution engine
– Offering optional extensions via e3nn-jax, PyTorch dataloaders, and Deep-HP (cffi/pycuda)
- It provides two primary use cases:
a) A training pipeline to generate models from datasets
b) A molecular-dynamics (MD) engine to run simulations with pre-trained models

##### File structure
Top-level organization
- .github/workflows – CI for docs generation and PyPI publishing
- examples/ – example scripts for training and MD use cases
- src/fennol/ – core library code, subdivided into:
– analyze, ase (ASE integration), md (simulation routines), models, preprocessing, training, utils
- pdoc_templates/ – HTML templates for auto-generated docs
- pyproject.toml, Makefile, LICENSE, README.md – packaging, build & metadata
Patterns & configuration
- src/fennol/models/embeddings – plugin-style registry of many embedding backends
- src/fennol/models/physics – force-field physics modules (bond, electrostatics…)
- src/fennol/training – end-to-end training pipeline (data loaders, optimizers…)
- src/fennol/md – MD integrator, thermostats, barostats, collective variables

##### README for architecture hints
- Confirms dual functionality (model training & MD simulations)
- Lists core dependencies (JAX, optional e3nn-jax, PyTorch, cffi/pycuda)
- Points to examples for both major paths

##### Main components & their interactions
a) User Interface
– Python API (import fennol…)
– CLI entry points (scripts in examples, `make`, `pip install fennol`)
b) Core Library
1. Input Parser & Preprocessor
- Parses Fennel input files (`.fnl`), XYZ geometries
- Standardizes data structures for training & MD
2. Model Builder
- Embedding registry (ANI, SchNet, MACE, …)
- Physics modules for force-field coupling
- Preprocessing hooks (normalization, neighbor lists)
3. Training Engine
- Datasets & dataloaders (PyTorch optional)
- JAX-based forward/backward passes
- Optimizers, checkpointing
4. MD Engine
- Integrator (Velocity-Verlet, etc.)
- Thermostats, Barostats, Collective Variables
- In-flight analysis (RDF, spectra)
5. Utilities
- Units conversion, IO, spherical harmonics, atomic properties
c) External Dependencies
– JAX (core compute)
– Optional: e3nn-jax, PyTorch, cffi, pycuda
– ASE (via src/fennol/ase.py)
d) CI / Packaging / Docs
– GitHub workflows → docs published & PyPI releases
– pdoc_templates → auto-generated API reference
– pyproject.toml, Makefile

- The User Interface → Core Library modules
- Model Builder ↔ Physics modules & Embeddings
- Training Engine → JAX (compute)
- MD Engine → JAX & Utilities
- Examples invoke either Training or MD Engine

##### Architectural patterns & design principles
- Layered architecture (Input → Model → Execution → Analysis)
- Plugin registry (embedding backends loaded dynamically)
- Separation of concerns: physics vs. neural networks vs. I/O
- Extensible “optional dependencies” design (e3nn, PyTorch, Deep-HP)
- CI/CD pipelines for documentation and package distribution

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Interface
    subgraph "User Interface"
        Examples["Examples Directory"]:::example
        ASE["CLI & ASE Integration"]:::external
    end

    %% Preprocessing Layer
    subgraph "Preprocessing Layer"
        InputParser["Input Parser & Preprocessor"]:::core
        PreprocessingHooks["Data Standardization & Preprocessing Hooks"]:::core
    end

    %% Model Builder Layer
    subgraph "Model Builder"
        subgraph "Embeddings"
            EmbeddingRegistry["Embedding Registry"]:::core
            Aimnet["aimnet Backend"]:::core
            Schnet["schnet Backend"]:::core
        end
        subgraph "Physics Modules"
            Bond["Bond Interactions"]:::core
            Electrostatics["Electrostatics"]:::core
            Dispersion["Dispersion"]:::core
        end
        ModelDefs["Model Definitions & Utilities"]:::core
        ModelInspect["Model Inspection Utilities"]:::core
    end

    %% Execution Layer
    subgraph "Execution Layer"
        subgraph "Training Pipeline"
            TrainingEngine["Training Engine"]:::pipeline
        end
        subgraph "MD Pipeline"
            MDEngine["MD Engine"]:::pipeline
        end
    end

    %% Shared Utilities
    subgraph "Shared Utilities"
        Units["Unit Conversions"]:::core
        IOUtils["I/O Utilities"]:::core
        Spherical["Spherical Harmonics"]:::core
        Periodic["Periodic Table Data"]:::core
        Activations["Activation Functions"]:::core
        Initializers["Initialization Routines"]:::core
        Kspace["K-space Utilities"]:::core
    end

    %% External Dependencies
    subgraph "External Dependencies"
        JAX["JAX"]:::external
        PyTorch["PyTorch"]:::external
        E3NN["e3nn-jax"]:::external
        DeepHP["cffi/pycuda"]:::external
    end

    %% CI/CD & Documentation
    subgraph "CI/CD & Docs"
        Workflows["GitHub Actions Workflows"]:::ci
        Templates["API Doc Templates"]:::ci
        Meta["Build & Metadata"]:::ci
    end

    %% Connections
    Examples -->|uses| InputParser
    Examples -->|invokes| TrainingEngine
    Examples -->|invokes| MDEngine
    ASE -->|integrates| InputParser

    InputParser -->|feeds| PreprocessingHooks
    PreprocessingHooks -->|configures| EmbeddingRegistry
    PreprocessingHooks -->|configures| Bond

    EmbeddingRegistry <-->|uses| Bond
    EmbeddingRegistry <-->|uses| Electrostatics
    EmbeddingRegistry <-->|uses| Dispersion
    EmbeddingRegistry -->|builds| ModelDefs
    PhysicsModules -->|couples| ModelDefs

    ModelDefs -->|provides| TrainingEngine
    ModelDefs -->|provides| MDEngine
    ModelInspect -->|inspects| ModelDefs

    TrainingEngine -->|executes| JAX
    TrainingEngine -.->|optional| PyTorch
    TrainingEngine -->|stores| IOUtils

    MDEngine -->|executes| JAX
    MDEngine -->|uses| Units
    MDEngine -->|uses| IOUtils
    MDEngine -->|uses| Spherical
    MDEngine -->|uses| Periodic
    MDEngine -->|uses| Activations
    MDEngine -->|uses| Initializers
    MDEngine -->|uses| Kspace
    MDEngine -.->|optional| DeepHP

    ModelBuilder ---|optional| E3NN

    Workflows -->|publishes docs| Templates
    Workflows -->|publishes package| Meta
    Templates -->|generate| ModelDefs

    %% Click Events
    click Examples "https://github.com/thomasple/fennol/tree/main/examples/"
    click ASE "https://github.com/thomasple/fennol/blob/main/src/fennol/ase.py"
    click InputParser "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/input_parser.py"
    click PreprocessingHooks "https://github.com/thomasple/fennol/blob/main/src/fennol/models/preprocessing.py"
    click EmbeddingRegistry "https://github.com/thomasple/fennol/tree/main/src/fennol/models/embeddings/"
    click Aimnet "https://github.com/thomasple/fennol/blob/main/src/fennol/models/embeddings/aimnet.py"
    click Schnet "https://github.com/thomasple/fennol/blob/main/src/fennol/models/embeddings/schnet.py"
    click Bond "https://github.com/thomasple/fennol/blob/main/src/fennol/models/physics/bond.py"
    click Electrostatics "https://github.com/thomasple/fennol/blob/main/src/fennol/models/physics/electrostatics.py"
    click Dispersion "https://github.com/thomasple/fennol/blob/main/src/fennol/models/physics/dispersion.py"
    click ModelDefs "https://github.com/thomasple/fennol/blob/main/src/fennol/models/modules.py"
    click ModelInspect "https://github.com/thomasple/fennol/blob/main/src/fennol/models/inspect.py"
    click TrainingEngine "https://github.com/thomasple/fennol/tree/main/src/fennol/training/"
    click MDEngine "https://github.com/thomasple/fennol/tree/main/src/fennol/md/"
    click Units "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/atomic_units.py"
    click IOUtils "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/io.py"
    click Spherical "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/spherical_harmonics.py"
    click Periodic "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/periodic_table.py"
    click Activations "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/activations.py"
    click Initializers "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/initializers.py"
    click Kspace "https://github.com/thomasple/fennol/blob/main/src/fennol/utils/kspace.py"
    click E3NN "https://github.com/thomasple/fennol/blob/main/src/fennol/models/misc/e3.py"
    click Workflows "https://github.com/thomasple/fennol/blob/main/.github/workflows/docs.yaml"
    click Templates "https://github.com/thomasple/fennol/tree/main/pdoc_templates/"
    click Meta "https://github.com/thomasple/fennol/blob/main/pyproject.toml"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef external fill:#FFE5B4,stroke:#DA8A00,color:#DA8A00
    classDef example fill:#E6FFE6,stroke:#00B200,color:#00B200
    classDef pipeline fill:#E8E8E8,stroke:#4A4A4A,color:#4A4A4A
    classDef ci fill:#E6F0FF,stroke:#0047AB,color:#0047AB
```
