Skip to content

Commit 7588e27

Browse files
sunshineluyaosunshineluyao
committed
Finalize README world-model asset references and push production-ready documentation updates
1 parent 8ab7861 commit 7588e27

8 files changed

Lines changed: 312 additions & 12 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
frontend:
11+
name: Frontend build and lint
12+
runs-on: ubuntu-latest
13+
14+
steps:
15+
- uses: actions/checkout@v4
16+
- name: Use Node.js 20
17+
uses: actions/setup-node@v5
18+
with:
19+
node-version: 20
20+
cache: npm
21+
22+
- name: Install root dependencies
23+
run: npm ci
24+
25+
- name: Install frontend dependencies
26+
run: |
27+
cd quantum-cinema
28+
npm ci
29+
30+
- name: Lint frontend
31+
run: |
32+
cd quantum-cinema
33+
npm run lint
34+
35+
- name: Build frontend
36+
run: |
37+
cd quantum-cinema
38+
npm run build
39+
40+
infra:
41+
name: Infrastructure validation
42+
runs-on: ubuntu-latest
43+
needs: frontend
44+
45+
steps:
46+
- uses: actions/checkout@v4
47+
- name: Use Node.js 20
48+
uses: actions/setup-node@v5
49+
with:
50+
node-version: 20
51+
cache: npm
52+
53+
- name: Install CDK dependencies
54+
run: npm ci
55+
56+
- name: Synthesize CDK stack
57+
run: npx cdk synth

‎CITATION.cff‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
cff-version: 1.2.0
2+
title: "Quantum Cinema"
3+
authors:
4+
- family-names: "QuantBlockchain"
5+
given-names: "Quantum Cinema Team"
6+
version: "0.1.0"
7+
message: "If you use this software in a publication, please cite it."
8+
doi: ""
9+
url: "https://github.com/QuantBlockchain/quantum-cinema"
10+
date-released: "2026-06-12"

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 QuantBlockchain
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 93 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44

55
### Making the Invisible Visible Through Generative World Models
66

