How fangcheng-wang/crystmatch works
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)