https://github.com/Rowlito/Chaos/releases

Chaos: GPU Quantum Simulator with 20 Qubits, Shor, Grover, QFT

Table of contents

• Overview
• Why Chaos
• Key features
• Technical highlights
• How Chaos works
• Getting started
  • Prerequisites
  • Installation
  • Quick start
  • Running tests
• API and usage
• Algorithms supported
  • Shor's algorithm
  • Grover search
  • Quantum Fourier Transform
  • General quantum-mechanics simulations
• Performance and benchmarking
• Architecture and components
• GPU acceleration details
• Memory model and scaling
• Data formats and I/O
• Example projects and tutorials
• Contributing
• Licensing
• Release notes and ongoing development

Overview Chaos is a high-performance quantum simulation platform designed for researchers, developers, and educators. It focuses on simulating quantum circuits and algorithms with a strong emphasis on practical performance on modern GPUs. The project targets real-world quantum computing research workloads, including Shor’s algorithm, Grover’s search, and the quantum Fourier transform (QFT). Chaos aims to deliver breakthrough efficiency for large qubit counts, with memory footprints that enable practical exploration on commodity hardware. The core idea is to push beyond traditional simulators by combining GPU acceleration, optimized data layouts, and algorithmic efficiencies that exploit problem structure.

The project combines a clean Python interface with a robust backend that rides on GPU-accelerated math libraries. It is designed to interoperate with popular computing ecosystems in the Python data stack, including numpy and cupy, to ease adoption for researchers and students who already work with numerical tools. Chaos also emphasizes reproducibility, providing deterministic simulation modes, well-defined random seeds, and consistent results across runs on the same hardware configuration.

Chaos is built with an eye toward collaboration. The codebase is modular, and the project welcomes contributions that expand the set of quantum algorithms, improve numerical stability, or extend support for different hardware backends. The repository hosts comprehensive documentation, examples, and tutorials that map directly to typical research workflows. This makes it easy to prototype ideas, compare against benchmarks, and share findings with the community.

Why Chaos In quantum computing research, simulating quantum systems at scale is a demanding task. It requires careful balance between speed, memory usage, and numerical accuracy. Chaos addresses these challenges with a GPU-first approach that leverages parallelism in both state vectors and quantum gates. The design emphasizes:

• Efficient memory usage: simulation of 20 qubits can be achieved with a small memory footprint on GPUs, enabling more interactive exploration.
• Speed scaling: GPU acceleration unlocks substantial speedups for linear-algebra-heavy operations, which dominate quantum state evolution.
• Rich algorithm support: Shor’s algorithm, Grover’s search, and QFT are implemented with practical optimizations, providing a realistic testbed for performance and accuracy.
• Python-friendly workflow: a simple API that fits into familiar Python workflows, while offering a high-performance backend for compute-heavy tasks.
• Open collaboration: an ecosystem designed for researchers and developers to extend, contribute, and validate new ideas.

Key features

• GPU-accelerated quantum simulation with strong support for multi-qubit circuits.
• Efficient simulation of up to 20 qubits on commodity hardware with a memory footprint around 24 MB for representative workloads.
• Implementation of Shor’s algorithm, Grover’s search, and the quantum Fourier transform, with practical examples and benchmarks.
• Compatibility with NumPy and CuPy, enabling seamless integration with the Python scientific stack.
• Cross-platform support for Linux, Windows, and macOS with clear installation procedures.
• Extensible architecture that allows researchers to plug in new backends, gates, and optimizers.
• Comprehensive examples and tutorials that cover common quantum algorithms and workflows.
• Testing suite and continuous integration to verify correctness across changes.
• Clear licensing and governance model to encourage community involvement.

Technical highlights

