Skip to content

Commit 9c3a12b

Browse files
ashutoshm1771ashutoshm1771
committed
update README with badges and project structure, fix footer and Python version
- Rewrite README with dynamic shields.io badges, tech stack table, encoding grid, project structure tree, and related links - Fix Python version from 3.10+ to 3.9+ in FooterCTA to match pyproject.toml - Update footer with QEA Contributors credit and web/project repo links
1 parent bdaaf10 commit 9c3a12b

3 files changed

Lines changed: 217 additions & 17 deletions

File tree

‎README.md‎

Lines changed: 196 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,219 @@
1-
# Quantum Encoding Atlas — Website
1+
<div align="center">
22

3-
Interactive showcase website for the [Quantum Encoding Atlas](https://github.com/encoding-atlas/quantum-encoding-atlas) Python library.
3+
<img src="public/logo.png" alt="Quantum Encoding Atlas" width="100" />
44

5-
**Live:** [q-encoding-atlas.web.app](https://q-encoding-atlas.web.app)
5+
# Quantum Encoding Atlas — Web
6+
7+
**Interactive explorer for quantum data encodings in machine learning**
8+
9+
<!-- Version badges auto-update from package.json via shields.io dynamic JSON endpoint -->
10+
[![Next.js](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fencoding-atlas%2Fquantum-encoding-atlas-web%2Fmain%2Fpackage.json&query=%24.dependencies.next&logo=next.js&logoColor=white&label=Next.js&color=black)](https://nextjs.org)
11+
[![React](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fencoding-atlas%2Fquantum-encoding-atlas-web%2Fmain%2Fpackage.json&query=%24.dependencies.react&logo=react&label=React&color=61dafb)](https://react.dev)
12+
[![TypeScript](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fencoding-atlas%2Fquantum-encoding-atlas-web%2Fmain%2Fpackage.json&query=%24.devDependencies.typescript&logo=typescript&logoColor=white&label=TypeScript&color=3178c6)](https://www.typescriptlang.org)
13+
[![Tailwind CSS](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fencoding-atlas%2Fquantum-encoding-atlas-web%2Fmain%2Fpackage.json&query=%24.devDependencies.tailwindcss&logo=tailwindcss&logoColor=white&label=Tailwind%20CSS&color=06b6d4)](https://tailwindcss.com)
14+
[![pnpm](https://img.shields.io/badge/pnpm-10-f69220?logo=pnpm&logoColor=white)](https://pnpm.io)
15+
16+
[![Deploy](https://img.shields.io/github/actions/workflow/status/encoding-atlas/quantum-encoding-atlas-web/deploy.yml?branch=main&logo=githubactions&logoColor=white&label=Build%20%26%20Deploy)](https://github.com/encoding-atlas/quantum-encoding-atlas-web/actions/workflows/deploy.yml)
17+
[![Website](https://img.shields.io/website?url=https%3A%2F%2Fq-encoding-atlas.web.app&logo=firebase&logoColor=white&label=Website)](https://q-encoding-atlas.web.app)
18+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
19+
20+
---
21+
22+
[**Live Website**](https://q-encoding-atlas.web.app) · [**Library Repository**](https://github.com/encoding-atlas/quantum-encoding-atlas) · [**Documentation**](https://encoding-atlas.github.io/quantum-encoding-atlas/) · [**PyPI**](https://pypi.org/project/encoding-atlas/)
23+
24+
</div>
25+
26+
<br />
27+
28+
## Overview
29+
30+
The **Quantum Encoding Atlas** web application is the interactive companion to the [`encoding-atlas`](https://pypi.org/project/encoding-atlas/) Python library. It provides an intuitive, browser-based interface for exploring, comparing, and selecting quantum data encodings for machine learning workflows — with publication-quality math rendering, interactive circuit diagrams, and an evidence-based recommendation engine.
31+
32+
### Pages
33+
34+
| Route | Description |
35+
|:------|:------------|
36+
| **`/`** | Landing page with hero, features overview, and encoding carousel |
37+
| **`/encodings`** | Browsable, filterable catalog of all 16 quantum encodings |
38+
| **`/encodings/[slug]`** | Detail page with circuit diagrams, properties, and MDX docs |
39+
| **`/compare`** | Side-by-side radar chart comparison of encoding properties |
40+
| **`/guide`** | 7-step interactive wizard for evidence-based encoding selection |
41+
42+
## Features
43+
44+
- **16 Encoding Methods** across 7 categories with detailed MDX documentation
45+
- **Interactive Circuit Diagrams** — Custom SVG renderer for quantum gate visualization (H, RX, RY, RZ, CNOT, CZ, and more)
46+
- **Radar Chart Comparisons** — [visx](https://airbnb.io/visx)-powered D3 charts for multi-dimensional property analysis
47+
- **Decision Guide Wizard** — 7-step questionnaire with a deterministic recommendation engine and shareable URL results
48+
- **KaTeX Math Rendering** — Publication-quality mathematical notation throughout
49+
- **Dark Mode** — Full light/dark theme support with system preference detection
50+
- **URL-Shareable State** — Comparison selections and guide results encoded in URL params for easy sharing
51+
- **Fully Static** — Pre-rendered for instant loading, SEO-friendly, and zero server cost
52+
53+
## Encodings
54+
55+
<table>
56+
<tr>
57+
<td width="25%">
58+
59+
**Angle-based**
60+
- Angle Encoding
61+
- Higher-Order Angle
62+
63+
</td>
64+
<td width="25%">
65+
66+
**Amplitude-based**
67+
- Amplitude Encoding
68+
69+
</td>
70+
<td width="25%">
71+
72+
**Basis**
73+
- Basis Encoding
74+
75+
</td>
76+
<td width="25%">
77+
78+
**Entangling**
79+
- IQP Encoding
80+
- ZZ Feature Map
81+
- Pauli Feature Map
82+
83+
</td>
84+
</tr>
85+
<tr>
86+
<td>
87+
88+
**Variational**
89+
- Data Reuploading
90+
- Hardware-Efficient
91+
- QAOA-Inspired
92+
- Hamiltonian
93+
94+
</td>
95+
<td>
96+
97+
**Physics-Inspired**
98+
- Trainable Encoding
99+
100+
</td>
101+
<td colspan="2">
102+
103+
**Symmetry & Equivariant**
104+
- Symmetry-Inspired
105+
- SO(2) Equivariant
106+
- Cyclic Equivariant
107+
- Swap Equivariant
108+
109+
</td>
110+
</tr>
111+
</table>
6112

7113
## Tech Stack
8114

9-
- **Framework:** Next.js (static export) with TypeScript
10-
- **Styling:** Tailwind CSS v4
11-
- **Package Manager:** pnpm
12-
- **Hosting:** Firebase Hosting
13-
- **CI/CD:** GitHub Actions
115+
| Layer | Technology |
116+
|:------|:-----------|
117+
| **Framework** | [Next.js](https://nextjs.org) 16 — App Router, static export |
118+
| **UI Library** | [React](https://react.dev) 19 |
119+
| **Language** | [TypeScript](https://www.typescriptlang.org) 5 — strict mode |
120+
| **Styling** | [Tailwind CSS](https://tailwindcss.com) v4 — CSS-first config, OKLCH colors |
121+
| **Components** | [shadcn/ui](https://ui.shadcn.com) + [Radix UI](https://www.radix-ui.com) — 19 primitives |
122+
| **Visualizations** | [visx](https://airbnb.io/visx) (D3 bindings) + custom SVG circuit renderer |
123+
| **Math** | [KaTeX](https://katex.org) via remark-math + rehype-katex |
124+
| **Content** | [MDX](https://mdxjs.com) with [@next/mdx](https://nextjs.org/docs/app/building-your-application/configuring/mdx) |
125+
| **Syntax Highlighting** | [Shiki](https://shiki.style) |
126+
| **Animations** | [Motion](https://motion.dev) |
127+
| **Icons** | [Lucide React](https://lucide.dev) |
128+
| **Dark Mode** | [next-themes](https://github.com/pacocoursey/next-themes) |
129+
| **Hosting** | [Firebase Hosting](https://firebase.google.com/products/hosting) |
130+
| **CI/CD** | [GitHub Actions](https://github.com/features/actions) — lint, build, deploy |
131+
| **Package Manager** | [pnpm](https://pnpm.io) 10 |
132+
133+
## Getting Started
14134

15-
## Development
135+
### Prerequisites
136+
137+
- [Node.js](https://nodejs.org) >= 22
138+
- [pnpm](https://pnpm.io) >= 10
139+
140+
### Development
16141

17142
```bash
143+
# Install dependencies
18144
pnpm install
145+
146+
# Start development server (http://localhost:3000)
19147
pnpm dev
20148
```
21149

22-
## Build
150+
### Build
23151

24152
```bash
153+
# Create optimized static export → out/
25154
pnpm build
26155
```
27156

28-
Static output is written to `out/`.
157+
### Lint
158+
159+
```bash
160+
pnpm lint
161+
```
162+
163+
## Deployment
164+
165+
Deployment is fully automated via **GitHub Actions** on every push to `main`:
29166

30-
## Deploy
167+
```
168+
push to main → install → lint → build → deploy to Firebase Hosting
169+
```
31170

32-
Deployment is automated via GitHub Actions on push to `main`. For manual deployment:
171+
For manual deployment:
33172

34173
```bash
35174
firebase deploy
36175
```
176+
177+
## Project Structure
178+
179+
```
180+
src/
181+
├── app/ # Next.js App Router
182+
│ ├── page.tsx # Landing page
183+
│ ├── compare/ # Encoding comparison tool
184+
│ ├── encodings/ # Catalog + [slug] detail pages
185+
│ └── guide/ # Decision guide wizard
186+
├── components/
187+
│ ├── encodings/ # Catalog cards, detail sections
188+
│ ├── guide/ # Wizard steps, results, option cards
189+
│ ├── landing/ # Hero, features, carousel, stats
190+
│ ├── layout/ # Header, footer, navigation
191+
│ ├── math/ # InlineMath, DisplayMath (KaTeX)
192+
│ ├── ui/ # 19 shadcn/ui primitives
193+
│ └── visualization/ # Circuit diagrams, radar charts
194+
├── content/encodings/ # 16 MDX long-form documentation files
195+
├── data/
196+
│ ├── encodings/ # 16 TypeScript encoding definitions
197+
│ ├── categories.ts # 7 encoding categories
198+
│ └── guide-rules.ts # Recommendation rules & constraints
199+
├── hooks/ # useGuideWizard, useCompareEncodings, ...
200+
└── lib/
201+
├── recommender.ts # Deterministic recommendation engine
202+
├── mdx.ts # Dynamic MDX import map
203+
├── animation-variants.ts
204+
└── utils.ts
205+
```
206+
207+
## Related
208+
209+
| | Link |
210+
|:--|:-----|
211+
| **Python Library** | [`pip install encoding-atlas`](https://pypi.org/project/encoding-atlas/) |
212+
| **Source Code** | [github.com/encoding-atlas/quantum-encoding-atlas](https://github.com/encoding-atlas/quantum-encoding-atlas) |
213+
| **Documentation** | [encoding-atlas.github.io/quantum-encoding-atlas](https://encoding-atlas.github.io/quantum-encoding-atlas/) |
214+
| **Tutorials** | [encoding-atlas.github.io/.../tutorials](https://encoding-atlas.github.io/quantum-encoding-atlas/tutorials/) |
215+
| **API Reference** | [encoding-atlas.github.io/.../api](https://encoding-atlas.github.io/quantum-encoding-atlas/api/) |
216+
217+
## License
218+
219+
[MIT](../quantum-encoding-atlas/LICENSE) © 2026 Quantum Encoding Atlas Contributors

‎src/components/landing/FooterCTA.tsx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,7 @@ export function FooterCTA() {
9696
>
9797
<span>MIT Licensed</span>
9898
<span aria-hidden="true">&middot;</span>
99-
<span>Python 3.10+</span>
99+
<span>Python 3.9+</span>
100100
<span aria-hidden="true">&middot;</span>
101101
<span>Framework Agnostic</span>
102102
</motion.div>

‎src/components/layout/Footer.tsx‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -119,14 +119,31 @@ export function Footer() {
119119
&copy; {new Date().getFullYear()} Quantum Encoding Atlas. MIT
120120
Licensed. Built by{" "}
121121
<a
122-
href="https://github.com/encoding-atlas"
122+
href="https://github.com/encoding-atlas/quantum-encoding-atlas"
123123
target="_blank"
124124
rel="noopener noreferrer"
125125
className="text-primary hover:underline"
126126
>
127-
Ashutosh Mishra
127+
QEA Contributors
128+
</a>
129+
.{" "}
130+
<a
131+
href="https://github.com/encoding-atlas/quantum-encoding-atlas-web"
132+
target="_blank"
133+
rel="noopener noreferrer"
134+
className="text-primary hover:underline"
135+
>
136+
Web
137+
</a>
138+
{" | "}
139+
<a
140+
href="https://github.com/encoding-atlas/quantum-encoding-atlas"
141+
target="_blank"
142+
rel="noopener noreferrer"
143+
className="text-primary hover:underline"
144+
>
145+
Project
128146
</a>
129-
.
130147
</p>
131148
</div>
132149
</div>

0 commit comments

Comments
 (0)