ProtectedisFlag indicating whether dense or sparse representation is currently used (backward compatibility)
Creates a QubitState with the specified number of qubits.
The constructor automatically selects the internal representation (dense or sparse) based on the system size and the provided state vector's sparsity. For systems with 8 or more qubits, sparse representation is enabled by default to conserve memory.
Number of qubits in the system. Must be a positive integer.
OptionalstateVector: Complex[]Optional initial state vector of complex amplitudes. If not provided, defaults to the |0...0⟩ state. The length must be 2^numQubits.
OptionaloptimizeMemory: booleanManually enable or disable sparse representation. Defaults to true for 8 or more qubits.
Optionalmaterial: TQubitReturns the effective number of quantum units (e.g., qubits) in this state.
ProtectedgetType-safe getter for representation state.
Returns the full array of quantum amplitudes of the quantum state. Uses memoization to reduce memory allocations for repeated access.
Array of quantum amplitudes.
ProtectedgetReconstruct full state vector from sparse Map representation.
ProtectedgetReconstruct full state vector from CSR representation.
Returns the measurement probabilities for all computational basis states.
Returns the probability of measuring a specific computational basis state.
ProtectedgetEvolves the quantum state in time according to a Hamiltonian operator.
ProtectedinvalidateInvalidates memoized amplitude cache when state changes.
ProtectedchooseSelects the appropriate representation for the quantum state.
ProtectedselectSelect the best representation type based on size and sparsity.
ProtectedshouldProtectedcreateCreate CSR format from sparse Map representation.
ProtectedoptimizeConvert CSR format to memory-optimized TypedArray format.
Calculates the estimated memory usage for the current quantum state.
ProtectedcalculateCalculate memory usage for CSR representation.
ProtectedapplyPerform efficient matrix-vector multiplication for CSR representation.
ProtectedapplyPerform efficient sparse matrix-vector multiplication when both matrix and vector are sparse.
ProtectedapplyApplies unitary matrix multiplication with representation-aware algorithms.
OptionalunitaryOperator: UnitaryOperatorProtectedapplyOptimized application of controlled gates for CSR representation.
ProtectedapplyOptimized application of single-qubit gates to large quantum systems.
ProtectedapplyProtectedapplyProtectedStandard dense matrix-vector multiplication. Uses optimized implementation from math/vector-matrix.ts
Dense unitary matrix
New state vector after multiplication
ProtectedapplyProtectedSparse matrix-vector multiplication for sparse Map representation. Uses optimized implementation from math/vector-matrix.ts
Dense unitary matrix
New state vector after multiplication
StaticfromCreates a QubitState representing a specific computational basis state.
Number of qubits in the system
Index of the basis state (0 to 2^numQubits - 1)
New QubitState in the specified basis state
StaticfromCreates a QubitState from a binary string representation.
Binary string (e.g., "101" for |101⟩)
New QubitState representing the specified basis state
Returns the quantum amplitude for a specific basis state. Implementation of Q5mState.amplitude() method.
Index of the computational basis state
Quantum amplitude for the specified basis state
Calculates the state space dimension for the given number of quantum units. For qubits (2-level systems): 2^n.
Applies a unitary operator to this quantum state.
This method uses representation-aware algorithms and preserves the representation type of the original state for consistency.
The unitary operator to apply
A new QubitState after the unitary transformation
Normalizes the quantum state to unit length.
Creates a new quantum state with the specified amplitudes.
Array of quantum amplitudes.
Returns the dimension of the quantum state space (2^n).
Creates a deep copy of the quantum state.
Computes the tensor product with another quantum state.
Another quantum state to tensor with.
Computes the fidelity between this state and another quantum state.
Another quantum state.
Fidelity value between 0 and 1.
Calculates the trace distance between this quantum state and another.
Trace distance is a metric for distinguishing quantum states, ranging from 0 to 1. For pure states, D(|ψ⟩, |φ⟩) = √(1 - |⟨ψ|φ⟩|²)
The other quantum state to compare with
The trace distance between 0 (identical) and 1 (maximally different)
Calculates the inner product (overlap) between this quantum state and another.
The overlap ⟨ψ|φ⟩ is the complex inner product between two state vectors.
The other quantum state to calculate overlap with
The complex overlap value ⟨this|other⟩
Checks if this quantum state is approximately equal to another.
Two states are considered equal if their fidelity is sufficiently close to 1.
The other quantum state to compare with
The tolerance for comparison (default: 1e-10)
True if the states are approximately equal
Returns a string representation of the quantum state.
Decimal precision for amplitudes.
Minimum amplitude magnitude to display.
Calculates the purity of the quantum state. For pure states (which QubitState represents), purity is always 1.
Checks if this quantum system represents a pure state. QubitState always represents pure states, so this always returns true.
Computes the von Neumann entropy of the quantum state. For pure states (which QubitState represents), the entropy is always 0.
StaticzeroCreates a QubitState for the |0⟩ computational basis state.
New QubitState instance representing |0⟩
StaticoneCreates a QubitState for the |1⟩ computational basis state.
New QubitState instance representing |1⟩
StaticplusCreates a QubitState for the |+⟩ Hadamard basis state.
New QubitState instance representing |+⟩
StaticminusCreates a QubitState for the |−⟩ Hadamard basis state.
New QubitState instance representing |−⟩
StaticfromCreates a QubitState from Bloch sphere angles.
Polar angle (0 to π)
Azimuthal angle (0 to 2π)
New QubitState instance corresponding to the specified angles
StaticfromCreates a QubitState from quantum amplitudes.
New QubitState instance with the specified amplitudes (auto-normalized)
Performs a projective measurement on a single qubit in the computational basis. This operation is stochastic and collapses the qubit's state to either |0⟩ or |1⟩.
The measurement outcome, either 0 or 1
ProtectedstateThe total number of basis states in the Hilbert space (its dimension).
ProtectednumThe number of quantum units (e.g., qubits, qutrits) in this state.
ProtectedmaterialThe quantum material associated with this state.
Protected OptionalstateThe state vector containing quantum amplitudes for each basis state. Optional for sparse representations.
Protected OptionalsparseSparse representation using Map for memory optimization
Protected OptionalcsrCSR (Compressed Sparse Row) representation for large sparse states
Protected OptionaloptimizedOptimized CSR representation using TypedArrays
ProtectedrepCurrent representation type
ProtectedsparseConfiguration for sparse optimization
Represents a pure quantum state of qubits with memory optimization and integrated single-qubit operations.
QubitState is the unified quantum state representation in q5m.js, supporting both single qubits and arbitrary multi-qubit systems with automatic optimization for large systems. It provides both the functionality of the original Qubit class for single-qubit operations and the multi-qubit capabilities.
State Representation: |ψ⟩ = Σᵢ αᵢ|i⟩ where |i⟩ are computational basis states and Σᵢ|αᵢ|² = 1
Memory Strategies:
Single Qubit Features:
Computational Basis Ordering (Big-Endian): For n qubits, basis states are ordered as |q_{n-1} ... q_1 q_0⟩. The index
iof the state vector corresponds to the integer value of the bit string.