How thomasple/fennol works
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