• State representation: Chaos uses a compact, GPU-friendly state vector representation that reduces memory overhead while preserving numerical stability for typical quantum circuits.
• Gate application: Gate operations are implemented with optimized kernels that exploit CUDA parallelism. Controlled gates and multi-qubit gates are handled through tensor product decompositions and in-place updates where feasible.
• Sparsity and structure: For circuits with structure or sparsity, Chaos employs specialized paths to reduce unnecessary computations, improving performance for common quantum circuits.
• Precision and stability: Numerical precision is chosen to balance accuracy and speed. The default mode offers double-precision for high-fidelity simulations, with a single-precision path for exploratory runs where speed is critical.
• Backends: The platform exposes a GPU backend designed to leverage CUDA-enabled GPUs. A CPU fallback path is available for environments without GPUs, ensuring broad accessibility.
• Interoperability: The Python API is designed to be friendly with numpy and cupy arrays. It also supports exporting data to standard formats for downstream analysis and visualization.

How Chaos works Chaos organizes computation around the state vector, gates, and measurement steps that define a quantum circuit. The workflow typically follows these stages:

• Define qubit wires and register a circuit that describes the sequence of gates.
• Allocate a quantum state vector on the GPU. For a system with n qubits, the state vector has 2^n complex amplitudes.
• Apply gates in a sequence. Each gate updates a subset of amplitudes according to its matrix representation. For multi-qubit gates, Chaos uses efficient composition strategies to avoid constructing full 2^n by 2^n matrices whenever possible.
• Optionally perform measurements to collect statistics that mimic sampling from a quantum circuit.
• Repeat the process for multiple shots or ensemble runs when required by the research workflow.

Chaos emphasizes practical algorithmic implementations. Shor’s algorithm is broken down into modular components such as period finding, modular exponentiation, and quantum modular arithmetic. Grover’s search is implemented with the standard amplitude amplification technique, optimized for common oracle constructions. The QFT is implemented with a carefully optimized circuit that minimizes depth and gate counts while retaining numerical fidelity.

Getting started Practical steps to begin using Chaos are described here. The goal is to get you from installing dependencies to running a simple simulation in a few minutes.

Prerequisites

• A CUDA-capable NVIDIA GPU with a driver that supports current CUDA toolkits. Chaos’s GPU backend relies on CUDA for kernel execution and optimized memory access patterns.
• Python 3.x. A modern Python environment, such as 3.8 or newer, is recommended to ensure compatibility with the latest NumPy, CuPy, and other dependencies.
• CUDA toolkit and related libraries for GPU development. This includes the CUDA driver, cuFFT, cuBLAS, and other performance-critical libraries that underpin many linear-algebra operations used by the simulator.
• Basic development tools for your platform. This includes compilers, build tools, and a working shell for command-line operations.

Installation

• Clone the repository:
  • git clone https://github.com/Rowlito/Chaos.git
  • cd Chaos
• Set up a virtual environment to isolate dependencies:
  • python3 -m venv venv
  • source venv/bin/activate (on Windows use venv\Scripts\activate)
• Install Python dependencies:
  • pip install -r requirements.txt
• Build GPU extensions (if provided by the project):
  • python setup.py build_ext --inplace
• If you encounter issues, ensure your CUDA toolkit version matches the project's supported versions and that the GPU driver is up to date.
• For Windows users, consider using the WSL 2 environment or your native Windows toolchain as appropriate. The project aims to maintain compatibility across major platforms, but some edge cases may require platform-specific tweaks.

Quick start

• Create a small quantum circuit description and run a basic simulation. The API is designed to be intuitive for researchers who already work with numpy and cupy.
• Example workflow (pseudo-code style, to illustrate the idea):
  • import chaos
  • sim = chaos.Simulator(backend='gpu')
  • circuits = chaos.Circuit([Hadamard(0), CNOT(0, 1), Rz(π/4)(2)])
  • result = sim.run(circuits)
  • print(result.probabilities)
• Chaos exposes a simple, Pythonic API that lets you define qubits, gates, and measurements without wrestling with low-level GPU code. The backend handles kernel configuration and optimization automatically, so you can focus on the quantum algorithm itself.

