# josquantum/hyvis architecture

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

- Interactive diagram: https://gitdiagram.com/josquantum/hyvis
- Repository: https://github.com/josquantum/hyvis

## Overview

##### Project type and purpose
- This is a Python‑based visualization library (“hyvis”) for exploring and rendering high‑dimensional function landscapes (especially quantum‑classical hybrid systems).
- It ships as a pip‑installable package, provides core modules, and includes example Jupyter notebooks demonstrating its features.

##### File structure
- Top‑level folders and files:
- src/hyvis/           ← core Python modules
- notebooks/           ← Jupyter notebooks for demos
- pictures/            ← sample output images/gifs
- dist/                ← built distribution artifacts (wheel, sdist)
- pyproject.toml       ← packaging/metadata configuration
- README.md, LICENSE  ← documentation & legal
- No separate “frontend/backend” layers—this is a library supporting both computation and visualization.
- Key modules:
- dr_tools.py          ← tools for defining affine linear subspaces
- native_landscapes.py ← landscape scanning & Hessian calculations
- video_scans.py       ← video generation of trajectories
- Packaging pipeline: pyproject.toml → build → dist/

##### README for additional insights
- Features: subspace creation, scanning, Hessian‑based visualization, video output.
- Dependencies (implicit): numpy, matplotlib (for plotting), moviepy or ffmpeg (for GIF/video).
- Usage model: users write code or open notebooks that import hyvis.* functions.

a. Main components
1. User Layer
- Jupyter notebooks & user scripts
2. hyvis Core Library
- dr_tools module
- native_landscapes module
- video_scans module
3. Visualization Engine
- matplotlib (plots)
- moviepy/ffmpeg (animations)
4. Packaging/Distribution
- pyproject.toml build process
- dist artifacts on PyPI
b. Relationships and interactions
- Notebooks & scripts → import → hyvis core modules
- dr_tools → supplies subspace definitions → native_landscapes
- native_landscapes → computes scans/Hessians → passes data to video_scans or plotting
- video_scans → invokes external video library → produces .gif/.mp4
- Packaging tool → reads pyproject.toml → outputs wheel & sdist → deployed to PyPI
c. Architectural patterns & principles
- Modular library design: each major feature lives in its own module
- Separation of concerns: computation (landscapes) vs. visualization vs. packaging
- Demonstration layer (notebooks) decoupled from core logic
d. Key technologies/frameworks
- Python
- NumPy (numerical arrays)
- Matplotlib (2D/3D plots)
- MoviePy/FFmpeg (video)
- setuptools/poetry (packaging via pyproject.toml)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User Layer"
        User["Notebooks & Scripts"]:::user
    end

    %% Core Library Modules
    subgraph "hyvis Core Library"
        dr_tools["dr_tools"]:::core
        native_landscapes["native_landscapes"]:::core
        video_scans["video_scans"]:::core
    end

    %% Visualization Engine
    subgraph "Visualization Engine"
        Matplotlib["Matplotlib"]:::external
        MoviePy["MoviePy/FFmpeg"]:::external
    end

    %% Packaging Pipeline
    subgraph "Packaging & Distribution"
        pyproject["pyproject.toml"]:::packaging
        Build["Build Process"]:::packaging
        dist["dist/*"]:::packaging
    end

    %% Documentation & Assets
    subgraph "Documentation & Assets"
        README["README.md"]:::doc
        LICENSE["LICENSE.txt"]:::doc
        pictures["pictures/"]:::external
    end

    %% Connections
    User -->|imports| dr_tools
    User -->|imports| native_landscapes
    User -->|imports| video_scans

    dr_tools -->|subspace params| native_landscapes
    native_landscapes -->|Hessian matrix| video_scans
    native_landscapes -->|plot object| Matplotlib
    video_scans -->|video data| MoviePy

    pyproject -->|configures| Build
    Build -->|outputs wheel/sdist| dist

    %% Assets usage
    video_scans -->|generates| pictures

    %% Click Events
    click User "https://github.com/josquantum/hyvis/tree/main/notebooks/"
    click dr_tools "https://github.com/josquantum/hyvis/blob/main/src/hyvis/dr_tools.py"
    click native_landscapes "https://github.com/josquantum/hyvis/blob/main/src/hyvis/native_landscapes.py"
    click video_scans "https://github.com/josquantum/hyvis/blob/main/src/hyvis/video_scans.py"
    click pictures "https://github.com/josquantum/hyvis/tree/main/pictures/"
    click pyproject "https://github.com/josquantum/hyvis/blob/main/pyproject.toml"
    click dist "https://github.com/josquantum/hyvis/tree/main/dist/"
    click README "https://github.com/josquantum/hyvis/blob/main/README.md"
    click LICENSE "https://github.com/josquantum/hyvis/blob/main/LICENSE.txt"

    %% Styles
    classDef user fill:#f9d,stroke:#333,stroke-width:1px
    classDef core fill:#9cf,stroke:#333,stroke-width:1px
    classDef external fill:#cfc,stroke:#333,stroke-width:1px
    classDef packaging fill:#ddd,stroke:#333,stroke-width:1px
    classDef doc fill:#ddf,stroke:#333,stroke-width:1px
```
