Qamposer

Qamposer is a modular, open-source quantum composer that can be embedded into your applications and runs anywhere.

Installation

npm install @qamposer/react

For the full version with visualization (Q-sphere, histograms), also install Plotly:

npm install plotly.js-basic-dist-min react-plotly.js

Examples

Educational Platform

Suitable for quantum education in schools and companies.

An interactive quantum computing tutorial with step-by-step guidance.

Gaming Application

Quantum Circuit as a Controller.

Quantum mechanics and simulation results can be directly leveraged as game logic.

Quick Start

Basic Usage (QamposerMicro)

import { QamposerMicro } from '@qamposer/react';

function App() {
  return <QamposerMicro />;
}

Note: By default, QamposerMicro runs in editor-only mode (no simulation). To enable simulation, see With Backend below.

Full Version with Visualization (Qamposer)

The full version includes visualization components (histograms, Q-sphere) that require simulation results, so a simulation adapter is needed. The zero-dependency localAdapter runs ideal simulation entirely in the browser — no server required:

import { Qamposer } from '@qamposer/react/visualization';
import { localAdapter } from '@qamposer/react';

function App() {
  return (
    <Qamposer
      adapter={localAdapter()}
      defaultTheme="dark"
      showThemeToggle
    />
  );
}

Qamposer vs QamposerMicro

This library provides two preset components to fit different use cases:

Feature	Qamposer	QamposerMicro
Circuit Editor	Yes	Yes
Gate Library	Yes	Yes
OpenQASM Code Editor	Yes	No
Results Histogram	Yes	No
Q-Sphere (3D)	Yes	No
Plotly.js Required	Yes	No
Bundle Size	Larger	Minimal
Best For	Full IDE experience	Embedded widgets, tutorials

When to use Qamposer

• Building a full-featured quantum circuit IDE
• Need visualization of simulation results (histograms, Q-sphere)
• Educational platforms where visualization is important

When to use QamposerMicro

• Embedding in existing applications
• Tutorials and interactive documentation
• Games and lightweight applications
• When bundle size matters (no Plotly.js dependency)

Backend Requirements

The React components work standalone for circuit editing. To run quantum simulations, you need the qamposer-backend server.

Editor-Only Mode

By default, components run in editor-only mode without requiring a backend:

import { QamposerMicro } from '@qamposer/react';

// No backend required - editor-only mode (default)
<QamposerMicro />;

Local Simulation (no backend)

localAdapter runs ideal (noiseless) state-vector simulation entirely in the browser, with counts, seeded sampling, and Q-sphere data matching the backend's output format:

import { QamposerMicro, localAdapter } from '@qamposer/react';

// No backend required — instant ideal simulation
<QamposerMicro adapter={localAdapter()} />;

Options:

localAdapter({
  name: 'Browser Simulator', // display name
  maxQubits: 12, // reject wider circuits
  qsphere: true, // emit Q-sphere points for ≤5 qubits
});

It can also be combined with a backend adapter: the backend handles noisy fake devices via "Set up and run", while every circuit edit is simulated instantly in the browser:

import { Qamposer } from '@qamposer/react/visualization';
import { qiskitAdapter, localAdapter } from '@qamposer/react';

<Qamposer
  adapter={qiskitAdapter(BACKEND_URL)} // noisy fake devices, via "Set up and run"
  realtimeAdapter={localAdapter()} // instant ideal results on every edit
/>;

With Backend (Simulation)

Noisy fake-device simulation (and any future real-hardware path) requires the backend. Start it and pass the qiskitAdapter:

Assuming localhost is used here, but please specify the actual deployment destination for the backend.

# Clone and setup qamposer-backend
cd qamposer-backend
poetry install
poetry run uvicorn backend.main:app --host 0.0.0.0 --port 8080 --reload

import { QamposerMicro, qiskitAdapter } from '@qamposer/react';

<QamposerMicro
  adapter={qiskitAdapter('http://localhost:8080')}
  onSimulationComplete={(event) => {
    console.log('Result:', event.result);
    console.log('QASM:', event.qasm);
  }}
/>;

API Reference

Qamposer Props

interface QamposerProps {
  // Circuit State
  circuit?: Circuit; // Controlled mode
  defaultCircuit?: Circuit; // Initial circuit
  onCircuitChange?: (circuit: Circuit) => void;

  // Simulation
  adapter?: SimulationAdapter; // Backend adapter (default: noopAdapter)
  onSimulationComplete?: (event: SimulationCompleteEvent) => void;

  // Configuration
  config?: QamposerConfig;

  // UI Customization
  className?: string;
  showHeader?: boolean; // Default: true
  title?: string; // Default: 'Qamposer'
  defaultTheme?: 'light' | 'dark'; // Default: 'dark'
  showThemeToggle?: boolean; // Default: true

  // Layout (Qamposer only)
  codeEditorWidth?: string; // Default: '280px'
  topGridTemplate?: string; // Default: '1fr 3fr'
  bottomGridTemplate?: string; // Default: '1fr 1fr'
}

QamposerConfig

interface QamposerConfig {
  maxQubits?: number; // Default: 5
  maxGates?: number; // Default: 500
  maxShots?: number; // Default: 10000
}

OpenQASM Utilities

import { circuitToQasm, qasmToCircuit } from '@qamposer/react';

// Convert Circuit to OpenQASM
const qasm = circuitToQasm(circuit);

// Parse OpenQASM to Circuit
const result = qasmToCircuit(qasmCode);
if (result.success) {
  console.log(result.circuit);
} else {
  console.error(result.errors);
}

Supported Gates

Gate	Description	Parameters
H	Hadamard	-
X	Pauli-X (NOT)	-
Y	Pauli-Y	-
Z	Pauli-Z	-
RX	Rotation around X-axis	angle (radians)
RY	Rotation around Y-axis	angle (radians)
RZ	Rotation around Z-axis	angle (radians)
CNOT	Controlled-NOT	control, target qubits

Theming

The library uses CSS variables for theming. You can customize colors by overriding these variables:

:root {
  --qamposer-bg-primary: #1a1a2e;
  --qamposer-bg-secondary: #16213e;
  --qamposer-text-primary: #ffffff;
  --qamposer-border: #2d3748;
  --qamposer-accent: #4fd1c5;
}

Or use the theme hook:

import { useTheme } from '@qamposer/react';

function ThemeToggle() {
  const { theme, toggleTheme } = useTheme();
  return <button onClick={toggleTheme}>{theme}</button>;
}

Peer Dependencies

{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0"
}

For Qamposer (full version) with visualization:

{
  "plotly.js-basic-dist-min": "^2.35.0 || ^3.0.0",
  "react-plotly.js": "^2.6.0"
}

Support & Stability

• This library is under active development.
• Please report issues via GitHub Issues.

License

Licensed under the Apache 2.0.