Changelog

View Source

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

0.6.0 - 2026-05-04

Added

  • OpenQASM 3.0 import — Qx.Export.OpenQASM.from_qasm/1 and from_qasm!/1 parse OpenQASM 3 source produced by Qx itself, by Qiskit, or by IBM Quantum and return a %Qx.QuantumCircuit{}. Round-trips with to_qasm/1 (statevectors match within 1e-10).
  • Gate definition codegen — Qx.Export.OpenQASM.from_qasm_function/1 (and the bang variant) parses a gate name(p1, …) a, b { … } definition and returns %{name, arity, source}, where source is an Elixir def … string that compiles via Code.compile_string/1. Function signature: (circuit, params…, qubits…).
  • Supported gate set on import — direct mappings for h, x, y, z, s, sdg, t, rx, ry, rz, p, phase, u, u3, cx, CX, cz, swap, iswap, cp, cphase, ccx, cswap. Decompositions for tdg → phase(-π/4), sx → u(π/2, -π/2, π/2), u1(λ) → phase(λ), u2(φ, λ) → u(π/2, φ, λ). id is dropped.
  • Typed import errors — Qx.QasmParseError (line/column/snippet) and Qx.QasmUnsupportedError (feature/line/hint) for grammar failures and out-of-scope features respectively.
  • Qx.cp/4 — controlled-phase gate applying e^(i·θ) to the |11⟩ basis state, required for QFT and QPE circuits
  • Qx.swap/3 — SWAP gate exchanging the quantum states of two qubits; includes circuit diagram rendering (× symbols connected by a line) and OpenQASM 3 export
  • Qx.iswap/3 — iSWAP gate exchanging qubit states with an i phase factor on the swapped components; native to superconducting hardware; includes circuit diagram rendering (labelled iSW boxes) and OpenQASM 3 export
  • Qx.u/5 — general single-qubit unitary gate U(θ,φ,λ) per IBM/OpenQASM 3 convention; subsumes X, Y, Z, H, RX, RY, RZ as special cases; includes circuit diagram rendering and OpenQASM 3 export
  • Qx.cswap/4 — Fredkin (controlled-SWAP) gate; swaps two target qubits when the control is |1⟩; universal reversible gate used in quantum multiplexers and arithmetic circuits; includes circuit diagram rendering and OpenQASM 3 export

Not supported on import (raises Qx.QasmUnsupportedError)

  • Multi-register programs (Qx models a single quantum + single classical register)
  • else branches on if (refactor as two if statements)
  • Gate modifiers inv @, pow(N) @, ctrl @, negctrl @
  • def, for, while, switch, classical types beyond bit, defcal, let, pragma, extern, box, delay, reset
  • stdgates cy, ch, crx, cry, crz, cu (no Qx equivalent yet)
  • Qiskit-extension gates rxx, ryy, rzz, rzx (not in stdgates.inc)
  • Discarded measure q[i]; (Qx requires a classical bit target)
  • Complex boolean conditions (&&, ||)

Dependencies

  • New runtime dependency: nimble_parsec ~> 1.4 (compile-time parser generator)

0.5.2 - 2026-04-11

Added

  • Bell State Extensions - Qx.bell_state/2 now supports all four Bell states: phi_plus (default), phi_minus, psi_plus, and psi_minus

Fixed

  • Circuit diagram: measurement arrowhead now terminates at the classical register double line instead of extending 8 px past it
  • Bloch sphere rendering: improved wireframe contrast, white halos on axis and state labels, and equatorial projection indicator for clearer visualization

0.5.1 - 2026-03-07

Added

  • S-dagger (Sdg) Gate - New sdg gate implementing the S† operation (-π/2 phase rotation on |1⟩)
    • Qx.sdg/2 for Circuit Mode: adds an sdg gate to a quantum circuit
    • Qx.Operations.sdg/2 for direct operations API
    • Qx.Qubit.sdg/1 for Calculation Mode on single qubits
    • Qx.Register.sdg/2 for Calculation Mode on multi-qubit registers
    • Full simulation support in Qx.Simulation (mapped to Qx.Gates.s_dagger/0)
    • OpenQASM 3.0 export support (sdg q[0];)
    • Validation support for the :sdg gate atom
    • Full test coverage including matrix correctness, S·S† = I identity verification, and circuit export
  • New LiveBook Tutorials - Expanded tutorial collection at examples/tutorials/
    • quantum_state_and_qubit.livemd - Introduction to quantum states and single-qubit operations
    • quantum_measurement.livemd - Quantum measurement concepts and examples
    • systems_of_qubits_and_entanglement.livemd - Multi-qubit systems and entanglement
    • quantum_algorithms.livemd - Common quantum algorithms with Qx

0.5.0 - 2026-02-17

