# netqir/netqir-sdk architecture

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

- Interactive diagram: https://gitdiagram.com/netqir/netqir-sdk
- Repository: https://github.com/netqir/netqir-sdk

## Overview

##### Project type and purpose
- This is an open‑source SDK (library) named “NetQIR SDK,” specifically the Python implementation called PyNetQIR.
- Its purpose is to let developers write and assemble quantum programs (QIR/NetQIR) in Python, using a high‑level builder API that targets the Microsoft Quantum Intermediate Representation (QIR) extended with NetQIR communication primitives.

##### File structure
Top‑level:
- setup.py, LICENSE, README.md – packaging and documentation
- python/ – the PyNetQIR package root
Under python/pynetqir:
- core/ – the main builder and program runtime
– builders/ – ScopeBuilder implementations (MainScopeBuilder, FunctionScopeBuilder)
– operation/ – IR node definitions (assembly ops, quantum ops, conditional, function, netqir comm ops, scopes)
– program.py – the Program façade (start, run, end, global state)
– traslation/ – translator/executor framework (printer executor, others)
- datatypes/ – definitions of QIR and NetQIR data types (Qubit, Result, Communicator, Rank)
- examples/ – sample Python scripts demonstrating teleporation and qsend/qrecv

Architectural clues:
– Builder pattern for constructing scopes and operations
– Core IR layer separated from datatypes
– Translation layer pluggable via executors (e.g., printer)

##### Key insights from README
– Program object coordinates lifecycle (start/end/run)
– Builders add operations to “global scope” or function scopes
– Example flows: Teleportation, NetQIR send/receive with conditional branching
– Emphasis on quantum and classical control, plus communicator initialization/finalization

a. Main components
1. User Code (python/examples)
2. Program API (Program class)
3. Scope Builders (MainScopeBuilder, FunctionScopeBuilder)
4. Operation IR Layer (operation.* modules)
5. Datatypes Layer (datatypes.* modules)
6. Translation/Executor Layer (executor printer, other executors)
7. External QIR/NetQIR Runtime (native runtime or simulator invoked by executor)

b. Relationships & interactions
– User Code calls Program.start()/get_global_scope()
– Builders invoke program IR methods to append Operation nodes
– Operation IR forms a tree/graph under Program
– At Program.run(), the Translation layer traverses the IR, serializes to QIR/NetQIR or invokes a backend executor
– Datatypes flow through builders and operations to represent registers, qubits, communicators
– Executor passes code to External Runtime or prints text

c. Architectural patterns & principles
– Builder Pattern: ScopeBuilder constructs sequences of Operation nodes
– Composite Pattern: Operation hierarchy represents nested scopes, functions, basic blocks
– Strategy Pattern: Multiple executors/printers can process the same IR
– Separation of Concerns: core (IR) vs datatypes vs translation/execution

d. Key technologies & frameworks
– Python 3.x packaging (setup.py)
– QIR (LLVM IR-based) and NetQIR extensions for communication
– asyncio or external MPI-like runtime (implied by communicator)

##### Elements
- Blue for user‑facing APIs (Program, Builders)
- Green for internal IR and datatypes
- Orange for translation/execution
- Gray for external systems
- Rectangles for modules
- Clouds for external runtimes

