# vpasumarthi/pycd architecture

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

- Interactive diagram: https://gitdiagram.com/vpasumarthi/pycd
- Repository: https://github.com/vpasumarthi/pycd

## Overview

##### Project Type and Purpose
- PyCD is a Python library/tool for running kMC simulations on crystalline systems.
- It provides both a core simulation engine (library) and a collection of CLI scripts for common workflows (data profiling, matrix generation, MSD calculations, etc.).

##### Main Components
a. User / Developer Interface
- Conda/Pip environment
- CLI scripts under PyCD/scripts
- Example runner scripts in examples/
b. Core Library
- core.py (simulation engine)
- io.py (I/O routines for reading/writing data)
- constants.py (physical constants, global parameters)
- material_*.py modules (material definitions and setup)
- data directory (packed datasets, look_and_say.dat)
c. Supporting Tooling
- devtools (conda env scripts, CI hooks)
- docs (Sphinx sources, API rst files)
d. Tests
- PyCD/tests (unit tests invoking core functionality)
e. External Dependencies
- NumPy, SciPy, YAML parsers (listed in requirements.txt)

##### Relationships & Data Flow
- Start at the top with “User / Script Invocation”
→ script calls Core Library APIs
→ Core loads material definitions (material_setup.py → material_run.py)
→ Core uses io.py to parse input files (sys_config.yml, POSCAR, trajectory dumps)
→ Core executes kMC algorithm (core.py loops, event selection, updates)
→ Core writes output data (trajectories, MSD, logs) via io.py
→ Optional post-processing scripts consume output for analytics (mean_distance, data_profile, etc.)
- Tests and examples sit to the side, each invoking the same core flow.

##### Architectural Patterns & Design Principles
- Modular library: clear separation between data layer (io.py + data/), simulation engine (core.py), and material models (material_*.py).
- CLI orchestration: thin wrapper scripts solely import and invoke library functions with config files.
- Extensibility: adding a new material_* module automatically plugs into core.
- Single-process synchronous flow (no microservices).

##### Single Flow Chart Benefits
- Provides a holistic view—from environment setup and script invocation, through the core simulation pipeline, to output and post-processing.
- Perfect for onboarding new contributors or architects reviewing system interactions at a glance.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Environment Setup
    GEAR["Conda/Pip Environment"]:::environment

    %% User / CLI Scripts
    subgraph "User / CLI Scripts"
        Scripts(("data_profile.py<br/>coc_msd.py<br/>generate_*.py")):::script
    end

    %% Example Runner Scripts
    subgraph "Example Runner Scripts"
        Examples(("Run.py")):::script
    end

    %% Core Library
    subgraph "Core Library"
        IO["io.py"]:::library
        Const["constants.py"]:::library
        Core["core.py<br/><i>kMC engine loop</i>"]:::library
        subgraph "Material Modules"
            M_setup["material_setup.py"]:::library
            M_run["material_run.py"]:::library
            M_coc["material_coc_msd.py"]:::library
            M_msd["material_msd.py"]:::library
            M_preprod["material_preprod.py"]:::library
        end
    end

    %% Data Directory
    Data["Data Directory<br/>(POSCAR, sys_config.yml,<br/>look_and_say.dat,<br/>trajectories, MSD)"]:::data

    %% Post-Processing
    subgraph "Post-Processing Scripts"
        PostProc(("mean_distance.py<br/>data_profile.py")):::script
    end

    %% Supporting Tooling
    subgraph "Supporting Tooling"
        CondaEnv["test_env.yaml"]:::tooling
        CreateEnv["create_conda_env.py"]:::tooling
        CI["before_install.sh"]:::tooling
    end

    %% Documentation & Tests
    subgraph "Documentation"
        Docs["docs/"]:::tooling
    end

    subgraph "Tests"
        Tests["test_PyCD.py"]:::test
    end

    %% External Dependencies
    Req["requirements.txt"]:::tooling

    %% Connections
    GEAR --> Scripts
    GEAR --> Examples
    Scripts -->|"invoke API"| Core
    Examples -->|"run example"| Core
    Core -->|"uses I/O routines"| IO
    IO -->|"reads/writes"| Data
    Core -->|"reads/writes"| Data
    Data -->|"consumed by"| PostProc
    Req --> Core
    Tests -.->|"validate API"| Core

    %% Click Events
    click Scripts "https://github.com/vpasumarthi/pycd/tree/master/PyCD/scripts/"
    click Examples "https://github.com/vpasumarthi/pycd/tree/master/examples/"
    click Core "https://github.com/vpasumarthi/pycd/blob/master/PyCD/core.py"
    click IO "https://github.com/vpasumarthi/pycd/blob/master/PyCD/io.py"
    click Const "https://github.com/vpasumarthi/pycd/blob/master/PyCD/constants.py"
    click M_coc "https://github.com/vpasumarthi/pycd/blob/master/PyCD/material_coc_msd.py"
    click M_msd "https://github.com/vpasumarthi/pycd/blob/master/PyCD/material_msd.py"
    click M_preprod "https://github.com/vpasumarthi/pycd/blob/master/PyCD/material_preprod.py"
    click M_run "https://github.com/vpasumarthi/pycd/blob/master/PyCD/material_run.py"
    click M_setup "https://github.com/vpasumarthi/pycd/blob/master/PyCD/material_setup.py"
    click Data "https://github.com/vpasumarthi/pycd/blob/master/PyCD/data/look_and_say.dat"
    click CondaEnv "https://github.com/vpasumarthi/pycd/blob/master/devtools/conda-envs/test_env.yaml"
    click CreateEnv "https://github.com/vpasumarthi/pycd/blob/master/devtools/scripts/create_conda_env.py"
    click CI "https://github.com/vpasumarthi/pycd/blob/master/devtools/travis-ci/before_install.sh"
    click Docs "https://github.com/vpasumarthi/pycd/tree/master/docs/"
    click Tests "https://github.com/vpasumarthi/pycd/blob/master/PyCD/tests/test_PyCD.py"
    click Req "https://github.com/vpasumarthi/pycd/blob/master/requirements.txt"

    %% Styles
    classDef environment fill:#D3D3F5,stroke:#333,stroke-width:1px
    classDef script fill:#B3D7FF,stroke:#036,stroke-width:1px
    classDef library fill:#C2F0C2,stroke:#2E8B57,stroke-width:1px
    classDef data fill:#FFD699,stroke:#DAA520,stroke-width:1px
    classDef tooling fill:#E0E0E0,stroke:#777,stroke-width:1px
    classDef test fill:#F0E68C,stroke:#B8860B,stroke-width:1px
```
