# badw/puppy architecture

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

- Interactive diagram: https://gitdiagram.com/badw/puppy
- Repository: https://github.com/badw/puppy

## Overview

##### Project type and purpose
- From the README (“puppy – Phonon Unfolding and Projections”) and the `src/puppy` modules, this is a Python scientific library/tool for unfolding phonon bands around crystal defects and projecting eigendisplacements onto dispersion curves.
- It is not a web or full-stack application but a domain-specific computational library with example notebooks.

##### File structure
- Top level:
- `src/puppy/` – core Python package
- `examples/` – Jupyter notebooks and example data sets (host, solid_solution, experimental)
- `static/` – logo and generated images
- `pyproject.toml` – packaging/config
- Inside `src/puppy/`:
- `analysis.py` – routines to read phonon data and compute unfolding/projections
- `unfolder.py` – algorithms to perform the actual band-unfolding
- `plotting.py` – visualization functions for results
- `_deprecated.py` – legacy code

##### README for additional insights
- Installation via `pip install .`
- Example notebooks drive the library, loading FORCE_CONSTANTS from example subfolders
- Outputs are figures (e.g., `static/unfolded.png`)

##### Be detailed and capture essential elements
- Break the core library into its 3 subcomponents.
- How examples supply data and consume the library’s API.
- Packaging boundary (pip installation) if relevant for deployments.
- Keep the layout horizontal: Examples on the left, core library in the middle, Data Assets below, static output on the right.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Example Driver Layer
    subgraph "Example Driver Layer"
        NB["Jupyter Notebooks"]:::example
    end

    %% Core Library Modules
    subgraph "Core Library (src/puppy)" 
        A["Analysis Module\n(src/puppy/analysis.py)"]:::core
        U["Unfolding Engine\n(src/puppy/unfolder.py)"]:::core
        P["Projection & Post-processing\n(src/puppy/analysis.py)"]:::core
        V["Visualization Module\n(src/puppy/plotting.py)"]:::core
        D["Legacy/Deprecated Code\n(src/puppy/_deprecated.py)"]:::deprecated
    end

    %% Data Assets
    subgraph "Data Assets" 
        FH[(FORCE_CONSTANTS Host)]:::data
        FS[(FORCE_CONSTANTS Solid Solution)]:::data
        EXD[(Experimental Data)]:::data
    end

    %% External Dependencies
    subgraph "External Dependencies"
        ND["NumPy, SciPy"]:::external
        MP["Matplotlib"]:::external
        PP["Phonopy/ASE"]:::external
    end

    %% Static Outputs & Packaging
    subgraph "Outputs & Config"
        SO["Static Outputs\n(static/)"]:::output
        PC["Packaging Config\n(pyproject.toml)"]:::config
    end

    %% Connections
    NB -->|"imports"| A
    A -->|"calls unfold()"| U
    U -->|"returns arrays"| P
    P -->|"passes NumPy arrays"| V
    V -->|"generates images"| SO

    A -->|reads| FH
    A -->|reads| FS
    A -->|reads| EXD

    A -->|"uses"| ND
    V -->|"uses"| MP
    A -->|"may use"| PP

    PC -->|"installs package"| A

    %% Click Events
    click NB "https://github.com/badw/puppy/tree/main/examples/"
    click A "https://github.com/badw/puppy/blob/main/src/puppy/analysis.py"
    click U "https://github.com/badw/puppy/blob/main/src/puppy/unfolder.py"
    click P "https://github.com/badw/puppy/blob/main/src/puppy/analysis.py"
    click V "https://github.com/badw/puppy/blob/main/src/puppy/plotting.py"
    click D "https://github.com/badw/puppy/blob/main/src/puppy/_deprecated.py"
    click FH "https://github.com/badw/puppy/tree/main/examples/CuAg/host/FORCE_CONSTANTS"
    click FS "https://github.com/badw/puppy/tree/main/examples/CuAg/solid_solution/FORCE_CONSTANTS"
    click EXD "https://github.com/badw/puppy/tree/main/examples/experimental/"
    click PC "https://github.com/badw/puppy/blob/main/pyproject.toml"
    click SO "https://github.com/badw/puppy/tree/main/static/"

    %% Styles
    classDef example fill:#E8F1FC,stroke:#2B6CB0,color:#2B6CB0;
    classDef core fill:#F0FFF4,stroke:#38A169,color:#2F855A;
    classDef data fill:#FFF5F5,stroke:#E53E3E,color:#C53030,stroke-dasharray: 5 5;
    classDef external fill:#FFFFF0,stroke:#D69E2E,color:#B7791F;
    classDef output fill:#EDF2F7,stroke:#4A5568,color:#2D3748;
    classDef config fill:#FEFCBF,stroke:#D69E2E,color:#975A16;
    classDef deprecated fill:#F7FAFC,stroke:#A0AEC0,color:#718096,stroke-dasharray: 2 2;
```
