A Python package for creating and simulating noisy quantum circuits using error models from IBM (Heron RX / Eagle RX) quantum hardware calibration data. The package implements the Monte-Carlo Wave Function (MCWF) method for efficient statevector simulation of noisy quantum systems.
The documentation for the package can be found here.
NoisyCircuits enables researchers and developers to:
- Simulate realistic quantum noise using calibration data from IBM QPU (Heron/Eagle) chipsets
- Perform efficient noisy statevector simulations with the Monte-Carlo Wave Function method
- Validate quantum algorithms under realistic hardware conditions
- Develop noise-aware quantum machine learning applications
- Compare quantum algorithms between ideal and noisy regimes
Hardware-Calibrated Noise Models: Direct integration with IBM Quantum backend calibration data
Parallel Monte-Carlo Simulation: Multi-core trajectory execution for scalable performance
Gate Set: Support for IBM Eagle QPU basis gates (X, √X, Rz, ECR) and Heron QPU basis gates (X, √X, Rz, Rx, CZ, RZZ)
Validation Framework: Built-in comparison with the density matrix method
Research Applications: Ready-to-use examples for quantum machine learning and algorithm development
The supported gated are fully decomposed into the hardware basis gates and this decomposition is applied to the circuit.
- Single-qubit gates: X, Y, Z, √X, Hadamard, Rx(θ), Ry(θ), Rz(θ)
- Two-qubit gates: ECR, CX, CY, CZ, CRx(θ), CRy(θ), CRz(θ), SWAP, RZZ(θ), RXX(θ), RYY(θ)
- Unitary Operation: Additionally, a unitary operator can be applied to the circuit. This unitary operator is not decomposed and is applied fully to the quantum circuit assuming a perfect implmenetation.
- Python 3.10 or higher
- A conda-based environment manager (Miniconda, Anaconda, or Micromamba)
- IBM Quantum account and API token (for noise model access, optional. Sample Noise Data is made available.)
-
Clone the repository:
git clone https://github.com/Sats2/NoisyCircuits.git cd NoisyCircuits -
Create and activate the conda environment:
conda env create -f environment.yml conda activate NoisyCircuits
-
Install the package:
pip install .
For development or if you plan to modify the code:
pip install -e .Core dependencies are automatically installed:
- PennyLane: Quantum computing framework
- Qiskit: IBM Quantum software stack
- Ray: Distributed computing for parallel execution
- NumPy, Matplotlib: Scientific computing and visualization
The validation/ and examples/ directories contains comprehensive validation and example notebooks:
- Method Verification: Statistical comparison between MCWF and exact density matrix simulation
- Performance Benchmarking: Trajectory convergence and computational efficiency analysis
- Quantum Machine Learning: CFD parameter prediction using quantum neural networks
- Algorithm Comparison: Performance analysis under realistic noise conditions
- Educational Resources: Step-by-step tutorials for quantum noise simulation
Quick Test: Run the introduction notebook to validate your installation:
jupyter notebook examples/introduction.ipynbFor detailed information about the example suite, see examples/README.md.
- Method Verification: Validation and accuracy testing of the MCWF method for noisy quantum circuit simulations compared against the density matrix simulation.
- Parallel Execution: Scaling simulations across multiple CPU cores (tested for shared memory architecture)
- Statistical Validation: Ensuring simulation accuracy through multiple metrics
- Introduction: Basic usage and configuration
- Quantum Neural Networks: Machine learning applications
- Hardware Submission: Creating, submitting and retreiving results from IBM hardware.
- Multiple Hardware Submissions: Creating, submitting and retreiving multiple quantum circuits from IBM Hardware.
- Monte-Carlo Wave Function: Efficient method for simulating open quantum systems
- Hardware Noise Models: Using real device calibration data for realistic simulations
We welcome contributions to NoisyCircuits! Here's how you can help:
- Bug Reports: Report issues or unexpected behavior
- Feature Requests: Suggest new functionality or improvements
- Documentation: Improve tutorials, examples, or API documentation
- Testing: Add test cases or improve validation coverage
- Code Contributions: Implement new features or optimize existing code
To be updated along with version release
NoisyCircuits/
├── src/NoisyCircuits/ # Main package source code
│ ├── __init__.py
│ ├── QuantumCircuit.py # Core quantum circuit class
│ └── utils/ # Utility modules
│ └── __init__.py
│ ├── GetNoiseModel.py # IBM backend integration to retreive Calibration Data
│ ├── BuildQubitGateModel.py # Module to generate the noise operators
│ ├── DensityMatrixSolver.py # Module to simulate a circuit with the density matrix method
│ ├── PureStateSolver.py # Module to simulate a circuit without noise (statevector simulator)
│ └── ParallelExecutor.py # Module to simulate a circuit with the MCWF method
│ └── Decomposition.py # Abstract class for QPU based gate decomposition
│ └── EagleDecomposition.py # Gate Decomposition for Eagle QPU
│ └── HeronDecomposition.py # Gate Decomposition for Heron QPU
│ └── SwapSequence.py # Module that ensures correct qubit coupling
├── docs/ # Directory with documentation. Automatically generated from source code API --> DO NOT CHANGE
├── noise_models/ # Directory with sample noise models
│ ├── README.md # Detailed documentation (will be added)
│ ├── Noise_Model_Eagle_QPU.pkl # Sample Noise Model for the Eagle QPU taken from IBM Brisbane calibration data
│ ├── Noise_Model_Heron_QPU.pkl # Sample Noise Model for the Heron QPU taken from IBM Fez calibration data
├── examples/ # Example suite and examples
│ ├── README.md # Detailed documentation
│ ├── introduction.ipynb # Getting started tutorial
│ ├── quantum_neural_networks.ipynb # ML application example
│ └── run_on_hardware.ipynb # Tutorial to create, submit and retreive a quantum circuit from hardware
│ └── run_multiple_on_hardware.ipynb # Tutorial to create, submit and retreive multiple quantum circuits from hardware
│ └── design_study_single_feature.csv # Sample dataset
├── validation/ # Validation suite
│ ├── README.md # Detailed documentation
│ ├── method_verification.ipynb # Validation against exact methods
│ ├── Results_Log_File.txt # Results of the validation study compiled in a single log file
├── tests/ # Test suite for Unit and Integration Testing consisting of local and Git CI/CD actions testing.
├── environment.yml # Conda environment specification
├── setup.py # Package installation configuration
├── requirements.txt # Python dependencies
├── pytest.toml # Configuration for Pytest
└── LICENSE # MIT License
-
Fork the repository and create a feature branch:
git checkout -b feature/your-feature-name
-
Set up development environment:
conda env create -f environment.yml conda activate NoisyCircuits pip install -e . # Install in development mode
-
Make your changes and add tests if applicable
-
Run the validation suite:
jupyter notebook test/method_verification.ipynb
-
Submit a pull request with a clear description of your changes
- Code Style: Follow PEP 8 python style guidelines
- Documentation: Update docstrings and README files for new features
- Testing: Include test cases for new functionality
- Backwards Compatibility: Maintain compatibility with existing APIs when possible
- Issues: Use GitHub Issues for bug reports and feature requests
- Discussions: Start a GitHub Discussion for questions and ideas
This project is licensed under the MIT License - see the LICENSE file for details.
If you use NoisyCircuits in your research, please cite the software as follows:
@software{NoisyCircuits2025,
author = {Hegde, Sathyamurthy},
title = {NoisyCircuits},
year = {2025},
url = {https://github.com/Sats2/NoisyCircuits},
version = {1.3.0},
}
- Author: Sathyamurthy Hegde
- GitHub: @Sats2
For more detailed information, examples, and tutorials, please refer to the documentation in the examples/ directory.