##### Final recommendations
- Lifecycle sequence: start() → build scopes → build IR → run() → translate → execute → end()
- Patterns (Builder, Composite, Strategy) where they occur to guide future contributors

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    subgraph "User Layer"
        direction TB
        UserCode["User Code\n(python/examples)"]:::frontend
    end

    %% Core API Layer
    subgraph "Core API" 
        direction TB
        Program["Program API\nProgram"]:::frontend
        Builders["Scope Builders\n(MainScopeBuilder, FunctionScopeBuilder)"]:::frontend
    end

    %% IR and Datatypes Layer
    subgraph "IR & Datatypes" 
        direction TB
        subgraph "Operation IR Layer"
            direction TB
            OpBase["Core Operation Base\noperation.py"]:::internal
            AssemblyOps["Assembly Ops\nassembly/*.py"]:::internal
            ConditionalOps["Conditional Ops\nconditional.py"]:::internal
            FunctionOps["Function Ops\nfunction.py"]:::internal
            QuantumGates["Quantum Gates\ngates.py, gate.py"]:::internal
            NetQIRComm["NetQIR Communication Ops\ncommunication/*.py"]:::internal
            NetQIROps["NetQIR State & Ops\nnetqir_operations.py, netqir_state.py"]:::internal
            ScopeNodes["Scope Nodes\nscope/*.py"]:::internal
        end
        subgraph "Datatypes Layer"
            direction TB
            QubitDT["Qubit, Result\ndatatypes/qir/qubit.py, result.py"]:::internal
            NetQIRDT["Communicator, Enums, Rank\ndatatypes/netqir/communicator.py, enum_types.py, rank.py"]:::internal
            RegisterDT["Register\ndatatypes/register.py"]:::internal
        end
    end

    %% Translation/Execution Layer
    subgraph "Translation & Executors"
        direction TB
        ExecutorIface["Executor Interface\nexecutor.py"]:::exec
        PrinterExec["Printer Executor\nexecutors/printer.py"]:::exec
    end

    %% External Runtime
    subgraph "External Runtime"
        direction TB
        ExtRuntime["External QIR/NetQIR Runtime"]:::external
    end

    %% Packaging & Docs
    subgraph "Packaging & Documentation"
        direction TB
        Docs["setup.py, README.md, LICENSE"]:::docs
    end

    %% Flow
    UserCode -->|"import & invoke"| Program
    Program -->|"start(), get_global_scope()"| Builders
    Builders -->|"build() → Operation nodes"| OpBase
    Builders -->|"use datatypes"| QubitDT
    Builders -->|"use datatypes"| NetQIRDT
    Builders -->|"use datatypes"| RegisterDT
    OpBase -->|“composite scope”| ScopeNodes
    OpBase -->|"includes"| AssemblyOps
    OpBase -->|"includes"| ConditionalOps
    OpBase -->|"includes"| FunctionOps
    OpBase -->|"includes"| QuantumGates
    OpBase -->|"includes"| NetQIRComm
    OpBase -->|"includes"| NetQIROps
    OpBase -->|"traverse IR"| ExecutorIface
    ExecutorIface -->|"print or exec"| PrinterExec
    ExecutorIface -->|"invoke"| ExtRuntime
    Program -->|"run() → Executor"| ExecutorIface
    Program -->|"end()"| Docs

    %% Click Events
    click UserCode "https://github.com/netqir/netqir-sdk/tree/main/python/examples"
    click Program "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/program.py"
    click Builders "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/builders/scope_builder.py"
    click OpBase "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/operation.py"
    click AssemblyOps "https://github.com/netqir/netqir-sdk/tree/main/python/pynetqir/core/operation/assembly"
    click ConditionalOps "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/conditional.py"
    click FunctionOps "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/function.py"
    click QuantumGates "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/quantum/gates/gates.py"
    click QuantumGates "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/quantum/gates/gate.py"
    click NetQIRComm "https://github.com/netqir/netqir-sdk/tree/main/python/pynetqir/core/operation/quantum/netqir/communication"
    click NetQIROps "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/quantum/netqir/netqir_operations.py"
    click NetQIROps "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/operation/quantum/netqir/netqir_state.py"
    click ScopeNodes "https://github.com/netqir/netqir-sdk/tree/main/python/pynetqir/core/operation/scope"
    click QubitDT "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/datatypes/qir/qubit.py"
    click QubitDT "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/datatypes/qir/result.py"
    click NetQIRDT "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/datatypes/netqir/communicator.py"
    click NetQIRDT "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/datatypes/netqir/enum_types.py"
    click NetQIRDT "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/datatypes/netqir/rank.py"
    click RegisterDT "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/datatypes/register.py"
    click ExecutorIface "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/traslation/executor.py"
    click PrinterExec "https://github.com/netqir/netqir-sdk/blob/main/python/pynetqir/core/traslation/executors/printer.py"
    click Docs "https://github.com/netqir/netqir-sdk/blob/main/setup.py"
    click Docs "https://github.com/netqir/netqir-sdk/blob/main/README.md"
    click Docs "https://github.com/netqir/netqir-sdk/tree/main/LICENSE"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef internal fill:#E0F7E9,stroke:#22863A,color:#22863A;
    classDef exec fill:#FFEFD5,stroke:#DB6D00,color:#DB6D00;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
    classDef docs fill:#F5E1FD,stroke:#6F42C1,color:#6F42C1;
```
