# minoru938/cspml architecture

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

- Interactive diagram: https://gitdiagram.com/minoru938/cspml
- Repository: https://github.com/minoru938/cspml

## Overview

##### Main Components
- Data Management & Storage:
- Data files and datasets are stored under both the top-level “data_set” directory and within “CSPML_latest_codes/data_set”. They include candidate crystals, structural data, pre-trained model files, and other arrays (e.g., .npy, .pd.xz).
- These datasets provide the material’s input for both training and predictive modeling.
- Model Training & Prediction Modules:
- Core algorithms are implemented in CSPML.py and complemented by additional scripts and notebooks (e.g., CSPML_training.ipynb, CSPML_Structure_Prediction.ipynb) that compare training outcomes.
- Pre-trained models (embedded as part of the repository) and the machine learning classification engine (binary neural network model) are key here.
- Updated/Latest Model Versions:
- The “CSPML_latest_codes” folder contains newer training codes addressing bias and newer TensorFlow versions, along with an updated training approach as described for the recent publication.
- User Interface & Tutorials:
- The tutorial.ipynb and various Jupyter notebooks serve as both documentation and interactive demonstrations.
- External Dependencies & Integration:
- The project relies on external libraries (pandas, numpy, tensorflow, pymatgen, xenonpy, torch, and optionally, matminer). Their interactions with data preprocessing, feature extraction (e.g., structure fingerprints), and model predictions should be represented.

##### Relationships and Interactions
- Data flows from the data storage layers (both “data_set” directories) into preprocessing and then into the machine learning pipeline.
- The updated “CSPML_latest_codes” plays a dual role: it mirrors the original module architecture but with enhanced training controls and additional processing pipelines.
- External libraries and dependencies should be depicted as side components that feed into the core components, emphasizing their roles (e.g., TensorFlow powering the training and "xenonpy" enhancing feature extraction).

##### Architectural Patterns and Design Principles
- Modular Design: Separate directories for datasets, core code, updated versions, and notebooks indicate that each major functionality is self-contained yet interconnected.
- Pipeline & Workflow Pattern: The system essentially works as a pipeline, where data is ingested, processed, used in model training, and finally served for prediction.
- Versioning for Research & Production: There is a clear distinction between the standard CSPML and the updated versions (contained in "CSPML_latest_codes"), emphasizing iterative improvements on the methodology.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Data Management & Storage
    subgraph "Data Management & Storage"
        direction TB
        A["Top-Level Data (data_set)"]:::data
        B["Updated Data (CSPML_latest_codes/data_set)"]:::data
        C["Crystal Structure DB<br/>(Materials Project)"]:::external
    end

    %% Preprocessing and Feature Extraction
    P["Preprocessing & Feature Extraction"]:::process

    %% ML Model Training & Prediction Modules
    subgraph "ML Model Training & Prediction"
        direction TB
        D["Main Training Script (CSPML.py)"]:::ml
        E["Updated Training Notebook (CSPML_latest_codes/CSPML_training.ipynb)"]:::ml
        F["Structure Prediction Notebook (CSPML_latest_codes/CSPML_Structure_Prediction.ipynb)"]:::ml
    end

    %% Updated/Latest Model Versions
    U["Updated ML Pipeline (CSPML_latest_codes)"]:::ml2

    %% Predicted Output
    L["Predicted Crystal Structures"]:::output

    %% User Interface & Tutorials
    subgraph "User Interface & Tutorials"
        direction TB
        G["Tutorial Notebook (tutorial.ipynb)"]:::ui
        H["ML Data Creation (CSPML_latest_codes/CSPML_Creating_MLdata.ipynb)"]:::ui
        I["Structure Fingerprint Creation (CSPML_latest_codes/Create_strcmp_fgp.ipynb)"]:::ui
        J["Tools Notebook (CSPML_latest_codes/tools.ipynb)"]:::ui
    end

    %% External Dependencies
    K["External Libraries<br/>(pandas, numpy, tensorflow, torch, pymatgen, xenonpy, matminer)"]:::external

    %% Connections: Data flows
    A --> P
    B --> P
    C --> P

    %% External Libraries integration
    K --> P
    K --> D
    K --> E
    K --> F

    %% Processing to ML pipelines
    P --> D
    P --> E
    P --> F

    %% ML pipelines to prediction output
    D --> L
    E --> L
    F --> L
    U --> L

    %% UI accesses predicted outputs
    L --> G
    L --> H
    L --> I
    L --> J

    %% Updated ML Pipeline linked with ML Training
    P --> U

    %% Class Definitions
    classDef data fill:#ffebcd,stroke:#8b4513,stroke-width:2px;
    classDef process fill:#e0ffff,stroke:#4682b4,stroke-width:2px;
    classDef ml fill:#d8bfd8,stroke:#dda0dd,stroke-width:2px;
    classDef ml2 fill:#dda0dd,stroke:#800080,stroke-width:2px;
    classDef ui fill:#ffe4e1,stroke:#ff69b4,stroke-width:2px;
    classDef external fill:#f0e68c,stroke:#b8860b,stroke-width:2px;
    classDef output fill:#98fb98,stroke:#2e8b57,stroke-width:2px;

    %% Click Events
    click A "https://github.com/minoru938/cspml/tree/master/data_set"
    click B "https://github.com/minoru938/cspml/tree/master/CSPML_latest_codes/data_set"
    click D "https://github.com/minoru938/cspml/blob/master/CSPML.py"
    click E "https://github.com/minoru938/cspml/blob/master/CSPML_latest_codes/CSPML_training.ipynb"
    click F "https://github.com/minoru938/cspml/blob/master/CSPML_latest_codes/CSPML_Structure_Prediction.ipynb"
    click U "https://github.com/minoru938/cspml/tree/master/CSPML_latest_codes"
    click G "https://github.com/minoru938/cspml/blob/master/tutorial.ipynb"
    click H "https://github.com/minoru938/cspml/blob/master/CSPML_latest_codes/CSPML_Creating_MLdata.ipynb"
    click I "https://github.com/minoru938/cspml/blob/master/CSPML_latest_codes/Create_strcmp_fgp.ipynb"
    click J "https://github.com/minoru938/cspml/blob/master/CSPML_latest_codes/tools.ipynb"
```