Running tests

• The project includes a test suite to validate correctness and performance across major features.
• To run tests locally:
  • pytest tests
  • Ensure the CUDA device is visible to the test environment if you are testing the GPU path.
• The test suite covers functional correctness, numerical stability checks, and regression tests for critical gates and algorithms.

API and usage

• Core concepts
  • Quantum circuit: A sequence of gates applied to qubits.
  • Gate: A unitary operation that transforms the quantum state.
  • Circuit execution: Evolve the state vector under gate operations.
  • Measurement: Collapse the quantum state and produce classical outcomes according to the Born rule.
• Key classes
  • Simulator: The main entry point for running simulations. It accepts parameters for backend selection, precision, and optimization flags.
  • Circuit: A container for gates and qubits. It provides utilities for building and validating quantum circuits.
  • Gate: Base class for all quantum gates. Derived classes implement common gates such as X, Y, Z, H, S, T, RX, RY, RZ, and multi-qubit gates like CNOT and CZ.
  • Backend: Abstraction for different compute backends. GPU is the primary backend, with a CPU fallback.
  • Results: Encapsulates measurement outcomes, probabilities, and statistics for a given run.
• Example usage
  • from chaos import Circuit, Simulator, Gates
  • circuit = Circuit(n_qubits=3)
  • circuit.add_gate(Gates.H(0))
  • circuit.add_gate(Gates.CNOT(0, 1))
  • sim = Simulator(backend='gpu', precision='double')
  • results = sim.run(circuit, shots=1024)
  • print(results.histogram())

Algorithms supported Shor's algorithm

• Chaos provides a practical, GPU-accelerated implementation of Shor's algorithm tailored for demonstration and research. It includes modular exponentiation, period finding via quantum phase estimation, and measurement strategies suited for educational or exploratory experiments.
• The implementation is designed to illustrate the core ideas of Shor’s algorithm without requiring specialized quantum hardware. It emphasizes numerical stability, traceable error behavior, and reproducible results across similar hardware configurations.
• Researchers can modify the modular exponentiation steps, experiment with different oracle constructions, and compare the impact on gate depth and circuit width.

Grover's search

• Grover’s search is implemented as a standard amplitude amplification technique. Chaos allows you to define an oracle that marks the solution(s) and then applies the Grover diffusion operator to amplify the desired state amplitude.
• The library includes common oracle patterns that correspond to typical search problems. It also provides utilities to wrap classical predicates into quantum-oracle constructions for experimentation.
• Performance considerations include careful gate scheduling to minimize circuit depth and reduce the number of required qubits while preserving the fidelity of the search result.

Quantum Fourier Transform (QFT)

• The QFT is implemented with an efficient low-depth circuit that scales well with the number of qubits. Chaos provides a configurable depth-accuracy trade-off so you can study the impact of gate count on hardware noise models in a simulated environment.
• The QFT component integrates with the broader circuit framework, allowing you to place QFT blocks within larger quantum algorithms and analyze interference patterns and phase relationships.

General quantum-mechanics simulations

• Chaos supports a wide range of quantum-mechanics simulations beyond the main algorithms. You can define custom gates, simulate time evolution under Hamiltonians, and study measurement statistics for complex systems.
• The framework emphasizes modularity so researchers can replace or extend parts of the simulation stack, including gate representations, state representations, and backends.

Performance and benchmarking

