# facebookresearch/fairchem architecture

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

- Interactive diagram: https://gitdiagram.com/facebookresearch/fairchem
- Repository: https://github.com/facebookresearch/fairchem

## Overview

##### Project type and purpose
- This is a large monorepo for an open-source framework (“fairchem”) providing:
- A core library (`src/fairchem/core`) with calculation engines, datasets, models, training/evaluation runners, and CLI.
- Multiple applications (`src/fairchem/applications/AdsorbML`, `…/cattsunami`, `…/ocx`) that build on the core to solve domain-specific tasks.
- Data modules (`src/fairchem/data/oc`, `…/odac`, `…/om`) that provide standardized datasets and utilities for materials and molecular data.
- A demo CLI/service (`src/fairchem/demo/ocpapi`) showcasing client workflows against the FAIRChem core.
- Configuration templates (`configs/uma/...`) and documentation (`docs/…`).
- The README clarifies that “fairchem” is a centralized repository of data, pre-trained models, demos, and application code for materials science and quantum chemistry.

##### File structure and architectural patterns
- Top-level directories:
- `src/fairchem/core`: core components, pluggable calculation/train/eval pipelines, dataset definitions, model implementations.
- `src/fairchem/applications`: domain-specific high-level APIs and workflows.
- `src/fairchem/data`: raw and processed data modules.
- `src/fairchem/demo`: end-user CLI/service example.
- `configs`: YAML configs for benchmarking, evaluation, training.
- `packages`: packaging stubs for PyPI distribution of each sub-module.
- `docs`: Sphinx/Quarto docs for users and tutorials.
- `tests`: unit/integration tests for each component.
- Architectural choices:
- Plugin/registry pattern in core (`registry.py`) for dynamic component loading.
- Configuration-driven workflows (Hydra-style YAML configs).
- Modular packages to publish core, data, applications separately.
- CI/CD pipelines in `.github/workflows` for build/test/deploy of docs and packages.

##### README for stack and dependencies
- Python 3.10+
- External libraries: ASE, Hugging Face for model hosting, PyTorch/ML frameworks under the hood.
- CLI (`main.py`) exposes entrypoints for core functionality.
- Models are fetched from HF and wrapped in an ASE calculator.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External Services"
        direction TB
        HF["Hugging Face"]:::external
        ASE["ASE"]:::external
        HPC["HPC Clusters"]:::external
    end

    subgraph "Data Layer"
        direction TB
        OC["OC Module"]:::data
        ODAC["ODAC Module"]:::data
        OM["OM Module"]:::data
    end

    subgraph "Core Library"
        direction TB
        Core["Core Library"]:::core
    end

    subgraph "Applications Layer"
        direction TB
        Ads["AdsorbML"]:::app
        Cat["Cattsunami"]:::app
        OCX["OCX"]:::app
    end

    subgraph "Demo Service"
        direction TB
        Demo["OCP API CLI & Workflows"]:::demo
    end

    subgraph "Config & CI/CD"
        direction TB
        Config["Configuration Repository"]:::config
        CI["CI/CD Pipelines"]:::config
    end

    subgraph "Packaging / Distribution"
        direction TB
        PCore["fairchem-core"]:::pack
        PAds["fairchem-applications-AdsorbML"]:::pack
        PCat["fairchem-applications-cattsunami"]:::pack
        POCX["fairchem-applications-ocx"]:::pack
        POC["fairchem-data-oc"]:::pack
        POM["fairchem-data-om"]:::pack
        PDemo["fairchem-demo-ocpapi"]:::pack
        PYPI["PyPI"]:::external
    end

    %% Data flows and dependencies
    Core -->|"loads data"| OC
    Core -->|"loads data"| ODAC
    Core -->|"loads data"| OM

    Ads -->|"invokes runner"| Core
    Cat -->|"invokes runner"| Core
    OCX -->|"invokes runner"| Core

    Demo -->|"uses workflows"| Core
    Demo -->|"uses apps"| Ads
    Demo -->|"uses apps"| Cat
    Demo -->|"uses apps"| OCX

    Core -->|"fetches model"| HF
    Ads -->|"fetches model"| HF
    Cat -->|"fetches model"| HF
    OCX -->|"fetches model"| HF

    Core -->|"integrates MD"| ASE

    Config -->|"provides configs"| Core
    Core -->|"writes logs/metrics"| Config
    Config -->|"provides configs"| Ads
    Config -->|"provides configs"| Cat
    Config -->|"provides configs"| OCX

    CI -->|"builds/tests"| PCore
    CI -->|"builds/tests"| PAds
    CI -->|"builds/tests"| PCat
    CI -->|"builds/tests"| POCX
    CI -->|"builds/tests"| POC
    CI -->|"builds/tests"| POM
    CI -->|"builds/tests"| PDemo

    PCore -->|"publishes"| PYPI
    PAds -->|"publishes"| PYPI
    PCat -->|"publishes"| PYPI
    POCX -->|"publishes"| PYPI
    POC -->|"publishes"| PYPI
    POM -->|"publishes"| PYPI
    PDemo -->|"publishes"| PYPI

    %% Click Events
    click Core "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/core"
    click Ads "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/applications/AdsorbML"
    click Cat "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/applications/cattsunami"
    click OCX "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/applications/ocx"
    click OC "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/data/oc"
    click ODAC "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/data/odac"
    click OM "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/data/om"
    click Demo "https://github.com/facebookresearch/fairchem/tree/main/src/fairchem/demo/ocpapi"
    click Config "https://github.com/facebookresearch/fairchem/tree/main/configs/uma"
    click CI "https://github.com/facebookresearch/fairchem/tree/main/.github/workflows"
    click PCore "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-core"
    click PAds "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-applications-AdsorbML"
    click PCat "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-applications-cattsunami"
    click POCX "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-applications-ocx"
    click POC "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-data-oc"
    click POM "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-data-om"
    click PDemo "https://github.com/facebookresearch/fairchem/tree/main/packages/fairchem-demo-ocpapi"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72
    classDef app fill:#D5F5E3,stroke:#1D8348
    classDef data fill:#FDEBD0,stroke:#B9770E
    classDef demo fill:#E8DAEF,stroke:#6C3483
    classDef config fill:#F2F3F4,stroke:#616A6B
    classDef pack fill:#F2F3F4,stroke:#1F618D
    classDef external stroke-dasharray: 5 5,stroke:#7D3C98,fill:none
```
