How vpasumarthi/pycd works
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.