• Memory footprint: Chaos targets a compact memory footprint for multi-qubit simulations. For typical 20-qubit workloads, the simulator operates within tens of megabytes on supported GPUs. This unusual efficiency is achieved through a combination of careful data layout, optimized kernel usage, and problem-structure-aware computations.
• Speed: On supported GPU hardware, Chaos achieves substantial speedups over conventional CPU-based simulators due to parallelized gate applications and batched linear algebra operations. The performance gains enable more complex experiments and interactive exploration of quantum circuits.
• Efficiency vs accuracy: Chaos provides configuration options to balance speed and precision. Users can opt for double precision for the most faithful results or single precision for faster exploratory runs. The default settings are chosen to preserve accuracy while offering practical performance.
• Benchmark suite: The project ships with a benchmark suite that compares Chaos against reference simulators on a set of standard circuits. Results include gate counts, depth, and measured runtimes, helping researchers evaluate hardware choices and algorithmic optimizations.
• Reproducibility: The benchmarking results are designed to be reproducible. This means identical seeds and deterministic execution paths where supported by the backend. The project aims to provide a stable baseline for performance discussions across different hardware platforms.

Architecture and components

• Frontend: The Python API provides a clear interface for building circuits, adding gates, and running simulations. It is designed to be intuitive for researchers who already use numpy and cupy.
• Core engine: The engine manages state vectors, gate matrices, and the scheduling of kernel launches on the GPU. It emphasizes parallel execution and memory coalescing for high throughput.
• Backends: Chaos exposes a backend abstraction. The GPU backend is the primary path, while a CPU fallback offers accessibility when GPU resources are unavailable.
• Gate library: A comprehensive set of gates covers single-qubit, two-qubit, and multi-qubit operations. Each gate type includes an efficient kernel implementation and a straightforward interface for composition into larger circuits.
• Circuit representation: Circuits are stored in a way that supports both compact representation and easy traversal for optimization. Gate rasters and qubit mappings are handled efficiently to minimize recomputation.
• I/O and data exchange: Chaos supports exporting circuit descriptions, results, and intermediate data to standard formats. This makes it easy to share experiments and integrate with other tools in the quantum software ecosystem.
• Tests and quality: Automated tests cover correctness, numerical stability, and performance metrics across multiple hardware configurations. The CI pipeline exercises both GPU and CPU paths to ensure broad compatibility.

GPU acceleration details

• CUDA kernels: Gate applications are implemented as CUDA kernels that operate on batches of amplitudes in parallel. This approach takes advantage of the massive parallelism available on modern GPUs.
• Memory access: The backends optimize memory access patterns to minimize bandwidth usage and maximize cache hits. Strided and tiled access patterns help with large qubit counts.
• CuPy integration: The Python interface leverages CuPy in many hot paths, providing familiar numpy-like semantics while retaining GPU acceleration.
• Hardware requirements: Chaos is designed to work with a wide range of GPUs. For best results, use GPUs with ample CUDA cores and fast memory bandwidth. Newer architectures often yield better throughput for large circuits.
• Portability: The codebase is modular enough to support other accelerators in the future. While the current focus is on CUDA-enabled GPUs, the architecture is designed with platform flexibility in mind.

Memory model and scaling

• 20-qubit simulations: Chaos targets practical simulations for up to 20 qubits on standard GPU hardware, balancing memory usage and accuracy. The 24 MB memory figure is a representative footprint under typical workloads, not a universal constant; actual memory usage varies with gate count, circuit depth, and precision.
• Scaling behavior: As qubits grow, the state vector grows exponentially. Chaos uses a mix of on-device parallelism and algorithmic optimizations to push toward higher qubit counts without a dramatic jump in memory requirements.
• Precision-aware scaling: Users can tune precision to trade memory for speed. Lower precision reduces memory needs and increases throughput but may affect fidelity for some circuits. The library provides guidance and tooling to help you choose the right mode for your study.
• Bandwidth and kernel fusion: The software employs kernel fusion and memory reuse strategies to cut down on global memory traffic, which is a major bottleneck in large quantum simulations.
• Streaming and pipelining: To maximize GPU utilization, Chaos pipelines gate applications and memory transfers. This approach reduces idle time and improves overall throughput.

Data formats and I/O

