# srijahn/moderna-challenge architecture

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

- Interactive diagram: https://gitdiagram.com/srijahn/moderna-challenge
- Repository: https://github.com/srijahn/moderna-challenge

## Overview

#### Purpose and execution model
This is a script-driven RNA secondary-structure research project for the WISER × Moderna challenge. It converts short RNA sequences into constrained QUBOs, solves them with simulated QAOA and CVaR-VQE, and evaluates decoded structures against ViennaRNA MFE references. There is no application server; entry points are executable Python workflows, notably `statistical_benchmark.py`, `generate_final_results.py`, and `compare_to_vienna.py`.

#### Sequence sets and classical reference boundary
Curated folding-positive workloads define the active experiments: `benchmark_sequences.py` supplies eight 8–14 nt sequences, while `test_sequences.py` supports smaller validation cases. ViennaRNA is the authoritative thermodynamic reference and candidate evaluator:
- `test_vienna.py`
- `structure_metrics.py`
- `official_example_benchmark.py`

`structure_metrics.py` calls ViennaRNA MFE folding and evaluates each candidate dot-bracket structure in comparable kcal/mol units, plus base-pair precision/recall/F1, pair distance, and Hamming distance. The 44-nt official example remains classical-only because its QUBO is infeasible for the simulated quantum solvers.

#### Default pair-indicator QUBO compilation
The central model is `rna_to_qubo_full.py`, which maps each feasible base pair to a binary variable/qubit. It includes Watson-Crick and G-U wobble candidates, minimum hairpin-loop constraints, and penalties for shared-nucleotide conflicts and crossing pairs (therefore excluding pseudoknots). It also provides brute-force validation for small instances.
- `rna_to_qubo_full.py`
- `rna_to_qubo.py`
- `qubo_energy.py`

This compiler is the boundary between RNA/domain constraints and generic binary optimization. Its simple pair-count-style objective is intentionally distinct from ViennaRNA thermodynamics, so a QUBO optimum may not be an MFE-optimal biological structure.

#### Quantum solver layer
Two independent PennyLane-based solvers consume the real QUBO, optimize circuit parameters, sample/decode binary assignments, and return structures/energies:
- `qaoa_rna_solver.py`
- `cvar_vqe_rna_solver.py`

Both use derivative-free SciPy COBYLA-style optimization rather than statevector backpropagation. QAOA is less scalable/reliable in batch use and is capped near 11 qubits for quality experiments; CVaR-VQE uses a two-local ansatz and is the more broadly run method. Statevector simulation, not quantum hardware, is the material execution runtime.

#### Evaluation and reproducible result production
The main flow is: curated sequence → QUBO compilation → solver trial(s) → assignment-to-dot-bracket decoding → ViennaRNA metric evaluation → CSV result table under `results/`.
- `statistical_benchmark.py`
- `batch_accuracy.py`
- `generate_final_results.py`

`statistical_benchmark.py` is the principal rigorous benchmark: repeated CVaR-VQE and QAOA trials produce trial-level and mean/std datasets. `final_summary.py` consumes final result and scaling tables for a human-readable aggregate report. `results/` is the sole generated-output boundary.

#### Scaling, noise, and feasibility studies
Separate workflows measure actual simulator resource behavior and robustness rather than extrapolated formulas:
- `scaling_analysis_real.py`
- `cvar_vqe_scaling_analysis.py`
- `noise_simulation.py`

They record qubits, depth/gates, forward runtime, and—only below optimization cutoffs—quality metrics. Noise experiments use PennyLane’s mixed-state simulator with depolarizing channels. Plot scripts consume these CSVs but do not alter solver logic.

#### Alternative encoding and key design decision
`rna_to_qubo_onehot.py` implements directed, per-position one-hot pairing variables with consistency penalties. `compare_qubo_encodings.py` verifies it against the default encoding and ViennaRNA where brute force is feasible. The one-hot scheme uses exactly twice the qubits and more penalty terms while yielding equivalent optima on tested instances, so the pair-indicator encoding remains the production path for solvers and scaling studies.

