# omkarbihani/cks-algorithm architecture

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

- Interactive diagram: https://gitdiagram.com/omkarbihani/cks-algorithm
- Repository: https://github.com/omkarbihani/cks-algorithm

## Overview

This research prototype builds Qiskit circuits approximating A⁻¹ for a quantum linear-systems problem, with Fourier and Chebyshev/quantum-walk approaches. A user supplies and validates (A, b), chooses a method and configuration, and receives a circuit whose success branch encodes the solution state. The Fourier route uses Hamiltonian evolutions directly on the system register; the Chebyshev route builds a walk operator and uses an enlarged register. The graph follows documented workflows and excerpted calls; postselection is described, but no separate result-processing or amplification implementation is shown.

Main entry points: [`lcu/chebyshev.py`](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py) (Chebyshev circuit), [`lcu/fourier.py`](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py) (Fourier circuit), [`problem.py`](https://github.com/omkarbihani/cks-algorithm/blob/main/problem.py) (Problem validation), [`common.py`](https://github.com/omkarbihani/cks-algorithm/blob/main/common.py) (State preparation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Problem input"]
  node_problem["Problem validation<br/>[problem.py]"]
  node_numeric["Numerical checks<br/>[utils.py]"]
end

subgraph group_fourier["Fourier approach"]
  node_fourier_approx["Fourier terms<br/>[fourier.py]"]
  node_evolution["Hamiltonian evolution<br/>[evolution.py]"]
  node_fourier_select["Fourier SELECT<br/>[fourier.py]"]
  node_fourier_circuit["Fourier circuit<br/>[fourier.py]"]
end

subgraph group_chebyshev["Chebyshev approach"]
  node_cheb_rescale["Matrix rescaling<br/>[chebyshev.py]"]
  node_walk["Walk construction<br/>[chebyshev.py]"]
  node_cheb_approx["Chebyshev terms<br/>[chebyshev.py]"]
  node_cheb_select["Walk SELECT<br/>[chebyshev.py]"]
  node_cheb_circuit["Chebyshev circuit<br/>[chebyshev.py]"]
end

subgraph group_shared["Shared LCU and gates"]
  node_lcu_types["LCU representation<br/>[common.py]"]
  node_state_prep["State preparation<br/>[common.py]"]
  node_gate_helpers["Gate conversion<br/>[qc_utils.py]"]
  node_pauli_decomp["Pauli decomposition<br/>[qc_utils.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"supplies inputs"| node_problem
node_problem -->|"validates with"| node_numeric
node_researcher -->|"chooses method"| node_fourier_circuit
node_researcher -->|"chooses method"| node_cheb_circuit
node_fourier_circuit -->|"reads problem"| node_problem
node_fourier_circuit -->|"builds terms"| node_fourier_approx
node_fourier_approx -->|"requests evolution"| node_evolution
node_evolution -->|"decomposes Hamiltonian"| node_pauli_decomp
node_fourier_circuit -->|"builds SELECT"| node_fourier_select
node_fourier_circuit -->|"prepares states"| node_state_prep
node_fourier_circuit -->|"converts gates"| node_gate_helpers
node_fourier_approx -->|"creates terms"| node_lcu_types
node_cheb_circuit -->|"reads problem"| node_problem
node_cheb_circuit -->|"rescales matrix"| node_cheb_rescale
node_cheb_rescale -->|"provides scaled matrix"| node_walk
node_cheb_circuit -->|"builds terms"| node_cheb_approx
node_cheb_approx -->|"builds walk powers"| node_walk
node_cheb_approx -->|"creates terms"| node_lcu_types
node_cheb_circuit -->|"builds SELECT"| node_cheb_select
node_cheb_circuit -->|"prepares states"| node_state_prep
node_cheb_circuit -->|"converts gates"| node_gate_helpers
node_state_prep -->|"creates gate"| node_gate_helpers

click node_problem "https://github.com/omkarbihani/cks-algorithm/blob/main/problem.py"
click node_numeric "https://github.com/omkarbihani/cks-algorithm/blob/main/utils.py"
click node_fourier_approx "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py"
click node_evolution "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/evolution.py"
click node_fourier_select "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py"
click node_fourier_circuit "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py"
click node_cheb_rescale "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py"
click node_walk "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py"
click node_cheb_approx "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py"
click node_cheb_select "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py"
click node_cheb_circuit "https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py"
click node_lcu_types "https://github.com/omkarbihani/cks-algorithm/blob/main/common.py"
click node_state_prep "https://github.com/omkarbihani/cks-algorithm/blob/main/common.py"
click node_gate_helpers "https://github.com/omkarbihani/cks-algorithm/blob/main/qc_utils.py"
click node_pauli_decomp "https://github.com/omkarbihani/cks-algorithm/blob/main/qc_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_problem,node_numeric toneBlue
class node_fourier_approx,node_evolution,node_fourier_select,node_fourier_circuit toneAmber
class node_cheb_rescale,node_walk,node_cheb_approx,node_cheb_select,node_cheb_circuit toneMint
class node_lcu_types,node_state_prep,node_gate_helpers,node_pauli_decomp toneRose
class node_researcher toneIndigo
```

## Components

### Problem input

- [Problem validation](https://github.com/omkarbihani/cks-algorithm/blob/main/problem.py): `problem.py`
- [Numerical checks](https://github.com/omkarbihani/cks-algorithm/blob/main/utils.py): `utils.py`

### Fourier approach

- [Fourier terms](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py): `lcu/fourier.py`
- [Hamiltonian evolution](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/evolution.py): `lcu/evolution.py`
- [Fourier SELECT](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py): `lcu/fourier.py`
- [Fourier circuit](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/fourier.py): `lcu/fourier.py`

### Chebyshev approach

- [Matrix rescaling](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py): `lcu/chebyshev.py`
- [Walk construction](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py): `lcu/chebyshev.py`
- [Chebyshev terms](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py): `lcu/chebyshev.py`
- [Walk SELECT](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py): `lcu/chebyshev.py`
- [Chebyshev circuit](https://github.com/omkarbihani/cks-algorithm/blob/main/lcu/chebyshev.py): `lcu/chebyshev.py`

### Shared LCU and gates

- [LCU representation](https://github.com/omkarbihani/cks-algorithm/blob/main/common.py): `common.py`
- [State preparation](https://github.com/omkarbihani/cks-algorithm/blob/main/common.py): `common.py`
- [Gate conversion](https://github.com/omkarbihani/cks-algorithm/blob/main/qc_utils.py): `qc_utils.py`
- [Pauli decomposition](https://github.com/omkarbihani/cks-algorithm/blob/main/qc_utils.py): `qc_utils.py`

### Other components

- **Researcher**

## Connections

- Researcher → Problem validation: supplies inputs (evidence: `README.md`)
- Problem validation → Numerical checks: validates with (evidence: `problem.py`)
- Researcher → Fourier circuit: chooses method (evidence: `README.md`)
- Researcher → Chebyshev circuit: chooses method (evidence: `README.md`)
- Fourier circuit → Problem validation: reads problem (evidence: `lcu/fourier.py`)
- Fourier circuit → Fourier terms: builds terms (evidence: `lcu/fourier.py`)
- Fourier terms → Hamiltonian evolution: requests evolution (evidence: `lcu/fourier.py`)
- Hamiltonian evolution → Pauli decomposition: decomposes Hamiltonian (evidence: `lcu/evolution.py`)
- Fourier circuit → Fourier SELECT: builds SELECT (evidence: `lcu/fourier.py`)
- Fourier circuit → State preparation: prepares states (evidence: `lcu/fourier.py`)
- Fourier circuit → Gate conversion: converts gates (evidence: `lcu/fourier.py`)
- Fourier terms → LCU representation: creates terms (evidence: `lcu/fourier.py`)
- Chebyshev circuit → Problem validation: reads problem (evidence: `lcu/chebyshev.py`)
- Chebyshev circuit → Matrix rescaling: rescales matrix (evidence: `lcu/chebyshev.py`)
- Matrix rescaling → Walk construction: provides scaled matrix (evidence: `lcu/chebyshev.py`)
- Chebyshev circuit → Chebyshev terms: builds terms (evidence: `lcu/chebyshev.py`)
- Chebyshev terms → Walk construction: builds walk powers (evidence: `lcu/chebyshev.py`)
- Chebyshev terms → LCU representation: creates terms (evidence: `lcu/chebyshev.py`)
- Chebyshev circuit → Walk SELECT: builds SELECT (evidence: `lcu/chebyshev.py`)
- Chebyshev circuit → State preparation: prepares states (evidence: `lcu/chebyshev.py`)
- Chebyshev circuit → Gate conversion: converts gates (evidence: `lcu/chebyshev.py`)
- State preparation → Gate conversion: creates gate (evidence: `common.py`)
