# zxcalc/pyzx architecture

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

- Interactive diagram: https://gitdiagram.com/zxcalc/pyzx
- Repository: https://github.com/zxcalc/pyzx

## Overview

##### Main Components
- Core Library (pyzx package): This is the heart of the system and is organized into several submodules. Its main components include:
- Circuit Parsing: Located in pyzx/circuit, these modules (e.g. gates.py, qasmparser.py, qcparser.py, etc.) are responsible for reading and converting input circuit files.
- Rewrite & Optimization Engine: Modules such as simplify.py, optmize.py, local_search, gadget_extract.py, and rules.py support the automated rewriting strategies and optimizations.
- Additional Utilities: Files related to linear algebra (linalg.py, linalg_c.pyx), simulation (simulate.py), and other supporting functionalities.

- Input/Output & Format Converters:
- Circuit Input: Support for multiple file formats (QASM, QC, Quipper, etc.) is reflected in dedicated parsers in the library.

- Command-line Interface & Demos:
- The __main__.py module enables running PyZX as a standalone command-line tool.
- The demos directory houses Jupyter notebooks that demonstrate various functionalities (from circuit generation to optimization and visualization).

- Test and Documentation Infrastructure:
- The tests directory includes unit and integration tests that validate each component.
- The docs and doc directories (with Sphinx configuration) and README provide usage instructions and background on the ZX-calculus.

##### Relationships and Interactions
- Visualization and Export: Once optimized, other modules handle visualization (drawing modules, TikZ export, D3 visualizations) and export the final circuit in the requested format.
- CLI and Demos: The user interacts with the system either via CLI commands invoking main modules (e.g., using “python -m pyzx opt …”) or through interactive Jupyter demos.

##### Architectural Patterns and Design Principles
- Modular Design: The separation into distinct submodules (for parsing, graph manipulation, optimization, and visualization) follows a clean modular architecture.
- Separation of Concerns: Each component (e.g., input parsing, internal representation, optimization logic, and output rendering) is encapsulated in a dedicated module.
- Extensibility: The design allows for additional file formats, rewriting rules, or visualization tools to be plugged in with minimal changes to the core logic.

##### Relevant Technologies and Libraries
- Python as the core language, making use of packages such as NumPy where needed.
- Jupyter for demos and interactive notebooks.
- Visualization libraries such as Matplotlib and TikZ (for LaTeX export) along with custom JavaScript for web-based diagramming.
- Continuous integration via GitHub workflows and standard testing frameworks (as seen in the tests folder).

– “Circuit Parsing” ↔ “Graph Representation”
– “Rewrite & Optimization Engine” (possibly with links to “Local Search” and “Rule Engine”)
– “Visualization/Output” (incorporating drawing, TikZ, and web-based views)
- An “User Interface” area showing the CLI entry point and interactive demos.
- Auxiliary components such as “Testing” and “Documentation” can be depicted as supporting blocks.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Parsing Layer
    subgraph "Input & Parsing"
        CP["Circuit Parsing"]:::core
    end

    %% Core Processing Layer
    subgraph "Core Processing"
        GR["Graph Representation & Manipulation"]:::core
        subgraph "Rewrite & Optimization Engine"
            OP_Core["Core Optimization Files"]:::opt
            LS["Local Search Strategies"]:::opt
            AR["Additional Rewrite Rules"]:::opt
        end
        AU["Additional Utilities"]:::util
    end

    %% Output & Visualization Layer
    subgraph "Output & Visualization"
        subgraph "Visualization Tools"
            VT_Draw["Drawing"]:::opt
            VT_Tikz["TikZ Export"]:::opt
            VT_D3["D3/JS Visualization"]:::opt
        end
    end

    %% Interfaces
    subgraph "Interfaces"
        CLI["Command-line Interface"]:::cli
        Demos["Demos & Interactive Notebooks"]:::cli
    end

    %% Support Infrastructure
    subgraph "Support"
        Tests["Test Infrastructure"]:::test
        Docs["Documentation"]:::doc
    end

    %% Data flow connections
    CP -->|"parses_to"| GR
    GR -->|"generates_diagram"| OP_Core
    OP_Core -->|"applies_optimizations"| LS
    LS -->|"refines_graph"| AR
    AR -->|"outputs"| VT_Draw
    AR -->|"outputs"| VT_Tikz
    AR -->|"outputs"| VT_D3
    AU -->|"supports"| GR
    AU -->|"supports"| OP_Core

    %% Interface interactions (dotted lines)
    CLI -.->|"initiate"| CP
    Demos -.->|"interact_with"| CP

    %% Support interactions (dashed lines)
    Tests ---|"validate"| CP
    Docs ---|"instructs"| CP

    %% Styles
    classDef core fill:#ABEBC6,stroke:#196F3D,stroke-width:2px;
    classDef opt fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef util fill:#F9E79F,stroke:#7D6608,stroke-width:2px;
    classDef cli fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef test fill:#FAD7A0,stroke:#AF601A,stroke-width:2px;
    classDef doc fill:#D5F5E3,stroke:#239B56,stroke-width:2px;

    %% Click Events
    click CP "https://github.com/zxcalc/pyzx/tree/master/pyzx/circuit"
    click GR "https://github.com/zxcalc/pyzx/tree/master/pyzx/graph"
    click OP_Core "https://github.com/zxcalc/pyzx/blob/master/pyzx/optimize.py"
    click LS "https://github.com/zxcalc/pyzx/tree/master/pyzx/local_search"
    click AR "https://github.com/zxcalc/pyzx/blob/master/pyzx/rules.py"
    click VT_Draw "https://github.com/zxcalc/pyzx/blob/master/pyzx/drawing.py"
    click VT_Tikz "https://github.com/zxcalc/pyzx/blob/master/pyzx/tikz.py"
    click VT_D3 "https://github.com/zxcalc/pyzx/blob/master/pyzx/d3.py"
    click AU "https://github.com/zxcalc/pyzx/blob/master/pyzx/linalg.py"
    click CLI "https://github.com/zxcalc/pyzx/blob/master/pyzx/__main__.py"
    click Demos "https://github.com/zxcalc/pyzx/tree/master/demos"
    click Tests "https://github.com/zxcalc/pyzx/tree/master/tests"
    click Docs "https://github.com/zxcalc/pyzx/tree/master/doc"
```
