# txie-93/cgcnn architecture

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

- Interactive diagram: https://gitdiagram.com/txie-93/cgcnn
- Repository: https://github.com/txie-93/cgcnn

## Overview

##### Main Components
- Core Library (cgcnn):
– Contains the primary modules:
- data.py: defines data loading, parsing of CIF files, CSV property mapping, and possibly dataset construction.
- model.py: implements the CGCNN neural network architecture.
– Role: encapsulate the core architecture/design (i.e., graph convolution on crystal structures).
- Command-Line Utilities:
– main.py: orchestrates the training pipeline. It handles reading a customized dataset (as described in the README), invoking the data loader, training the CGCNN model, and producing output files such as the best model checkpoint, final checkpoint, and test results.
– predict.py: loads a pre-trained model (from the pre-trained folder) and maps new crystal structure data (via CIF files and associated CSV/JSON files) to predictions.
- Data & Pre-Trained Models:
– The “data” directory holds example datasets to illustrate both classification and regression tasks.
– The “pre-trained” directory contains compressed model files (.pth.tar) which are used by predict.py.
- External Dependencies:
– Libraries such as PyTorch, scikit-learn, and pymatgen are critical to the functioning of the CGCNN modules and should be noted as part of the technical stack.

##### Relationships and Interactions Between Components
- Data Flow:
– User provides a “customized dataset” (with CIF files, id_prop.csv, and atom_init.json).
– The data is processed by the routines in cgcnn/data.py.
– The processed data is fed into the model architecture defined in cgcnn/model.py.
– main.py uses this pipeline to train a model and outputs checkpoint files (model_best.pth.tar and checkpoint.pth.tar) as well as test_results.csv.
– predict.py uses one of the pre-trained models (located in pre-trained) to process a new dataset and generate predictions (again outputting test_results.csv).
- Command-Line Invocation:
– Both main.py and predict.py serve as entry points: the former for training and the latter for inference.

##### Architectural Patterns & Design Principles
- Layered and modular design:
– Separation of concerns: Data input/processing, model definition, training/prediction logic, and evaluation/reporting.
- Pipeline Architecture:
– A clear “data → model → output” flow, reflecting a typical machine learning pipeline.
- Extensibility:
– The use of customizable datasets and the suggested possibility (in the advanced section) for writing custom PyTorch Dataset classes indicates an architecture designed for flexibility.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Data Input Section
    subgraph "Data Input"
        DS1["Sample Classification Dataset"]:::datastore
        DS2["Sample Regression Dataset"]:::datastore
        DS["Custom Dataset\n(CIF, CSV, JSON)"]:::datastore
        DS1 --> DS
        DS2 --> DS
    end

    %% Preprocessing and Core Model
    subgraph "CGCNN Core Library"
        DP["Data Preprocessing/Loader\n(cgcnn/data.py)"]:::core
        CM["CGCNN Model\n(cgcnn/model.py)"]:::core
        DS --> DP
        DP --> CM
    end

    %% Training Pipeline
    subgraph "Training Flow"
        TP["Training Pipeline\n(main.py)"]:::pipeline
        CM --> TP
    end

    %% Prediction Pipeline
    subgraph "Prediction Flow"
        PT["Prediction Pipeline\n(predict.py)"]:::pipeline
        PM["Pre-Trained Models\n(pre-trained)"]:::datastore
        DS --> PT
        PM --> PT
    end

    %% Output Section
    subgraph "Outputs"
        O1["Model Checkpoints & Test Results\n(training)"]:::output
        O2["Prediction Results\n(prediction)"]:::output
        TP --> O1
        PT --> O2
    end

    %% External Dependencies Section
    ED["External Dependencies\n(PyTorch, pymatgen, scikit-learn)"]:::external
    ED --- DP
    ED --- CM

    %% Click Events
    click DP "https://github.com/txie-93/cgcnn/blob/master/cgcnn/data.py"
    click CM "https://github.com/txie-93/cgcnn/blob/master/cgcnn/model.py"
    click TP "https://github.com/txie-93/cgcnn/blob/master/main.py"
    click PT "https://github.com/txie-93/cgcnn/blob/master/predict.py"
    click DS1 "https://github.com/txie-93/cgcnn/tree/master/data/sample-classification"
    click DS2 "https://github.com/txie-93/cgcnn/tree/master/data/sample-regression"
    click PM "https://github.com/txie-93/cgcnn/tree/master/pre-trained"

    %% Styles
    classDef core fill:#D0E6F5,stroke:#1F78C1,stroke-width:2px;
    classDef pipeline fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    classDef datastore fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    classDef external fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
    classDef output fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    
    %% Layout adjustments for vertical orientation
    style DS fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    style DP fill:#D0E6F5,stroke:#1F78C1,stroke-width:2px;
    style CM fill:#D0E6F5,stroke:#1F78C1,stroke-width:2px;
    style TP fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    style PT fill:#D5F5E3,stroke:#28B463,stroke-width:2px;
    style PM fill:#FCF3CF,stroke:#F1C40F,stroke-width:2px;
    style ED fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
