# blakktyger/toqito architecture

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

- Interactive diagram: https://gitdiagram.com/blakktyger/toqito
- Repository: https://github.com/blakktyger/toqito

## Overview

##### Project Type and Purpose
- toqito is an open-source Python toolkit (library) for quantum information.
- It provides numerical tools around quantum states, channels, measurements, and nonlocal games.
- Users import components from the `toqito` namespace; no client-server or UI layers exist.

##### High-Level Structure
- Top-level package: `toqito/`
- Core subpackages (each encapsulating a domain):
- `states`           — definitions of standard quantum states
- `channels`         — common quantum channels (e.g., bitflip, depolarizing)
- `measurements`     — measurement strategies
- `nonlocal_games`   — implementations of nonlocal (XOR) games
- `rand`             — random state/channel/measurement generators
- `matrix_ops`       — tensor, vector/matrix transforms
- `matrix_props`     — tests on matrices (Hermitian, positive, etc.)
- `channel_ops`      — channel representations (Choi ↔ Kraus, apply, partial)
- `channel_metrics`  — distances and norms on channels
- `measurement_ops`  — measurement application routines
- `measurement_props`— checks for valid POVMs
- `state_ops`        — state operations (e.g., Schmidt decomp)
- `state_metrics`    — fidelity, distance measures for states
- `state_props`      — properties of quantum states (purity, entanglement)
- `state_opt`        — optimization tasks (state discrimination, extension hierarchies)
- `perms`            — permutation operators, projections
- `helper`           — internal utilities (dimensions, odometer, NPA hierarchies)
- Supporting directories:
- `docs/`            — Sphinx documentation sources
- `.github/`         — CI, issue/pr templates
- Tests are co-located under each subpackage’s `tests/` folder.

##### Component Relationships
- Helper utilities (`helper`) sit at the bottom layer: many modules import dimension routines or array converters.
- Data objects (states, channels, measurements) form the primary domain model.
- “Ops” subpackages (e.g., `matrix_ops`, `channel_ops`, `measurement_ops`, `state_ops`) consume data objects to perform transformations.
- “Props” and “metrics” modules analyze these objects (tests & distances).
- `nonlocal_games` depends on states, measurements, and optimizers from `state_opt` for quantum values.
- `rand` can generate instances used by any domain (states, channels, measurements).

##### Diagramming Guidance for an Open-Source Toolkit
a. Components
b. Interactions
- states → state_ops → state_props / state_metrics
- channels → channel_ops → channel_metrics
- measurements → measurement_ops → measurement_props
- states + measurements + state_opt → nonlocal_games
- rand → states / channels / measurements
c. Architectural Patterns
- Layered architecture:
1. Data Models (states, channels, measurements)
2. Operations (…_ops)
3. Analysis (…_props, …_metrics)
4. High-level workflows (nonlocal_games, state_opt)
- Utility layer (helper) underpins all.
d. Technologies & Tools
- Python 3.10–3.12
- pytest for testing
- Sphinx for docs
- GitHub Actions for CI/CD

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% High-level Workflows
    subgraph "High-level Workflows"
        direction TB
        NL["nonlocal_games"]:::workflow
        SO["state_opt"]:::workflow
    end

    %% Analysis Layer
    subgraph "Analysis (Props & Metrics)"
        direction TB
        MP["matrix_props"]:::analysis
        CP["channel_props"]:::analysis
        CM["channel_metrics"]:::analysis
        MPR["measurement_props"]:::analysis
        SP["state_props"]:::analysis
        SM["state_metrics"]:::analysis
    end

    %% Operations Layer
    subgraph "Operations (_ops)"
        direction TB
        MO["matrix_ops"]:::ops
        CO["channel_ops"]:::ops
        MEO["measurement_ops"]:::ops
        SOps["state_ops"]:::ops
    end

    %% Data Models
    subgraph "Data Models"
        direction TB
        ST["states"]:::models
        CH["channels"]:::models
        ME["measurements"]:::models
        PR["perms"]:::models
    end

    %% Random Generators
    RG["rand"]:::rand

    %% Utility Layer
    HEL["helper"]:::helper

    %% External Tools
    S["Sphinx docs"]:::external
    T["pytest"]:::external
    CI["GitHub Actions"]:::external

    %% Relationships
    ST -->|uses| SOps
    SOps -->|analysis| SP
    SOps -->|analysis| SM

    CH -->|uses| CO
    CO -->|analysis| CM
    CO -->|analysis| CP

    ME -->|uses| MEO
    MEO -->|analysis| MPR

    ST -->|data| NL
    ME -->|data| NL
    SO -->|optimizes| NL

    RG -->|generates| ST
    RG -->|generates| CH
    RG -->|generates| ME

    SO -->|uses| SOps

    MP -->|tests| MO

    %% Helper imports
    HEL --> ST
    HEL --> CH
    HEL --> ME
    HEL --> PR
    HEL --> MO
    HEL --> CO
    HEL --> MEO
    HEL --> SOps
    HEL --> SP
    HEL --> SM
    HEL --> CM
    HEL --> CP
    HEL --> MPR

    %% External placements
    S -.->|docs source| ST
    CI -.->|CI/CD| ST
    T -.->|tests| ST

    %% Click Events
    click ST "https://github.com/blakktyger/toqito/tree/master/toqito/states/"
    click CH "https://github.com/blakktyger/toqito/tree/master/toqito/channels/"
    click ME "https://github.com/blakktyger/toqito/tree/master/toqito/measurements/"
    click NL "https://github.com/blakktyger/toqito/tree/master/toqito/nonlocal_games/"
    click PR "https://github.com/blakktyger/toqito/tree/master/toqito/perms/"
    click HEL "https://github.com/blakktyger/toqito/tree/master/toqito/helper/"
    click MO "https://github.com/blakktyger/toqito/tree/master/toqito/matrix_ops/"
    click CO "https://github.com/blakktyger/toqito/tree/master/toqito/channel_ops/"
    click MEO "https://github.com/blakktyger/toqito/tree/master/toqito/measurement_ops/"
    click SOps "https://github.com/blakktyger/toqito/tree/master/toqito/state_ops/"
    click MP "https://github.com/blakktyger/toqito/tree/master/toqito/matrix_props/"
    click CP "https://github.com/blakktyger/toqito/tree/master/toqito/channel_props/"
    click CM "https://github.com/blakktyger/toqito/tree/master/toqito/channel_metrics/"
    click MPR "https://github.com/blakktyger/toqito/tree/master/toqito/measurement_props/"
    click SP "https://github.com/blakktyger/toqito/tree/master/toqito/state_props/"
    click SM "https://github.com/blakktyger/toqito/tree/master/toqito/state_metrics/"
    click SO "https://github.com/blakktyger/toqito/tree/master/toqito/state_opt/"
    click RG "https://github.com/blakktyger/toqito/tree/master/toqito/rand/"
    click S "https://github.com/blakktyger/toqito/tree/master/docs/"
    click CI "https://github.com/blakktyger/toqito/tree/master/.github/workflows/"

    %% Styles
    classDef models fill:#cce5ff,stroke:#1f77b4,color:#1f77b4;
    classDef ops fill:#d4edda,stroke:#28a745,color:#28a745;
    classDef analysis fill:#fff3cd,stroke:#ffc107,color:#856404;
    classDef workflow fill:#e2d5f7,stroke:#6f42c1,color:#6f42c1;
    classDef helper fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef external stroke-dasharray: 5 5,fill:#f8f9fa,stroke:#343a40,color:#343a40;
```