Added

  • Remote Execution via QxServer - Run quantum circuits on real hardware through QxServer
    • New Qx.Remote module for submitting circuits, polling job status, and retrieving results
    • New Qx.Remote.Config for configuring QxServer connection (URL, API key, timeout)
    • New Qx.ResultBuilder for constructing Qx.SimulationResult structs from hardware counts data
    • New Qx.RemoteError exception type for remote execution errors
    • Example script at examples/remote/run_on_hardware.exs
  • Quantum Operations Tutorial - New comprehensive LiveBook tutorial covering quantum gates, Bloch sphere, and two-qubit operations at examples/tutorials/quantum_operations_tutorial.livemd

Changed

  • README Restructure - Major reorganization for better new-user experience
    • Moved Performance & Acceleration section (~380 lines) from between Installation and Quick Start to the end
    • Removed API Reference section (duplicated by hexdocs) and Module Structure section
    • Added "Understanding the Two Modes" orientation section with comparison table
    • Added consolidated Visualization section
    • Added links to hexdocs and LiveBook guides
    • Reduced README from 1,308 to ~750 lines

Fixed

  • Qx.Qubit.draw_bloch/2 now correctly defaults to :vega_lite format (was ignoring the default and using :svg)
  • Draw functions (Qx.Draw.plot_counts/2, Qx.Draw.plot/2) now correctly handle SimulationResult structs from hardware backends where counts keys are binary strings
  • OpenQASM export formatting improvements

0.4.0 - 2025-12-23

Added

  • OpenQASM 3.0 Export - Export quantum circuits to OpenQASM format for real quantum hardware execution
    • Full support for OpenQASM 3.0 syntax including conditionals
    • Export via Qx.Export.OpenQASM.to_qasm/2 with customizable options
    • Supports all quantum gates, measurements, barriers, and conditional operations
    • Enables seamless integration with IBM Quantum, Rigetti, and other quantum hardware platforms
  • Error Handling Documentation (qx-gd5) - Comprehensive CONTRIBUTING.md with error handling philosophy and best practices
    • Detailed guidelines for error types, messages, and recovery strategies
    • Error handling patterns for library developers
    • Examples of proper error propagation and context enrichment
    • Documentation of all custom error types and their use cases
  • Test Coverage Integration (qx-xbf) - Complete test coverage metrics and CI/CD integration
    • Added ExCoveralls dependency for code coverage reporting
    • Achieved 66.4% test coverage across the codebase
    • Integrated coverage reporting into CI/CD pipeline
    • Configured multiple coverage output formats (HTML, JSON, Cobertura)
    • Added GitHub Actions integration for coverage tracking

Changed

  • Predicate Function Conventions (qx-7iw) - Enhanced predicate naming and specifications
    • Added @spec type specifications to all predicate functions
    • Improved naming conventions for boolean-returning functions
    • Enhanced documentation for predicate function usage patterns
    • Better consistency across module APIs
  • Module Documentation (qx-sdb) - Verified comprehensive module documentation
    • Confirmed all modules have proper @moduledoc documentation
    • Ensured consistent documentation style across the codebase
    • Enhanced module-level descriptions and usage examples

Fixed

  • Credo strict mode compliance in OpenQASM export module
    • Refactored complex pattern matching to reduce cyclomatic complexity
    • Used Enum.map_join/3 for better performance
    • Added inline Credo exception for legitimate gate mapping complexity

Improved

  • Development workflow with better error handling guidelines
  • Code quality with comprehensive type specifications
  • Test coverage visibility and tracking
  • Documentation completeness and consistency
  • Hardware integration capabilities via OpenQASM export

0.3.0 - 2025-12-21

Added

  • Runtime Backend Selection - Major new feature allowing backend specification at runtime without compile-time configuration
    • Added :backend option to Qx.run/2, Qx.get_state/2, and Qx.get_probabilities/2
    • Users can now specify different backends for different circuits: Qx.run(circuit, backend: EXLA.Backend)
    • Supports all Nx backends including EXLA (CPU/CUDA/ROCm) and EMLX (Apple Silicon GPU)
    • Combines with other options: Qx.run(circuit, backend: EXLA.Backend, shots: 2048)
    • Maintains full backward compatibility with existing code
    • Implemented using Nx.with_default_backend/2 for proper scoped execution
    • Comprehensive documentation added to README.md with usage examples and best practices

Changed

  • Draw Module Refactoring - Reorganized visualization code for better maintainability and clarity
    • Split large 1,531-line Qx.Draw module into 5 focused sub-modules:
    • Qx.Draw now serves as a clean API facade, delegating to specialized sub-modules
    • Maintains 100% backward compatibility - no API changes required
    • Improved code organization following single responsibility principle
    • Better separation of concerns between rendering formats and visualization types
    • All 557 tests continue to pass

Fixed

  • Fixed Nx backend configuration anti-pattern where library imposed compile-time backend choices on users
  • Eliminated warnings about undefined Nx.default_backend/2 function

