# fangcheng-wang/crystmatch architecture

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

- Interactive diagram: https://gitdiagram.com/fangcheng-wang/crystmatch
- Repository: https://github.com/fangcheng-wang/crystmatch

## Overview

##### Project Type and Purpose
- `crystmatch` is an open‑source Python library + command‑line tool for enumeration and analysis of crystal‑structure matches (CSMs).
- It ships as a pip/conda package, provides a CLI frontend plus a Python API, and produces NPZ, CSV, PDF, POSCAR files as outputs.

##### Decompose the File Structure into Architectural Layers
A. Packaging & Configuration
- `setup.py` / `pyproject.toml` → defines the package, dependencies, CLI entry‑points
- `.gitignore`, `LICENSE` → VCS and legal
B. Core Library (`crystmatch/`)
- `enumeration.py` → algorithms to generate and filter CSMs
- `analysis.py` → scoring, benchmarking, RMSD/RMSS computations
- `utilities.py` → file I/O (POSCAR read/write), NPZ table management, math helpers
- `__init__.py` → module exports & API surface
C. CLI Layer
- Entry‑point installed via setup.py → parses user arguments, dispatches to enumeration or analysis routines
- Modes: enumeration, read‑mode (export/orientation), single‑CSM mode
D. Outputs & Data
- POSCAR files (input & output), `.npz` container for CSM lists
- Generated CSV tables, PDF scatter plots
E. Documentation Site (MkDocs)
- `mkdocs.yml`, `docs/` → authoring of user guide, CLI reference, API docs
- Static assets: CSS, JavaScript, markdown pages

##### External Dependencies & Services
- `spglib` → space‑group detection for symmetry filtering
- `numpy` → numerical arrays, NPZ I/O
- `matplotlib` (likely) → scatter plots to PDF
- POSCAR format conventions (VASP input schema)

##### Architectural Patterns and Design Principles
- Modular separation: I/O (utilities) vs. algorithmic core (enumeration, analysis) vs. CLI glue
- Clear CLI/Application boundary (thin interface layer)
- Reusable library: the same core engines support both CLI and direct Python API use
- Declarative documentation (MkDocs) separated from code

##### Diagramming Conventions
- CLI → Enumeration Engine → Utilities → File System
- CLI → Analysis Engine → Utilities → File System
- Python API → Core Modules
- Docs Source → MkDocs → Static Site

##### Putting It All Together
- Or group into vertically stacked layers (Interface, Processing, Dependencies, Persistence)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Packaging & Configuration
    subgraph "Packaging & Configuration"
        style Packaging fill:#e0e0e0,stroke:#888
        Packaging_setup["setup.py"]:::tooling
        Packaging_pyproject["pyproject.toml"]:::tooling
        Packaging_gitignore[".gitignore"]:::tooling
        Packaging_license["LICENSE"]:::tooling
    end

    %% CLI Layer
    subgraph "CLI Layer"
        style CLI fill:#f8f8f8,stroke:#888
        CLI["CLI Parser\n(console_scripts)"]:::cli
    end

    %% Core Library
    subgraph "Core Library"
        style Core fill:#f8fff0,stroke:#888
        Enum["Enumeration Engine\n(crystmatch/enumeration.py)"]:::core
        Anal["Analysis Engine\n(crystmatch/analysis.py)"]:::core
        Util["Utilities\n(crystmatch/utilities.py)"]:::core
        API["API Surface\n(crystmatch/__init__.py)"]:::core
    end

    %% External Services
    subgraph "External Dependencies"
        style External fill:#f0f8ff,stroke:#888
        Spglib["spglib"]:::external
        Numpy["numpy"]:::external
        Mpl["matplotlib"]:::external
    end

    %% File System & Outputs
    subgraph "File System & Outputs"
        style IO fill:#fff0d0,stroke:#888
        POSCAR["POSCAR Files"]:::io
        NPZ[".npz Containers"]:::io
        CSV["CSV Tables"]:::io
        PDF["PDF Plots"]:::io
    end

    %% Documentation
    subgraph "Documentation Site"
        style Docs fill:#f0f0f0,stroke:#888
        Docs_src["docs/"]:::tooling
        Mkdocs["MkDocs\n(mkdocs.yml)"]:::tooling
        Site["Static Site"]:::tooling
    end

    %% Connections
    Packaging_setup -->|defines entry-point| CLI
    CLI -->|"invoke enumeration"| Enum
    CLI -->|"invoke analysis"| Anal
    CLI -->|"via API imports"| API

    Enum -->|"read_POSCAR()"| Util
    Enum -->|"filter_symmetry()"| Spglib
    Enum -->|"store_CSM_list()"| NPZ
    Enum -->|"export_csv()"| CSV
    Enum -->|"export_pdf()"| PDF

    Anal -->|"load_npz()"| Util
    Anal -->|"compute_metrics()"| Numpy
    Anal -->|"generate_plots()"| Mpl
    Anal -->|"export_poscar()"| POSCAR
    Anal -->|"export_csv()"| CSV
    Anal -->|"export_pdf()"| PDF

    API --> Enum
    API --> Anal
    API --> Util

    Docs_src --> Mkdocs
    Mkdocs --> Site

    %% Click Events
    click Packaging_setup "https://github.com/fangcheng-wang/crystmatch/blob/main/setup.py"
    click Packaging_pyproject "https://github.com/fangcheng-wang/crystmatch/blob/main/pyproject.toml"
    click Packaging_gitignore "https://github.com/fangcheng-wang/crystmatch/blob/main/.gitignore"
    click Packaging_license "https://github.com/fangcheng-wang/crystmatch/tree/main/LICENSE"
    click Enum "https://github.com/fangcheng-wang/crystmatch/blob/main/crystmatch/enumeration.py"
    click Anal "https://github.com/fangcheng-wang/crystmatch/blob/main/crystmatch/analysis.py"
    click Util "https://github.com/fangcheng-wang/crystmatch/blob/main/crystmatch/utilities.py"
    click API "https://github.com/fangcheng-wang/crystmatch/blob/main/crystmatch/__init__.py"
    click Mkdocs "https://github.com/fangcheng-wang/crystmatch/blob/main/mkdocs.yml"
    click Docs_src "https://github.com/fangcheng-wang/crystmatch/tree/main/docs/"

    %% Styles
    classDef tooling fill:#cccccc,stroke:#888,stroke-width:1px
    classDef cli fill:#ffe4b5,stroke:#888,stroke-width:1px
    classDef core fill:#a0f2a0,stroke:#080,stroke-width:1px
    classDef external fill:#a0c4f0,stroke:#008,stroke-width:1px
    classDef io fill:#f2a060,stroke:#a50,stroke-width:1px
    classDef Docs fill:#f0f0f0,stroke:#888,stroke-width:1px
```
