QState

Overview

QState represents a quantum state vector. It stores a vector of Complex amplitudes and provides utilities for normalization, conjugation, and inner products.

Import

import { QState } from "@masabando/quantum-gates"

Constructor

Create a state from an array of numbers or Complex values. By default, the state is treated as a column vector.

import { QState, Complex } from "@masabando/quantum-gates"

const ket0 = new QState([1, 0])

const ket1 = new QState([0, 1])

const psi = new QState([

  new Complex(1 / Math.sqrt(2), 0),

  new Complex(0, 1 / Math.sqrt(2)),

])

Row / column vectors

QState can represent either a column vector (|ψ⟩) or a row vector (⟨ψ|). Many operations require the correct orientation.

const ket = new QState([1, 0], true)  // column (default)

const bra = ket.dagger()               // row

Scaling and normalization

Use scale to multiply amplitudes by a scalar.magnitude returns the vector norm, and normalize returns a normalized state.

const s = new QState([2, 0])

console.log(s.magnitude())

const sn = s.normalize()

const half = sn.scale(0.5)

Transpose / conjugate / dagger

These methods return new states.

• transpose(): swaps row and column orientation
• conjugate(): element-wise complex conjugation
• dagger(): conjugate transpose (conjugate().transpose())

const bra = ket.dagger()

const ket2 = bra.dagger()

Inner product

Compute an inner product ⟨ψ|φ⟩ using applyState. The left operand must be a row vector and the right operand must be a column vector.

const psi = new QState([1, 0])

const phi = new QState([0, 1])

const inner = psi.dagger().applyState(phi)

console.log(inner.toString())

Applying a matrix

Apply a matrix to a state using applyMatrix. This operation follows the orientation rules used in the implementation.

// row vector × matrix

const braNext = bra.applyMatrix(matrix)

Bloch coordinates

For a single-qubit state (column vector), xyz returns the Bloch sphere coordinates computed from Pauli expectations.

const psi = new QState([1, 0])

const { x, y, z } = psi.xyz

console.log(x, y, z)

Notes

• QState does not automatically normalize the vector.
• Methods throw errors when the orientation (row/column) or dimensions are incompatible.