uniqc.simulator.base_simulator module#

Base simulator classes for UnifiedQuantum.

This module provides abstract base classes for quantum circuit simulators, defining common behaviors and interfaces for statevector and density matrix simulations. It also includes topology validation and qubit mapping utilities.

Key exports:

TopologyError: Exception for invalid qubit/topology configurations.
BaseSimulator: Abstract base for ideal circuit simulators.
BaseNoisySimulator: Abstract base for noisy circuit simulators.

class uniqc.simulator.base_simulator.BaseNoisySimulator(backend_type='statevector', available_qubits=None, available_topology=None, error_loader=None, readout_error={})[source]#

Bases: BaseSimulator

Noisy simulator base class supporting error models and readout errors.

Extends BaseSimulator with noise simulation capabilities including gate errors (via ErrorLoader) and measurement readout errors.

Parameters:

available_qubits (List[int])
available_topology (List[List[int]])
error_loader (ErrorLoader)
readout_error (Dict[int, List[float]])

simulate_density_matrix(originir)[source]#

Compute the density matrix with noise effects applied.

Parameters:

originir – Quantum program in the simulator’s input format.

Returns:

Density matrix as a 2D numpy array.

Raises:

NotImplementedError – If readout_error is set.
ValueError – If backend is not density_operator type.

simulate_pmeasure(originir)[source]#

Compute measurement probabilities with noise effects.

Parameters:: originir – Quantum program in the simulator’s input format.
Returns:: List of probabilities for each measurement outcome.
Raises:: ValueError – If backend is not density_operator type.

simulate_preprocess(originir)[source]#

Parse, preprocess, and inject errors into the quantum program.

Parameters:: originir – Quantum program in the simulator’s input format.
Returns:: Tuple containing the error-injected program body and measurement qubits.

simulate_shots(quantum_code, shots)[source]#

Execute the noisy circuit multiple times and return measurement counts.

Parameters:

quantum_code – Quantum program code.
shots – Number of measurement shots to perform.

Returns:

Dictionary mapping outcome bitstrings (int) to their count.

simulate_single_shot(originir)[source]#

Execute the noisy circuit and return a single measurement sample.

Parameters:: originir – OriginIR quantum program.
Returns:: Integer representing the measured bitstring (decimal).

simulate_statevector(originir)[source]#

Not supported for noisy simulators.

Raises:: NotImplementedError – Noisy simulators do not support statevector simulation.

class uniqc.simulator.base_simulator.BaseSimulator(backend_type='statevector', available_qubits=None, available_topology=None, **extra_kwargs)[source]#

Bases: object

Abstract base class for quantum circuit simulators.

This class describes common behaviors of simulators. It is not designed to be used directly; instead, it should be subclassed by specific simulators (e.g., OriginIR_Simulator, QASM_Simulator).

Parameters:

available_qubits (List[int])
available_topology (List[List[int]])

simulate_density_matrix(quantum_code)[source]#

Compute the density matrix representation of the final state.

Parameters:: quantum_code – Quantum program code.
Returns:: Density matrix as a 2D numpy array.

simulate_pmeasure(quantum_code)[source]#

Compute measurement probabilities for all qubits.

Parameters:: quantum_code – Quantum program code.
Returns:: List of probabilities for each measurement outcome.

simulate_preprocess(originir)[source]#

Parse and preprocess the quantum program.

Extracts the actual used qubits, builds qubit mapping (e.g., q45 -> 0), checks topology constraints, and returns processed program body and measurement qubits.

Parameters:: originir – Quantum program in the simulator’s input format.
Returns:: Tuple containing the processed program body and measurement qubits.

simulate_shots(quantum_code, shots)[source]#

Execute the circuit multiple times and return measurement counts.

Parameters:

quantum_code – Quantum program code.
shots – Number of measurement shots to perform.

Returns:

Dictionary mapping outcome bitstrings (int) to their count.

simulate_single_shot(quantum_code)[source]#

Execute the circuit and return a single measurement sample.

Parameters:: quantum_code – Quantum program code.
Returns:: Integer representing the measured bitstring (decimal).

simulate_stateprob(quantum_code)[source]#

Compute state probabilities (|amplitude|^2) for all basis states.

Parameters:: quantum_code – Quantum program code.
Returns:: Array of probabilities for each basis state.

simulate_statevector(quantum_code)[source]#

Compute the final statevector after executing the circuit.

Parameters:: quantum_code – Quantum program code.
Returns:: Statevector as a complex numpy array.

property simulator#: Return the underlying simulator instance.

property state#: Return the current state of the simulator (statevector or density matrix).

exception uniqc.simulator.base_simulator.TopologyError[source]#

Bases: Exception

Exception raised when an invalid qubit or topology is used.