• Circuit descriptions: Circuits are described in a structured, human-readable format that maps gates to qubits and clock cycles. The format supports serialization and deserialization for sharing and reproducibility.
• Results: Measurement results, distributions, and fidelity metrics can be exported to common formats such as CSV or JSON. This makes it straightforward to analyze results in Python, R, or data visualization tools.
• Interchangeability: The project provides utilities to convert circuits between internal representations and common external formats. This helps researchers port experiments from Chaos to other frameworks or share with collaborators.
• Visualization: Basic visualization tools are included to plot probability distributions, state amplitudes, and measurement histograms. The visuals are designed to convey intuition about quantum behavior without requiring deep quantum theory knowledge.

Example projects and tutorials

• Quick tutorials: A set of guided tutorials demonstrates how to build simple quantum circuits, run shots, and visualize outcomes. Each tutorial highlights common pitfalls and best practices.
• Realistic workloads: Examples cover common research scenarios, such as simulating depth-limited circuits with error models, exploring Grover search on moderate datasets, and implementing a compact QFT block within a larger algorithm.
• Educational modules: Aimed at students and teachers, these modules explain core concepts with runnable code. They emphasize clarity and reproducibility.
• Community projects: The ecosystem includes community-led examples and mini-projects. These showcase different modeling approaches and help newcomers see how to extend Chaos for their needs.

Contributing

• How to contribute: Chaos welcomes contributions from researchers, students, and practitioners. You can contribute by adding new algorithms, improving kernel performance, extending API coverage, or writing tutorials.
• Setting up a development environment: Start by creating a fork, then clone your fork locally. Use a virtual environment to manage dependencies. Run the test suite to verify your changes locally.
• Coding standards: The project follows established Python and CUDA coding standards. Contributions should include unit tests and documentation updates where relevant.
• Review process: Pull requests go through a lightweight review process. Maintainers look for correctness, performance impact, and code clarity. Community feedback is encouraged to shape the project’s direction.
• Documentation and examples: Contributors are encouraged to add or improve examples and tutorials. Clear, runnable examples help others understand how to use Chaos effectively.
• Issue tracking: Open issues should be precise. Include steps to reproduce, expected outcomes, and actual results. This helps maintainers triage and address problems quickly.
• Community guidelines: The project fosters respectful communication and constructive feedback. Collaboration is welcomed across institutions and industries.

License

• Chaos uses an open license designed to encourage broad adoption and collaboration. The license supports academic and commercial use, with reasonable attribution requirements. Always review the LICENSE file in the repository for the exact terms and conditions.

Release notes and ongoing development

• The latest release page contains downloadable assets, release notes, and upgrade guidance. To obtain the most recent builds and release artifacts, visit the Releases page.
• The release notes document new features, fixes, and performance improvements. They provide context for researchers who want to reproduce experiments or compare against prior runs.
• For ongoing development, the main branch contains the latest integration work. Users who want cutting-edge features can try the nightly builds or pre-release assets when available.

Downloads and releases

• The project provides downloadable assets through its releases page. If you are looking for a ready-to-run package or prebuilt artifacts, search that page for the latest build corresponding to your platform. From the releases page, download the latest Chaos package and run the installer to set up your environment.
• For quick access, a colorful download button is available above that links to the releases page. This makes it easy to grab the latest builds and begin experimentation without digging through the repo.

Notes on usage and safety

• The Chaos platform is designed for research and education. It does not attempt to replace real quantum hardware. It aims to provide a practical sandbox to model quantum algorithms and explore their behavior under ideal and noisy conditions.
• When using hardware acceleration, ensure you are running within a controlled environment. Keep drivers up to date and follow best practices for GPU management to avoid conflicts with other software.
• Always validate results with multiple seeds and, when possible, compare against analytic expectations or established reference simulators to ensure your setup is sound.

Community and ecosystem

• The Chaos project thrives on community input. You can contribute code, documentation, tutorials, and example datasets. The ecosystem welcomes collaborations from academia, industry, and independent researchers.
• Community channels include discussion forums, issue trackers, and collaborative projects. Engaging with the community helps improve the simulator and expands its range of use cases.

