# hegoimanzano/pycsh architecture

> Architecture diagram of the GitHub repository hegoimanzano/pycsh, 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/hegoimanzano/pycsh
- Repository: https://github.com/hegoimanzano/pycsh

## Overview

##### Project Type and Purpose
- This is a standalone scientific‐computational Python application (“pyCSH”) for automated generation of realistic bulk calcium silicate hydrate structures.
- It reads user parameters, builds atomistic bricks from predefined block templates, assembles them into supercells, optionally validates and visualizes results, and writes output in multiple molecular‐simulation formats (LAMMPS, VASP, EricaFF).

##### Core Components
a. Command-Line Interface (CLI) / Entry Point
- File: main_brick.py
- Parses CLI flags and loads parameters.py
b. Parameter Manager
- File: parameters.py
c. Sampling Engine
- Module: mod_sample.py
- Computes random Ca/Si, Si–OH, Ca–OH distributions via Gaussian sampling
d. Brick Constructor
- Module: mod_construct_brick.py
- Reads block definitions from Blocks_Renamed/
- Generates individual unit‐cell bricks
e. Supercell Assembler
- Module: mod_construct_supercell.py
f. Validation / Checking
- Module: mod_check.py
- Optional “check” mode: verifies ratio distributions over many samples
g. Graph Generator
- Module: mod_make_graphs.py
- Produces diagnostic plots of distribution accuracy
h. Output Writer
- Module: mod_write.py
- Exports final structures as:
- LAMMPS .data
- LAMMPS+EricaFF .data
- VASP .vasp

­­­ Additional resource:
- Blocks_Renamed/ (data folder) containing block files (“<Lo”, “>Ro”, w15, etc.)

##### External Dependencies & Services
- Python 3 + NumPy (internal library)
- External simulators/readers: LAMMPS, EricaFF, VASP (consumers of the generated files)

##### Data Flow & Interactions
CLI → Parameter Manager → Sampling Engine → Brick Constructor → Supercell Assembler → [branch → Validation] → Graph Generator
↓
Output Writer → Filesystem → External Simulators

##### Architectural Patterns & Principles
- Pipeline pattern: each module performs a well‐defined transformation on the structure data.
- Data‐driven: block definitions are externalized in Blocks_Renamed/ for easy extensibility.
- Single Responsibility: each mod_*.py has a focused purpose.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core pipeline
    A["main_brick.py (CLI)"]:::core
    B["parameters.py"]:::resource
    C["mod_sample.py"]:::core
    subgraph "Brick Building"
        D["mod_construct_brick.py"]:::core
        E["Blocks_Renamed/"]:::resource
    end
    F["mod_construct_supercell.py"]:::core
    Q{"Mode?"}
    G["mod_check.py"]:::optional
    H["mod_make_graphs.py"]:::optional
    I["mod_write.py"]:::core

    %% External outputs
    subgraph "External Simulators"
        J["LAMMPS"]:::external
        K["EricaFF"]:::external
        L["VASP"]:::external
    end

    %% Flows
    A -->|"load flags"| B
    B -->|"params"| C
    C -->|"brick list"| D
    E --> D
    D -->|"unit bricks"| F
    F -->|"supercell atoms"| Q

    Q -->|"check=True"| G
    G --> H
    Q -->|"create/read/surface"| I

    I -->|"LAMMPS .data"| J
    I -->|"EricaFF .data"| K
    I -->|".vasp"| L

    %% Click events
    click A "https://github.com/hegoimanzano/pycsh/blob/main/main_brick.py"
    click B "https://github.com/hegoimanzano/pycsh/blob/main/parameters.py"
    click C "https://github.com/hegoimanzano/pycsh/blob/main/mod_sample.py"
    click D "https://github.com/hegoimanzano/pycsh/blob/main/mod_construct_brick.py"
    click E "https://github.com/hegoimanzano/pycsh/tree/main/Blocks_Renamed/"
    click F "https://github.com/hegoimanzano/pycsh/blob/main/mod_construct_supercell.py"
    click G "https://github.com/hegoimanzano/pycsh/blob/main/mod_check.py"
    click H "https://github.com/hegoimanzano/pycsh/blob/main/mod_make_graphs.py"
    click I "https://github.com/hegoimanzano/pycsh/blob/main/mod_write.py"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#1167b1,stroke-width:1px;
    classDef resource fill:#d9ead3,stroke:#38761d,stroke-width:1px;
    classDef external fill:#fce5cd,stroke:#bf9000,stroke-width:1px;
    classDef optional stroke-dasharray: 5 5,fill:#fff2cc,stroke:#b45f06,stroke-width:1px;
```
