QDeck Quantum Simulator

⚛️ A modern quantum information science kit simulator in pure TypeScript, inspired by the deprecated @qiskit/sim package.

Features

• Circuit Simulation: Build and simulate quantum circuits with various gates.
• State Vector Representation: Track the quantum state vector throughout the simulation.
• Extensible Gate Set: Easily add new quantum gates.
• Circuit Visualization: Text-based rendering of quantum circuits.
• Save/Load Functionality: Serialize and deserialize circuits for later use.

Installation

Requires Node.js (LTS or latest stable version).

npm install qdeck
# or
yarn add qdeck

Usage

YouYou can find more complete examples in the example.ts file.

import { Circuit, Gate } from 'qdeck';

// Create a 2-qubit circuit
const circuit = new Circuit(2);

// Add gates
circuit.add(Gate.H, 0); // Hadamard on qubit 0
circuit.add(Gate.CX, 0, 1); // CNOT with control 0, target 1

console.log('Circuit before run:');
circuit.print();

// Run the circuit with an initial state (e.g., |00>)
circuit.run();

console.log('\nDone, internal state:');
console.log(circuit.stateToString());

// Demonstrate save and load functionality
const savedCircuit = circuit.save();
console.log('\nSaved Circuit IR:', JSON.stringify(savedCircuit, null, 2));

const loadedCircuit = new Circuit(2); // Create a new circuit instance
loadedCircuit.load(savedCircuit);

console.log('\nLoaded Circuit:');
loadedCircuit.print();

console.log('Running loaded circuit with same input ...');
loadedCircuit.run();

console.log('\nLoaded Circuit State (should be same as original): ');
console.log(loadedCircuit.stateToString());

API

Circuit(nQubits)

Creates a new quantum circuit with nQubits qubits, initialized to the $|0...0\rangle$ state.

• nQubits (number): The number of qubits in the circuit.

circuit.add(gate, ...qubits)

Adds a quantum gate to the circuit.

• gate (QuantumGate): An instance of a quantum gate (e.g., Gate.H, Gate.CX).
• ...qubits (number[]): The 0-indexed qubit(s) the gate acts upon.

circuit.run([input])

Simulates the circuit. If input is provided, the circuit starts from that initial state; otherwise, it starts from the current internal state (defaulting to $|0...0\rangle$ if no previous run or load was called).

• input (boolean[], optional): An array of booleans representing the initial state of each qubit (false for $|0\rangle, true for $|1\rangle).

circuit.state

(Read-only) The internal state vector of the simulation as a mathjs Matrix of Complex numbers.

circuit.stateToString()

Returns a human-readable string representation of the current quantum state.

circuit.print()

Prints a text-based visual representation of the circuit to the console.

circuit.save()

Serializes the current circuit's structure (number of qubits and operations) into a JSON-serializable object.

circuit.load(circuitIr)

Loads a circuit structure from a serialized object, replacing the current circuit's operations.

• circuitIr (object): The serialized circuit representation obtained from save().

Available Gates

The Gate export provides the following predefined quantum gates:

• Gate.H: Hadamard gate (1-qubit)
• Gate.X: Pauli-X (NOT) gate (1-qubit)
• Gate.Y: Pauli-Y gate (1-qubit)
• Gate.Z: Pauli-Z gate (1-qubit)
• Gate.S: Phase gate (1-qubit)
• Gate.T: Pi/8 gate (1-qubit)
• Gate.CX: Controlled-NOT gate (2-qubits, first is control, second is target)
• Gate.CZ: Controlled-Z gate (2-qubits)
• Gate.SWAP: SWAP gate (2-qubits)
• Gate.I: Identity gate (1-qubit)

Development

To run tests:

npm test

To build the project:

npm run build

To run the example:

npm start

License

MIT License