Usage tips and best practices

• Start small: Begin with a 2- or 3-qubit circuit to verify basic gate behavior and result reporting. This helps you establish a baseline before scaling up.
• Profile your workload: Use the provided benchmarks to identify bottlenecks. Profiling can reveal whether your workload is memory-bound or compute-bound.
• Tune precision: If speed is critical and you can tolerate some approximation, experiment with single precision. For high-fidelity simulations, use double precision.
• Leverage structure: If your circuit contains blocks with known structure, consider reorganizing the circuit to maximize gate fusion and kernel efficiency.
• Save intermediate results: When testing new ideas, save intermediate state vectors or checkpoint circuits to reduce recomputation and facilitate debugging.
• Cross-validate: Compare Chaos results with other simulators for common benchmarks. Discrepancies can reveal numerical sensitivities or implementation issues worth investigating.

Security and safety considerations

• Chaos focuses on numerical simulation and educational use. It does not introduce hardware-level risks or network exposure beyond typical software libraries.
• When running on shared systems, ensure appropriate resource quotas to prevent contention with other users. Use isolation mechanisms such as virtual environments or containerization where appropriate.

Images and visuals

• The README includes visuals to help readers quickly grasp concepts. A high-quality schematic of a quantum circuit and a GPU-accelerated processing diagram illustrate the core ideas.
• Visuals are chosen to be accessible and informative. They aim to convey both the abstract concepts and the practical performance implications of Chaos.
• You can replace the visuals with your own approved graphics as you tailor the repository to your organization or research group.

Examples of real-world use cases

• Quantum algorithm research: Researchers can prototype and compare different circuit designs for Shor’s algorithm, Grover’s search, and QFT in a GPU-accelerated environment.
• Education: Instructors can demonstrate quantum phenomena and algorithmic ideas with interactive notebooks that run locally on GPUs.
• Performance engineering: Engineers can test optimizations for gate kernels, memory layouts, and kernel fusion strategies to squeeze more performance from limited hardware.
• Collaboration: Teams can share reproducible experiments, collaborate on new gate implementations, and publish results with clear release artifacts.

Footnotes on naming and branding

• Chaos is the official project name for this repository. The branding reflects the blend of cutting-edge quantum computing ideas and the practical, fast-paced nature of GPU-accelerated simulation.
• The project logo and visual identity emphasize clarity, precision, and a forward-looking research mindset. Visuals are designed to be informative without overpowering the technical content.

Future directions

• Expansion to more backends: While the current focus is GPU acceleration with CuPy, future work could broaden support to other accelerators, such as AMD GPUs or specialized hardware, while preserving a consistent user experience.
• Noise modeling: Adding configurable noise models would help researchers study error mitigation strategies and understand hardware limitations more deeply.
• Larger qubit counts: Ongoing efforts aim to extend efficient simulation to higher qubit counts by exploiting problem structure, approximate methods, and advanced memory techniques.
• Enhanced tooling: Improved notebooks, tutorials, and example datasets will help new users adopt Chaos quickly and effectively.
• Collaboration channels: The project will continue to foster open collaboration with clear contribution guidelines, issue templates, and release management to maintain a healthy, productive ecosystem.

Final notes

• Chaos combines a clean Python API with a GPU-backed engine designed for high-performance quantum simulation. It emphasizes accessibility, extensibility, and reproducibility to support researchers and educators in exploring quantum algorithms and quantum mechanics.
• The Releases page is the primary portal for obtaining builds, updates, and release notes. If you are looking for the latest stable or pre-release assets, that page is your best starting point.
• By design, Chaos invites collaboration. If you have ideas, propose changes, or contribute new algorithms, the project is ready to review and integrate your work. The community’s knowledge, combined with GPU-accelerated computation, can drive rapid progress in quantum simulation research.