# selvachandrasekaranselvaraj/deepatom architecture

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

- Interactive diagram: https://gitdiagram.com/selvachandrasekaranselvaraj/deepatom
- Repository: https://github.com/selvachandrasekaranselvaraj/deepatom

## Overview

##### Project type and purpose
- DeepAtom is a standalone Python library/package for materials-science machine-learning workflows: loading trajectory data, computing atomic descriptors, preparing training data, training/predicting with a graph neural network (GNN).
- It is not a web/full-stack app or microservice: it’s a modular scientific pipeline accessed via a CLI or imported as a library.

##### File structure
- Top-level files: setup.py, requirements.txt, README.md define packaging and dependencies.
- Core package directory (`deepatom/`):
- `main.py`: orchestrator and CLI entry point (DeepAtom class).
- `descriptors.py`: descriptor calculators (Coulomb, ACSF, SOAP, MBTR, etc.).
- `gnn.py`: graph-neural-network architecture, training, saving/loading.
- `utils.py`: data-handling utilities for parsing LAMMPS trajectory files.
- `tools/`: shell and Perl scripts for pre/post-processing outside Python.
- `tests/`: unit tests for descriptors (and potentially other modules).

##### README for additional insights
- Workflow stages clearly defined: load data → calculate descriptors → prepare data → train GNN → predict.
- External input: LAMMPS trajectory files.
- Outputs: descriptor arrays, saved model file (`deepatom_model.pth`), prediction metrics.
- Dependencies: NumPy, PyTorch (for GNN), scikit-learn (likely for scaling/splitting), perhaps ASE for structure parsing.

##### Detail
- “Tests” component connected to the modules it validates.
- Packaging/deployment layer (setup.py, pip install) to show how the library is distributed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Artifacts
    subgraph "Data Artifacts" 
        direction TB
        LAMMPS["LAMMPS\nTrajectory File"]:::artifact
        ModelFile["deepatom_model.pth\nModel File"]:::artifact
        Predictions["Prediction\nMetrics"]:::artifact
    end

    %% Modules
    subgraph "Core Modules"
        direction TB
        CLI["CLI / API Entry\n(deepatom/main.py)"]:::python
        Utils["Data Loader\n(deepatom/utils.py)"]:::python
        Descriptors["Descriptor Engine\n(deepatom/descriptors.py)"]:::python
        Preprocessor["Data Preprocessor\n(main.py logic)"]:::python
        GNN["GNN Model\n(deepatom/gnn.py)"]:::python
    end

    %% Model persistence inside GNN
    subgraph "Model Persistence"
        direction TB
        Persistence["Checkpoint Save/Load\n(gnn.py)"]:::python
    end

    %% External Tools
    subgraph "External Tools" 
        direction TB
        NebMovie["neb_movie.sh"]:::external
        NebMake["nebmake.pl"]:::external
        QEEnergy["qe_energy.sh"]:::external
    end

    %% Tests and Packaging
    subgraph "Quality & Distribution"
        direction TB
        Tests["Tests Suite\ntests/"]:::external
        Setup["setup.py\nrequirements.txt\nREADME.md"]:::external
    end

    %% Flow
    LAMMPS -->|reads trajectory| CLI
    CLI -->|calls loader| Utils
    Utils -->|provides structures| Descriptors
    Descriptors -->|features arrays| Preprocessor
    Preprocessor -->|train/test tensors| GNN
    GNN -->|saves/loads checkpoint| Persistence
    GNN -->|outputs predictions| Predictions
    Predictions -->|reports metrics| CLI

    %% Optional tools
    CLI -.->|invokes| NebMovie
    CLI -.->|invokes| NebMake
    CLI -.->|invokes| QEEnergy

    %% Tests connections
    Tests -.->|validates| Descriptors
    Tests -.->|validates| Utils
    Tests -.->|validates| GNN

    %% Packaging
    Setup --> CLI

    %% Click events
    click CLI "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/main.py"
    click Utils "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/utils.py"
    click Descriptors "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/descriptors.py"
    click Preprocessor "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/main.py"
    click GNN "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/gnn.py"
    click Persistence "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/gnn.py"
    click NebMovie "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/tools/neb_movie.sh"
    click NebMake "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/tools/nebmake.pl"
    click QEEnergy "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/deepatom/tools/qe_energy.sh"
    click Tests "https://github.com/selvachandrasekaranselvaraj/deepatom/tree/master/tests/"
    click Setup "https://github.com/selvachandrasekaranselvaraj/deepatom/blob/master/setup.py"

    %% Styles
    classDef python fill:#D0E8FF,stroke:#0277BD,stroke-width:1px
    classDef external fill:#E8F5E9,stroke:#2E7D32,stroke-width:1px
    classDef artifact fill:#FFF9C4,stroke:#F9A825,stroke-width:1px
```