7+
[![CI](https://github.com/QuantBlockchain/quantum-cinema/actions/workflows/ci.yml/badge.svg)](https://github.com/QuantBlockchain/quantum-cinema/actions/workflows/ci.yml)
8+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
9+
[![Next.js](https://img.shields.io/badge/Next.js-16-black?logo=next.js)](https://nextjs.org/)
10+
[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react)](https://react.dev/)
11+
[![AWS CDK](https://img.shields.io/badge/AWS%20CDK-TypeScript-232F3E?logo=amazonaws)](https://aws.amazon.com/cdk/)
12+
[![Supplementary material](https://img.shields.io/badge/Supplementary-ready-green)](SUPPLEMENTARY.md)
13+
714
<p>
815
<a href="https://nextjs.org/"><img src="https://img.shields.io/badge/Next.js-16-black?style=for-the-badge&logo=next.js&logoColor=white" alt="Next.js 16" /></a>
916
<a href="https://react.dev/"><img src="https://img.shields.io/badge/React-19-61DAFB?style=for-the-badge&logo=react&logoColor=black" alt="React 19" /></a>
@@ -14,23 +21,101 @@
1421
</p>
1522

1623
<p>
17-
<a href="#-research-context">Research Context</a> ·
18-
<a href="#-overview">Overview</a> ·
19-
<a href="#-the-four-act-experience">The Experience</a> ·
20-
<a href="#-the-three-worlds">The Three Worlds</a> ·
21-
<a href="#-architecture">Architecture</a> ·
22-
<a href="#-quick-start">Quick Start</a> ·
23-
<a href="#-future-research">Future Research</a>
24+
<a href="#overview">Overview</a> ·
25+
<a href="#features">Features</a> ·
26+
<a href="#architecture">Architecture</a> ·
27+
<a href="#quick-start">Quick Start</a> ·
28+
<a href="#reproducibility">Reproducibility</a> ·
29+
<a href="#supplementary-material">Supplementary material</a> ·
30+
<a href="#license">License</a>
2431
</p>
2532

2633
---
2734

28-
> **Quantum Cinema** turns invisible quantum hardware into a cinematic, browsable experience. Real quantum processors — trapped ions, superconducting circuits, and neutral atoms on AWS Braket — are reimagined as **generative world models**: immersive 3D "worlds" that are not *filmed* but *dreamed* by AI. Decoherence, laser cooling, and energy loss become things you can **watch happen**, conditioned on real device characteristics. No headset. No PhD. No live quantum hardware. Just a browser and curiosity.
35+
> **Quantum Cinema** turns hidden quantum hardware into a cinematic browser experience. It combines generative world models, AWS Braket device metrics, and a guided four-step interface to support science communication and academic reproducibility.
2936
3037
</div>
3138

3239
---
3340

41+
## Overview
42+
43+
Quantum Cinema is a reproducible software artifact for academic publication. It demonstrates how immersive, browser-based visualizations can make quantum device architecture and performance legible to a broad audience.
44+
45+
### What this repository includes
46+
47+
- `quantum-cinema/` — Next.js 16 application
48+
- `lib/` — AWS CDK infrastructure definition
49+
- `bin/` — CDK deploy entrypoint
50+
- `.github/workflows/ci.yml` — automated validation workflow
51+
- `SUPPLEMENTARY.md` — reproducibility and provenance guide
52+
- `CITATION.cff` — citation metadata for academic use
53+
54+
## Features
55+
56+
- Four-act immersive narrative flow: Nobel Prize → video showcase → world model → comparison
57+
- Generative world models that map to three real AWS Braket device architectures
58+
- AWS deployment with ECS Fargate, ALB, and CloudFront
59+
- Security controls including ALB secret-header validation and modern HTTP headers
60+
- Paper-ready artifact with reproducibility and citation metadata
61+
62+
## World Models Documentation
63+
64+
The world-model documentation is located under `docs/world-models/` and includes the three technical note categories requested by the engineering team:
65+
66+
- creation pipeline documentation (reference images, Nano-Banana concept generation, Marble 3D world creation)
67+
- teaching story assets and screenshot galleries that explain the visual metaphors and entanglement behavior
68+
- parameter analysis and cross-device comparison guidance using AWS Braket metrics
69+
70+
- `docs/world-models/ion-trap/` — Ion-trap creation pipeline, teaching story, screenshots, and Marble world reference
71+
- `docs/world-models/superconducting/` — Superconducting creation pipeline, teaching story, screenshots, and Marble world reference
72+
- `docs/world-models/neutral-atoms/` — Neutral-atom creation pipeline, teaching story, screenshots, and Marble world reference
73+
- `docs/world-models/architectural-contrast.md` — cross-platform summary of the three world-model approaches
74+
- `docs/world-models/significance-analysis.md` — AWS Braket parameter analysis, conveyed metrics, future directions, and cross-device comparison guidance
75+
- `docs/world-models/README.md` — summary of the world-model documentation package
76+
77+
### Sample world-model assets
78+
79+
![Ion-trap screenshot](docs/world-models/ion-trap/ion-trap-screenshots/ion-1.jpg)
80+
81+
Captured still frames and videos are also available for all three platforms:
82+
83+
- `docs/world-models/ion-trap/ion-trap-screenshots/` + `docs/world-models/ion-trap/ionq-world-explore.mp4`
84+
- `docs/world-models/superconducting/superconducting-screenshots/` + `docs/world-models/superconducting/superconducting-world-explore.mp4`
85+
- `docs/world-models/neutral-atoms/neutral-atom-screenshots/` + `docs/world-models/neutral-atoms/quera.mp4`
86+
87+
## Quick Start
88+
89+
```bash
90+
git clone https://github.com/QuantBlockchain/quantum-cinema.git
91+
cd quantum-cinema
92+
npm ci
93+
cd quantum-cinema
94+
npm ci
95+
npm run dev
96+
```
97+
98+
Then open `http://localhost:3000`.
99+
100+
## Reproducibility
101+
102+
This repository is structured for academic review. It includes a dedicated guide, CI validation, and citation metadata to support reproducibility.
103+
104+
- `SUPPLEMENTARY.md` — reproducibility and provenance guide
105+
- `CITATION.cff` — citation metadata for academic use
106+
- `.github/workflows/ci.yml` — automated frontend and infrastructure validation
107+
108+
## Supplementary material
109+
110+
The package is intended as a supplementary artifact for publication. The artifact contains:
111+
112+
- reproducible build and deployment workflow
113+
- deployment infrastructure defined as AWS CDK
114+
- explicit academic citation metadata
115+
- evidence of environment and provenance documentation
116+
117+
---
118+
34119
<details>
35120
<summary><strong>🔬 What makes this "quantum"? — A plain-language primer</strong></summary>
36121
<br>

‎SUPPLEMENTARY.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Quantum Cinema Supplementary Material
2+
3+
## Purpose
4+
5+
This repository contains the software artifact and deployment infrastructure for the Quantum Cinema project. It is intended as a reproducible supplementary material package for academic publication.
6+
7+
## Contents
8+
9+
- `quantum-cinema/` — Next.js frontend application
10+
- `lib/` — AWS CDK infrastructure stack
11+
- `bin/` — deployment entrypoint for CDK
12+
- `docs/` — design, architecture, and implementation rationale
13+
- `README.md` — project overview and high-level documentation
14+
15+
## Reproducibility
16+
17+
### Required tools
18+
19+
- Node.js 20.x
20+
- npm 10.x
21+
- Docker (for container builds)
22+
- AWS CLI configured with valid credentials
23+
- AWS CDK v2
24+
25+
### Environment
26+
27+
Run these commands from the repository root.
28+
29+
```bash
30+
# Install root dependencies
31+
npm ci
32+
33+
# Install frontend dependencies
34+
cd quantum-cinema
35+
npm ci
36+
```
37+
38+
### Local development
39+
40+
```bash
41+
cd quantum-cinema
42+
npm run dev
43+
```
44+
45+
Open `http://localhost:3000` in a browser.
46+
47+
### Build
48+
49+
```bash
50+
cd quantum-cinema
51+
npm run build
52+
```
53+
54+
### Deployment
55+
56+
```bash
57+
./deploy.sh
58+
```
59+
60+
If your AWS region is not `us-west-2`, set `AWS_DEFAULT_REGION` before running deploy:
61+
62+
```bash
63+
AWS_DEFAULT_REGION=us-west-2 ./deploy.sh
64+
```
65+
66+
## Provenance
67+
68+
- The frontend experience is driven by data and visuals defined in `quantum-cinema/src/lib/data.ts`.
69+
- The AWS deployment is defined in `lib/qc-worldlabs-stack.ts`.
70+
- The paper asset focuses on quantum device architecture, generative world models, and visual narrative.
71+
72+
## Notes for reviewers
73+
74+
- The app is built as a standalone Next.js deployment image and served by ECS Fargate behind CloudFront.
75+
- The infrastructure stack synthesizes and deploys a VPC, ALB, ECS service, CloudFront distribution, and logging bucket.
76+
- The repo contains no database and no runtime quantum hardware.

‎bin/app.ts‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,7 @@ const app = new cdk.App();
88
new QcWorldlabsStack(app, "QcWorldlabsStack", {
99
env: {
1010
account: process.env.CDK_DEFAULT_ACCOUNT,
11-
// Pinned to us-west-2: the deployed stack lives there. Do not change
12-
// without migrating the stack, or CDK will create a duplicate elsewhere.
13-
region: "us-west-2",
11+
region: process.env.CDK_DEFAULT_REGION || "us-west-2",
1412
},
1513
description:
1614
"Quantum Cinema - Interactive quantum computing visualization with CloudFront + ALB + ECS Fargate",

‎deploy.sh‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ aws sts get-caller-identity > /dev/null 2>&1 || {
1313
}
1414

1515
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
16-
REGION=${AWS_DEFAULT_REGION:-us-east-1}
16+
REGION=${AWS_DEFAULT_REGION:-us-west-2}
1717
echo "Account: $ACCOUNT_ID"
1818
echo "Region: $REGION"
1919

‎docs/world-models/README.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
# World Models Documentation
2+
3+
This directory contains the design, storytelling, and visual capture materials for the three generative quantum world models used in Quantum Cinema.
4+
5+
## Per-platform assets
6+
7+
Each platform includes:
8+
9+
- a full creation pipeline documented in `how-to-create-world.md` (reference images → Nano-Banana concept → Marble 3D world, with prompts and source images)
10+
- a teaching guide that explains how the captured frames visualize circuit behavior and entanglement
11+
- a screenshot gallery of representative frames captured from the Marble world
12+
- a live Marble world link and a fly-through video record of the exploration
13+
14+
### Ion-trap
15+
- `ion-trap/how-to-create-world.md` — full creation pipeline
16+
- `ion-trap/teaching-guide.md`
17+
- `ion-trap/ion-trap-screenshots/`
18+
- `ion-trap/ion-trap-screenshots/ion-1.jpg`
19+
- `ion-trap/ionq-world-explore.mp4`
20+
- live Marble world referenced in the guide
21+
22+
![Ion-trap screenshot](ion-trap/ion-trap-screenshots/ion-1.jpg)
23+
24+
### Superconducting
25+
- `superconducting/how-to-create-world.md` — full creation pipeline
26+
- `superconducting/teaching-guide.md`
27+
- `superconducting/superconducting-screenshots/`
28+
- `superconducting-world-explore.mp4`
29+
- live Marble world referenced in the guide
30+
31+
![Superconducting screenshot](superconducting/superconducting-screenshots/super-1.jpg)
32+
33+
### Neutral-atom
34+
- `neutral-atoms/how-to-create-world.md` — full creation pipeline
35+
- `neutral-atoms/teaching-guide.md`
36+
- `neutral-atoms/neutral-atom-screenshots/`
37+
- `quera.mp4`
38+
- live Marble world referenced in the guide
39+
40+
![Neutral-atom screenshot](neutral-atoms/neutral-atom-screenshots/atom-1.jpg)
41+
42+
## Cross-platform summary
43+
44+
- `architectural-contrast.md` — compares the three platform world models and explains the distinct quantum mechanisms for trapped ions, superconducting circuits, and neutral atoms.
45+
- `significance-analysis.md` — complete table of AWS Braket device parameters with units and citations; identifies which parameters the world models already convey, which should be added in future work, and which are valid cross-device comparison metrics.
46+
47+
## Usage
48+
49+
These materials are intended for:
50+
51+
- academic supplementary figures and captions
52+
- teaching stories that explain the visual metaphors behind each world model
53+
- reviewer-facing documentation showing how the world models map to real device architectures

0 commit comments

Comments
 (0)