0.2.5 - 2025-12-16

Fixed

  • More fixes to the pipeline

0.2.4 - 2025-12-16

Fixed

  • More automation of the release and build process
  • pipeline fixes

0.2.3 - 2025-12-14

Fixed

  • Simplified application configuration to resolve Nx.Defn compilation issues
  • Removed unnecessary application dependencies that were causing compile-time conflicts

0.2.2 - 2025-12-14

Fixed

  • Added nx and complex to extra_applications in mix.exs to fix compilation errors when using the Hex package
  • Ensures dependencies are loaded before qx_sim compiles

Changed

  • Published to Hex.pm as qx_sim (package name "qx" was already taken)
  • Updated installation instructions to use Hex.pm syntax
  • Added Hex.pm badges to README

0.2.1 - 2025-11-26

Changed

  • Improved readability of Bloch sphere labels
  • Refactored code and tidied up documentation
  • Cleaned up old test files
  • Updated README.md

Fixed

  • Fixed CNOT gate error
  • Fixed dependencies
  • Fixed mix.exs configuration

0.2.0 - 2025-11-01

Added

Core Quantum Computing Features

  • Full quantum circuit API with chainable operations via Qx module
  • Support for 20+ quantum gates including:
    • Single-qubit gates: H, X, Y, Z, S, T, Sdg, Tdg
    • Parametric rotation gates: RX, RY, RZ with arbitrary angles
    • Two-qubit gates: CNOT (CX), CZ (Controlled-Z), SWAP
    • Multi-qubit support up to 20 qubits
  • Measurement operations with classical bit storage and reset capabilities
  • Conditional operations based on classical measurement results
  • Statevector simulation using Nx tensors with Complex64 format
  • Direct state access via Qx.get_state/1

Visualization

  • Circuit diagram generation with Qx.Draw.circuit/2 for publication-quality SVG output
  • State visualization using VegaLite: bar charts, probability distributions, Bloch sphere
  • SVG export capability for all visualization types
  • Example visualization scripts in examples/ directory including circuit_visualization_example.exs

Performance & Acceleration

  • EXLA backend integration for CPU acceleration (~100x speedup vs Binary)
  • EMLX backend support for Apple Silicon GPU acceleration (M1/M2/M3/M4)
  • Automatic backend detection and configuration
  • JIT compilation support via Nx.Defn

Benchmarking Suite

  • Professional benchmarking infrastructure using Benchee
  • GHZ state scaling benchmarks (5, 10, 15, 20 qubits)
  • Backend comparison benchmarks (Binary, EXLA CPU, EMLX GPU, EXLA CUDA/ROCm)
  • HTML report generation with interactive graphs
  • Statistical analysis with warmup, iterations, and memory profiling
  • Safe GPU backend detection with graceful fallback

Documentation & Examples

  • Comprehensive API documentation with examples
  • Example files demonstrating:
    • Basic quantum circuit operations
    • Complex number handling
    • Bell state creation
    • Quantum teleportation protocol
    • Conditional circuit operations
    • Grover's search algorithm
    • Circuit visualization techniques
  • Performance benchmarking guide
  • Backend configuration documentation

Error Handling

Changed

  • Updated state representation to use :c64 (Complex64) tensor format for improved performance
  • Migrated from Torchx to EMLX for Apple Silicon GPU acceleration (pure Elixir, no Python)
  • Enhanced error messages with context and suggestions
  • Improved documentation structure with module grouping
  • Updated examples to work with latest Complex number API

Performance

  • ~100x speedup with EXLA CPU backend compared to Binary backend
  • Additional 2-10x speedup with GPU acceleration (hardware dependent)
  • Efficient statevector manipulation with direct tensor operations
  • Optimized gate application avoiding unnecessary matrix construction

Fixed

  • Complex number handling in example files for :c64 format
  • CZ gate now properly exposed in main Qx module API
  • Backend detection error handling for unavailable GPU platforms
  • Output directory creation in visualization examples
  • Grover's algorithm now uses proper CZ gates instead of H-CX-H decomposition

Developer Experience

  • Added :usage_rules dependency for better development ergonomics
  • Comprehensive test suite with 549 passing tests
  • Modular architecture separating concerns (Circuit, Operations, Simulation, etc.)
  • Clean API design following Elixir conventions

0.1.0 - 2024-10-05

Added

  • Initial release
  • Basic quantum circuit functionality
  • Core gate operations
  • Statevector simulation
  • Nx backend integration

Future Roadmap

Potential Additions

  • Additional quantum gates (Toffoli, Fredkin, controlled rotations)
  • Quantum Fourier Transform implementation
  • Noise models for realistic simulations
  • Density matrix simulation for mixed states
  • OpenQASM import (export is available since v0.4.0)
  • Performance optimizations for larger circuits