Contributing

We welcome contributions to NoisyCircuits! If you would like to contribute, here’s how you can help:

• Bug Reports: Report issues or unexpected behavior on our Github Issues page.

• Feature Requests: Suggest new features or improvements by opening a feature request on our Github repository.

• Documentation: Improvements to tutorials, examples or API documentation are always welcome.

• Testing: Add test cases or improve validation coverage for existing features.

• Code Contributions: Implement new features or optimize existing code.

Development Workflow

1. Fork the repository on GitHub.

2. Setup a development environment:

3. Make your changes and commit them with clear messages. Add tests for new features.

4. Run the unit tests to ensure everything works as expected:

5. Run the Validation suite to ensure compliance with existing functionality

6. Push your changes to your fork and open a Pull Request against the main repository with a detailed description of your changes.

Contributing Guidelines

• Code Style: Follow PEP 8 python coding style guidelines.

• Maintain the existing repository structure (as shown below).

• Documentation: Ensure all new features are well-documented with docstrings and examples.

• Testing: Include unit tests for new features and ensure existing tests pass.

• Backwards Compatibility: Maintain Compatibility with existing APIs unless there is a strong reason to break them.

Repository Structure

The repository is organized as follows

NoisyCircuits/
├── docs/                                           # Documentation source files
│   ├── source/                                     # Sphinx documentation source (do not edit for API changes. Use docstrings)
│   ├── build/                                      # Built documentation (files generated by Sphinx)
├── src/NoisyCircuits/                              # Main package source code
│   ├── __init__.py
│   ├── QuantumCircuit.py                           # Core quantum circuit class
│   ├── RunOnHardware.py                            # Module to create, submit and retreive quantum circuits from IBM Quantum hardware
│   └── 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
├── tests/                                          # Unit and Integration test suite
├── noise_models/                                   # Directory with sample noise models
├── 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
├── environment.yml                                 # Conda environment specification
├── setup.py                                        # Package installation configuration
├── requirements.txt                                # Python dependencies
└── pytest.toml                                     # Pytest configuration file
└── README.md                                       # Project overview
└── LICENSE                                         # License information

Adding New QPUs

To add support for a new QPU architecture, follow these steps:

1. Create a new decomposition module in src/NoisyCircuits/utils/ that inherits from the Decomposition abstract class with the name of the QPU. For example, if the QPU is named “QuantumX”, create a file named QuantumXDecomposition.py which has a class QuantumXDecomposition(Decomposition).

2. Implement the required methods for gate decomposition specific to the new QPU architecture. Refer to existing implementations like EagleDecomposition.py and HeronDecomposition.py for guidance. Ensure that all implemented gates are covered in the decomposition and that the gate decomposition exactly matches the behavior of the original gates (i.e., no global phase differences).

3. Update the method names in QuantumCircuit.py to include the new QPU architecture where necessary (as shown below):

# Import the new decomposition module
from NoisyCircuits.utils.QuantumXDecomposition import QuantumXDecomposition
...
# Update the QPU information within the QuantumCircuit class attribute `basis_gates_set`
class QuantumCircuit:
    ...
    basis_gates_set = {
        "eagle" : {
            "basis_gates" : [["rz", "sx", "x"], ["ecr"]],
            "gate_decomposition" : EagleDecomposition
        },
        "heron" : {
            "basis_gates" : [["rz", "sx", "x", "rx"], ["cz", "rzz"]],
            "gate_decomposition" : HeronDecomposition
        },
        "quantumx" : {
            "basis_gates" : [["rz", "sx", "x", "h"], ["cx"]],
            "gate_decomposition" : QuantumXDecomposition
        }
    }
    ...

4. Run the unit tests to ensure everything works as expected:

pytest tests/

5. Update the documentation to include information about the new QPU support.

6. Submit a Pull Request with your changes and a detailed description of the new QPU support.

Getting Help

If you need assistance or have questions about contributing, feel free to reach out via our GitHub Discussions page or open an issue.

• Author: Sathyamurthy Hegde

• GitHub: @Sats2