Main entry points: [`rna_to_qubo_full.py`](https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo_full.py) (Pair-indicator compiler), [`statistical_benchmark.py`](https://github.com/srijahn/moderna-challenge/blob/main/statistical_benchmark.py) (Statistical benchmark), [`cvar_vqe_rna_solver.py`](https://github.com/srijahn/moderna-challenge/blob/main/cvar_vqe_rna_solver.py) (CVaR-VQE), [`structure_metrics.py`](https://github.com/srijahn/moderna-challenge/blob/main/structure_metrics.py) (Structure metrics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Workloads & reference"]
  node_benchmark_sequences["Benchmark sequences<br/>sequence workload"]
  node_test_sequences["Validation sequences<br/>sequence workload<br/>[test_sequences.py]"]
  node_vienna{{"ViennaRNA reference<br/>thermodynamic evaluator<br/>[test_vienna.py]"}}
  node_metrics["Structure metrics<br/>evaluation layer"]
  node_official_example["Official 44-nt example<br/>classical benchmark"]
end

subgraph group_core["Production optimization"]
  node_pair_qubo["Pair-indicator compiler<br/>QUBO compiler"]
  node_qubo_support["QUBO utilities<br/>model support<br/>[rna_to_qubo.py]"]
  node_qaoa["Simulated QAOA<br/>PennyLane solver<br/>[qaoa_rna_solver.py]"]
  node_cvar_vqe["CVaR-VQE<br/>PennyLane solver"]
end

subgraph group_studies["Evaluation studies"]
  node_statistical_benchmark["Statistical benchmark<br/>benchmark workflow"]
  node_batch_accuracy["Batch accuracy<br/>batch workflow<br/>[batch_accuracy.py]"]
  node_final_results["Final results generator<br/>production workflow"]
  node_scaling["Scaling studies<br/>resource workflow"]
  node_cvar_scaling["CVaR scaling<br/>resource workflow"]
  node_noise["Noise simulation<br/>robustness workflow"]
  node_onehot["One-hot encoding<br/>alternative QUBO compiler"]
  node_encoding_comparison["Encoding comparison<br/>validation workflow"]
  node_final_summary["Final summary<br/>report workflow<br/>[final_summary.py]"]
end

subgraph group_outputs["Generated results"]
  node_results[("Results tables<br/>generated CSV output")]
end

node_benchmark_sequences -->|"compile"| node_pair_qubo
node_test_sequences -->|"validate"| node_pair_qubo
node_pair_qubo -->|"QUBO energy"| node_qubo_support
node_pair_qubo -->|"real QUBO"| node_qaoa
node_pair_qubo -->|"real QUBO"| node_cvar_vqe
node_qaoa -->|"decoded structures"| node_metrics
node_cvar_vqe -->|"decoded structures"| node_metrics
node_vienna -->|"MFE reference"| node_metrics
node_official_example -->|"classical folding"| node_vienna
node_statistical_benchmark -->|"uses"| node_benchmark_sequences
node_statistical_benchmark -->|"trials"| node_qaoa
node_statistical_benchmark -->|"trials"| node_cvar_vqe
node_statistical_benchmark -->|"evaluate"| node_metrics
node_statistical_benchmark -->|"trial and summary CSVs"| node_results
node_batch_accuracy -->|"CSV results"| node_results
node_final_results -->|"final tables"| node_results
node_scaling -->|"compiled instances"| node_pair_qubo
node_scaling -->|"resource tables"| node_results
node_cvar_scaling -->|"measure"| node_cvar_vqe
node_cvar_scaling -->|"scaling tables"| node_results
node_noise -.->|"noisy runtime variant"| node_cvar_vqe
node_noise -->|"robustness tables"| node_results
node_encoding_comparison -->|"verify"| node_onehot
node_encoding_comparison -->|"compare"| node_pair_qubo
node_encoding_comparison -->|"validate"| node_vienna
node_results -->|"consume"| node_final_summary

click node_benchmark_sequences "https://github.com/srijahn/moderna-challenge/blob/main/benchmark_sequences.py"
click node_test_sequences "https://github.com/srijahn/moderna-challenge/blob/main/test_sequences.py"
click node_vienna "https://github.com/srijahn/moderna-challenge/blob/main/test_vienna.py"
click node_metrics "https://github.com/srijahn/moderna-challenge/blob/main/structure_metrics.py"
click node_official_example "https://github.com/srijahn/moderna-challenge/blob/main/official_example_benchmark.py"
click node_pair_qubo "https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo_full.py"
click node_qubo_support "https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo.py"
click node_qaoa "https://github.com/srijahn/moderna-challenge/blob/main/qaoa_rna_solver.py"
click node_cvar_vqe "https://github.com/srijahn/moderna-challenge/blob/main/cvar_vqe_rna_solver.py"
click node_statistical_benchmark "https://github.com/srijahn/moderna-challenge/blob/main/statistical_benchmark.py"
click node_batch_accuracy "https://github.com/srijahn/moderna-challenge/blob/main/batch_accuracy.py"
click node_final_results "https://github.com/srijahn/moderna-challenge/blob/main/generate_final_results.py"
click node_scaling "https://github.com/srijahn/moderna-challenge/blob/main/scaling_analysis_real.py"
click node_cvar_scaling "https://github.com/srijahn/moderna-challenge/blob/main/cvar_vqe_scaling_analysis.py"
click node_noise "https://github.com/srijahn/moderna-challenge/blob/main/noise_simulation.py"
click node_onehot "https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo_onehot.py"
click node_encoding_comparison "https://github.com/srijahn/moderna-challenge/blob/main/compare_qubo_encodings.py"
click node_final_summary "https://github.com/srijahn/moderna-challenge/blob/main/final_summary.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_benchmark_sequences,node_test_sequences,node_vienna,node_metrics,node_official_example toneBlue
class node_pair_qubo,node_qubo_support,node_qaoa,node_cvar_vqe toneAmber
class node_statistical_benchmark,node_batch_accuracy,node_final_results,node_scaling,node_cvar_scaling,node_noise,node_onehot,node_encoding_comparison,node_final_summary toneMint
class node_results toneRose
```

## Components

### Workloads & reference

- [Benchmark sequences](https://github.com/srijahn/moderna-challenge/blob/main/benchmark_sequences.py): sequence workload · Eight curated 8–14 nt folding-positive sequences. · `benchmark_sequences.py`
- [Validation sequences](https://github.com/srijahn/moderna-challenge/blob/main/test_sequences.py): sequence workload · Small validation cases. · `test_sequences.py`
- [ViennaRNA reference](https://github.com/srijahn/moderna-challenge/blob/main/test_vienna.py): thermodynamic evaluator · Authoritative MFE folder and candidate evaluator. · `test_vienna.py`
- [Structure metrics](https://github.com/srijahn/moderna-challenge/blob/main/structure_metrics.py): evaluation layer · Computes comparable energies and structure-quality metrics. · `structure_metrics.py`
- [Official 44-nt example](https://github.com/srijahn/moderna-challenge/blob/main/official_example_benchmark.py): classical benchmark · Classical-only because its QUBO is infeasible for simulated solvers. · `official_example_benchmark.py`

### Production optimization

- [Pair-indicator compiler](https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo_full.py): QUBO compiler · Maps feasible base pairs to binary variables with RNA constraints. · `rna_to_qubo_full.py`
- [QUBO utilities](https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo.py): model support · Legacy/simple compilation and QUBO energy calculation. · `rna_to_qubo.py`
- [Simulated QAOA](https://github.com/srijahn/moderna-challenge/blob/main/qaoa_rna_solver.py): PennyLane solver · COBYLA-style optimized statevector solver; quality runs cap near 11 qubits. · `qaoa_rna_solver.py`
- [CVaR-VQE](https://github.com/srijahn/moderna-challenge/blob/main/cvar_vqe_rna_solver.py): PennyLane solver · Two-local ansatz with derivative-free optimization. · `cvar_vqe_rna_solver.py`

### Evaluation studies

- [Statistical benchmark](https://github.com/srijahn/moderna-challenge/blob/main/statistical_benchmark.py): benchmark workflow · Runs repeated CVaR-VQE and QAOA trials with mean/std summaries. · `statistical_benchmark.py`
- [Batch accuracy](https://github.com/srijahn/moderna-challenge/blob/main/batch_accuracy.py): batch workflow · `batch_accuracy.py`
- [Final results generator](https://github.com/srijahn/moderna-challenge/blob/main/generate_final_results.py): production workflow · `generate_final_results.py`
- [Scaling studies](https://github.com/srijahn/moderna-challenge/blob/main/scaling_analysis_real.py): resource workflow · Measures simulator resource behavior and quality below optimization cutoffs. · `scaling_analysis_real.py`
- [CVaR scaling](https://github.com/srijahn/moderna-challenge/blob/main/cvar_vqe_scaling_analysis.py): resource workflow · `cvar_vqe_scaling_analysis.py`
- [Noise simulation](https://github.com/srijahn/moderna-challenge/blob/main/noise_simulation.py): robustness workflow · Uses mixed-state simulation with depolarizing channels. · `noise_simulation.py`
- [One-hot encoding](https://github.com/srijahn/moderna-challenge/blob/main/rna_to_qubo_onehot.py): alternative QUBO compiler · Directed per-position encoding with twice the qubits. · `rna_to_qubo_onehot.py`
- [Encoding comparison](https://github.com/srijahn/moderna-challenge/blob/main/compare_qubo_encodings.py): validation workflow · Compares encodings and ViennaRNA where brute force is feasible. · `compare_qubo_encodings.py`
- [Final summary](https://github.com/srijahn/moderna-challenge/blob/main/final_summary.py): report workflow · Builds a human-readable aggregate report from result tables. · `final_summary.py`

### Generated results

- **Results tables**: generated CSV output · Sole generated-output boundary.

## Connections

- Benchmark sequences → Pair-indicator compiler: compile
- Validation sequences → Pair-indicator compiler: validate
- Pair-indicator compiler → QUBO utilities: QUBO energy
- Pair-indicator compiler → Simulated QAOA: real QUBO
- Pair-indicator compiler → CVaR-VQE: real QUBO
- Simulated QAOA → Structure metrics: decoded structures
- CVaR-VQE → Structure metrics: decoded structures
- ViennaRNA reference → Structure metrics: MFE reference
- Official 44-nt example → ViennaRNA reference: classical folding
- Statistical benchmark → Benchmark sequences: uses
- Statistical benchmark → Simulated QAOA: trials
- Statistical benchmark → CVaR-VQE: trials
- Statistical benchmark → Structure metrics: evaluate
- Statistical benchmark → Results tables: trial and summary CSVs
- Batch accuracy → Results tables: CSV results
- Final results generator → Results tables: final tables
- Scaling studies → Pair-indicator compiler: compiled instances
- Scaling studies → Results tables: resource tables
- CVaR scaling → CVaR-VQE: measure
- CVaR scaling → Results tables: scaling tables
- Noise simulation → CVaR-VQE: noisy runtime variant
- Noise simulation → Results tables: robustness tables
- Encoding comparison → One-hot encoding: verify
- Encoding comparison → Pair-indicator compiler: compare
- Encoding comparison → ViennaRNA reference: validate
- Results tables → Final summary: consume