# nkuetemeli/bvns architecture

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

- Interactive diagram: https://gitdiagram.com/nkuetemeli/bvns
- Repository: https://github.com/nkuetemeli/bvns

## Overview

BVNs is a research implementation of quantum-interference models for supervised classification and implicit image fitting. The main workflow prepares labeled samples, runs a standard or generalized BVN circuit on a quantum simulator, fits an interference-basis representation from measurement counts, and predicts or reconstructs outputs. The README also highlights reversible-ReLU and rectangle representations, generalized interference bases, and noisy simulation. Some training and circuit details are only partially excerpted, so unverified links are omitted.

Main entry points: [`src/bvn_rect_act.py`](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_rect_act.py) (Rectangle BVN), [`src/bvn_relu_act.py`](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_act.py) (ReLU experiments), [`src/bvn_img_fitting.py`](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_img_fitting.py) (Image fitting), [`src/dataset.py`](https://github.com/nkuetemeli/bvns/blob/main/src/dataset.py) (Dataset preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiments["Experiment workflows"]
  node_relu_workflow["ReLU experiments<br/>[bvn_relu_act.py]"]
  node_rectangle_workflow["Rectangle experiments<br/>[bvn_rect_act.py]"]
  node_image_workflow["Image fitting<br/>[bvn_img_fitting.py]"]
end

subgraph group_data["Data and results"]
  node_dataset["Dataset preparation<br/>[dataset.py]"]
  node_fit_utils["Basis fitting<br/>[utils.py]"]
  node_image_result["Image reconstruction<br/>[bvn_img_fitting.py]"]
end

subgraph group_models["BVN models"]
  node_relu_model["ReLU BVN<br/>[bvn_relu_act.py]"]
  node_mask_model["Rectangle BVN<br/>[bvn_rect_act.py]"]
  node_layers["BV layers<br/>[bvn_relu_layers.py]"]
end

subgraph group_quantum["Quantum operations"]
  node_relu_op["Reversible ReLU<br/>[utils_relu.py]"]
  node_mask_op["Mask operation<br/>[utils_mask.py]"]
  node_simulator["Quantum simulator"]
  node_interference["Interference bases<br/>[utils.py]"]
  node_noisy_backend["Noisy simulator"]
end

node_user(("Researcher"))

node_user -->|"runs experiment"| node_relu_workflow
node_user -->|"runs experiment"| node_rectangle_workflow
node_user -->|"runs fitting"| node_image_workflow
node_relu_workflow -->|"loads samples"| node_dataset
node_rectangle_workflow -->|"loads samples"| node_dataset
node_image_workflow -->|"loads image"| node_dataset
node_image_workflow -->|"runs model"| node_mask_model
node_image_workflow -->|"reconstructs image"| node_image_result
node_relu_workflow -->|"configures model"| node_relu_model
node_rectangle_workflow -->|"configures model"| node_mask_model
node_relu_model -->|"builds layers"| node_layers
node_layers -->|"applies operation"| node_relu_op
node_mask_model -->|"applies operation"| node_mask_op
node_relu_model -->|"runs circuit"| node_simulator
node_mask_model -->|"runs circuit"| node_simulator
node_relu_workflow -->|"configures noise"| node_noisy_backend
node_rectangle_workflow -->|"configures noise"| node_noisy_backend
node_relu_model -->|"evaluates basis"| node_interference
node_mask_model -->|"evaluates basis"| node_interference
node_fit_utils --> node_dataset

click node_relu_workflow "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_act.py"
click node_rectangle_workflow "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_rect_act.py"
click node_image_workflow "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_img_fitting.py"
click node_dataset "https://github.com/nkuetemeli/bvns/blob/main/src/dataset.py"
click node_fit_utils "https://github.com/nkuetemeli/bvns/blob/main/src/utils.py"
click node_relu_model "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_act.py"
click node_mask_model "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_rect_act.py"
click node_layers "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_layers.py"
click node_relu_op "https://github.com/nkuetemeli/bvns/blob/main/src/utils_relu.py"
click node_mask_op "https://github.com/nkuetemeli/bvns/blob/main/src/utils_mask.py"
click node_image_result "https://github.com/nkuetemeli/bvns/blob/main/src/bvn_img_fitting.py"
click node_interference "https://github.com/nkuetemeli/bvns/blob/main/src/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_relu_workflow,node_rectangle_workflow,node_image_workflow toneBlue
class node_dataset,node_fit_utils,node_image_result toneAmber
class node_relu_model,node_mask_model,node_layers toneMint
class node_relu_op,node_mask_op,node_simulator,node_interference,node_noisy_backend toneRose
class node_user toneIndigo
```

## Components

### Experiment workflows

- [ReLU experiments](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_act.py): `src/bvn_relu_act.py`
- [Rectangle experiments](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_rect_act.py): `src/bvn_rect_act.py`
- [Image fitting](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_img_fitting.py): `src/bvn_img_fitting.py`

### Data and results

- [Dataset preparation](https://github.com/nkuetemeli/bvns/blob/main/src/dataset.py): `src/dataset.py`
- [Basis fitting](https://github.com/nkuetemeli/bvns/blob/main/src/utils.py): `src/utils.py`
- [Image reconstruction](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_img_fitting.py): `src/bvn_img_fitting.py`

### BVN models

- [ReLU BVN](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_act.py): `src/bvn_relu_act.py`
- [Rectangle BVN](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_rect_act.py): `src/bvn_rect_act.py`
- [BV layers](https://github.com/nkuetemeli/bvns/blob/main/src/bvn_relu_layers.py): `src/bvn_relu_layers.py`

### Quantum operations

- [Reversible ReLU](https://github.com/nkuetemeli/bvns/blob/main/src/utils_relu.py): `src/utils_relu.py`
- [Mask operation](https://github.com/nkuetemeli/bvns/blob/main/src/utils_mask.py): `src/utils_mask.py`
- **Quantum simulator**
- [Interference bases](https://github.com/nkuetemeli/bvns/blob/main/src/utils.py): `src/utils.py`
- **Noisy simulator**

### Other components

- **Researcher**

## Connections

- Researcher → ReLU experiments: runs experiment (evidence: `README.md`)
- Researcher → Rectangle experiments: runs experiment (evidence: `README.md`)
- Researcher → Image fitting: runs fitting (evidence: `README.md`)
- ReLU experiments → Dataset preparation: loads samples (evidence: `src/bvn_relu_act.py`)
- Rectangle experiments → Dataset preparation: loads samples (evidence: `src/bvn_rect_act.py`)
- Image fitting → Dataset preparation: loads image (evidence: `src/bvn_img_fitting.py`)
- Image fitting → Rectangle BVN: runs model (evidence: `src/bvn_img_fitting.py`)
- Image fitting → Image reconstruction: reconstructs image (evidence: `src/bvn_img_fitting.py`)
- ReLU experiments → ReLU BVN: configures model (evidence: `src/bvn_relu_act.py`)
- Rectangle experiments → Rectangle BVN: configures model (evidence: `src/bvn_rect_act.py`)
- ReLU BVN → BV layers: builds layers (evidence: `src/bvn_relu_act.py`)
- BV layers → Reversible ReLU: applies operation (evidence: `src/bvn_relu_layers.py`)
- Rectangle BVN → Mask operation: applies operation (evidence: `src/bvn_rect_act.py`)
- ReLU BVN → Quantum simulator: runs circuit (evidence: `src/bvn_relu_act.py`)
- Rectangle BVN → Quantum simulator: runs circuit (evidence: `src/bvn_rect_act.py`)
- ReLU experiments → Noisy simulator: configures noise (evidence: `src/bvn_relu_act.py`)
- Rectangle experiments → Noisy simulator: configures noise (evidence: `src/bvn_rect_act.py`)
- ReLU BVN → Interference bases: evaluates basis (evidence: `src/bvn_relu_act.py`)
- Rectangle BVN → Interference bases: evaluates basis (evidence: `src/bvn_rect_act.py`)
- Basis fitting → Dataset preparation
