Quantum Manager
- class sequence.kernel.quantum_manager.QuantumManager
Class to track and manage quantum states (abstract).
All states stored are of a single formalism (by default as a ket vector).
- Class Attributes:
_registry (dict): mapping of formalism names to manager classes. _global_formalism_lock (Lock): lock for managing global formalism. _global_formalism (str): global formalism.
- _least_available
tracking the total number of quantum states in the quantum network
- Type:
int
- classmethod create(*args, **kwargs) QuantumManager
Create a new instance of the quantum manager.
- get(key: int) State
Method to get quantum state stored at an index.
- Parameters:
key (int) – key for quantum state.
- Returns:
quantum state at supplied key.
- Return type:
- abstractmethod new(state: Any = None) int
Method to create a new quantum state.
- Parameters:
state (Any) – State payload for the new state. Type depends on subclass.
- Returns:
key for new state generated.
- Return type:
int
- classmethod register(name: str, manager_class=None)
Register a quantum manager class.
- Parameters:
name (str) – The name of the quantum manager.
manager_class (type, optional) – The manager class to register.
- remove(key: int) None
Method to remove state stored at key.
- Parameters:
key (int) – The key of the state to remove.
- abstractmethod set(keys: list[int], state: Any) None
Method to set quantum state at a given key(s).
- Parameters:
keys (list[int]) – key(s) of state(s) to change.
state (Any) – State payload to assign, type determined by type of subclass.
- classmethod set_global_manager_formalism(formalism: str)
Set the global manager formalism.
- Parameters:
formalism (str) – The formalism to set as the global manager formalism.
- set_states(states: dict)
Set multiple quantum states.
- Parameters:
states (dict) – A dictionary mapping keys to their corresponding quantum states.
- class sequence.kernel.quantum_manager.QuantumManagerBellDiagonal
Class to track and manage quantum states with the bell diagonal formalism.
To be aligned with analytical formulae, we have assumed that successfully generated EPR pair is in Phi+ form. And note that the 4 BDS elements are in I, Z, X, Y order.
BDS is only used for entanglement distribution (generation, swapping, purification), assuming underlying errors being purely Pauli.
All manipulation results can be tracked analytically, without explicit quantum gates / channels / measurements.
- get(key: int)
Method to get quantum state stored at an index.
- Parameters:
key (int) – key for quantum state.
- Returns:
quantum state at supplied key.
- Return type:
- new(state=None) int
Generates new quantum state key for quantum manager.
NOTE: since this generates only one state, there will be no corresponding entangled state stored. The Bell diagonal state formalism assumes entangled states; thus, attempting to call get will return an exception until entangled. The purpose of this function is thus mainly to avoid state key collisions.
- Parameters:
state (Any) – to conform to type definition (does nothing).
- Returns:
quantum state key corresponding to state.
- Return type:
int
- set(keys: list[int], diag_elems: list[float]) None
Method to set the state of given keys to a Bell diagonal state with given diagonal elements. If the keys list is not of length 2, the keys will be removed from the quantum manager
- Parameters:
keys (list[int]) – list of quantum manager keys to modify.
diag_elems (list[float]) – list of 4 diagonal elements of Bell diagonal state, in I, Z, X, Y order.
- class sequence.kernel.quantum_manager.QuantumManagerDensity
Class to track and manage states with the density matrix formalism.
- get_ascending_keys(key: int) DensityState
- Method to get quantum state stored at an index.
Reorders qubits (in-place) in ascending order of keys before returning.
- Parameters:
key (int) – key for quantum state.
- Returns:
quantum state at supplied key.
- Return type:
- new(state: list[complex] | tuple[complex, ...] | list[list[complex]] | tuple[tuple[complex, ...], ...] = ((1 + 0j, 0j), (0j, 0j))) int
Method to create a new density matrix state.
- Parameters:
state (OneDimensionInput | TwoDimensionInput) – 2D density matrix or 1D pure-state array.
- Returns:
key of the new state.
- Return type:
int
- reorder_qubits_ascending_keys(state: DensityState) None
- Update the quantum state (in-place) to match the ascending order of keys.
Meanwhile, the reordered state is also set in the quantum manager.
- Parameters:
state (DensityState) – The quantum state to reorder.
- run_circuit(circuit: Circuit, keys: list[int], meas_samp=None) dict[int, int]
Method to run a circuit on a given list of keys.
- Parameters:
circuit (Circuit) – quantum circuit to apply.
keys (list[int]) – list of keys to apply circuit to.
meas_samp (float) – random number between 0 and 1 used for measurement.
- Returns:
dictionary mapping qstate keys to measurement results. If non-measurement, dict: empty dictionary.
- Return type:
If measurement, dict[int, int]
- set(keys: list[int], state: list[complex] | tuple[complex, ...] | list[list[complex]] | tuple[tuple[complex, ...], ...]) None
Method to set the quantum state at the given keys.
The state argument may be a 1D pure-state vector or a 2D density matrix.
- Parameters:
keys (list[int]) – list of quantum manager keys to modify.
state – quantum state to set input keys to.
- class sequence.kernel.quantum_manager.QuantumManagerDensityFock(truncation: int = 1)
Class to track and manage Fock states with the density matrix formalism.
- truncation
maximally allowed number of excited states for elementary subsystems. Default is 1 for qubit.
- Type:
int
- dim
subsystem Hilbert space dimension. dim = truncation + 1
- Type:
int
- add_loss(key, loss_rate)
Method to apply generalized amplitude damping channel on a single subspace corresponding to key.
- Parameters:
key (int) – key for the subspace experiencing loss.
loss_rate (float) – loss rate for the quantum channel.
- build_ladder()
Generate matrix of creation and annihilation (ladder) operators on truncated Hilbert space.
- measure(keys: list[int], povms: list[NDArray], meas_samp: float) int
Method to measure subsystems at given keys in POVM formalism.
Serves as wrapper for private _measure method, performing quantum manager specific operations.
- Parameters:
keys (list[int]) – list of keys to measure.
povms – (list[array]): list of POVM operators to use for measurement.
meas_samp (float) – random measurement sample to use for computing resultant state.
- Returns:
measurement as index of matching POVM in supplied tuple.
- Return type:
int
- new(state=None) int
Method to create a new state with key
- Parameters:
state (str | list[complex] | list[list[complex]]) – amplitudes of new state. Default value is ‘gnd’: create zero-excitation state with current truncation. Other inputs are passed to the constructor of DensityState.
- set(keys: list[int], state: list[list[complex]]) None
Method to set the quantum state at the given keys.
The state argument should be passed as list[list[complex]], where each internal list is a row. However, the state may also be given as a one-dimensional pure state. If the list is one-dimensional, will be converted to matrix with the outer product operation.
- Parameters:
keys (list[int]) – list of quantum manager keys to modify.
state – quantum state to set input keys to.
- set_to_zero(key: int)
set the state to ground (zero) state.
- Parameters:
key (int) – key of the state to set to ground state.
- class sequence.kernel.quantum_manager.QuantumManagerKet
Class to track and manage quantum states with the ket vector formalism.
- get_ascending_keys(key: int) KetState
- Method to get quantum state stored at an index.
Reorders qubits (in-place) in ascending order of keys before returning.
- Parameters:
key (int) – key for quantum state.
- Returns:
quantum state at supplied key.
- Return type:
- new(state: list[complex] | tuple[complex, ...] = (1 + 0j, 0j)) int
Method to create a new ket state.
- Parameters:
state (OneDimensionInput) – 1D state-vector amplitudes.
- Returns:
the key of the new state.
- Return type:
int
- reorder_qubits_ascending_keys(state: KetState) None
- Update the quantum state (in-place) to match the ascending order of keys.
Meanwhile, the reordered state is also set in the quantum manager.
- Parameters:
state (KetState) – The quantum state to reorder.
- run_circuit(circuit: Circuit, keys: list[int], meas_samp=None) dict[int, int]
Method to run a circuit on a given list of keys.
- Parameters:
circuit (Circuit) – quantum circuit to apply.
keys (list[int]) – list of keys to apply circuit to.
meas_samp (float) – random sample used for measurement result.
- Returns:
dictionary mapping qstate keys to measurement results. If non-measurement, dict: empty dictionary.
- Return type:
If measurement, dict[int, int]
- set(keys: list[int], amplitudes: list[complex] | tuple[complex, ...]) None
Set the quantum state for the given keys.
- Parameters:
keys (list[int]) – list of keys of the quantum state.
amplitudes (OneDimensionInput) – amplitudes to set the state to.
- class sequence.kernel.quantum_manager.QuantumManagerStabilizer(seed: int | None = None, **kwargs)
Quantum manager for stabilizer-state simulation.
- base_seed
Base seed for deterministic child-seed generation.
- Type:
int | None
- noise_rng
NumPy random generator used to sample stochastic noise events.
- one_qubit_gate_fid
Single-qubit gate fidelity.
- Type:
float
- two_qubit_gate_fid
Two-qubit gate fidelity.
- Type:
float
- measurement_fid
Measurement reporting fidelity.
- Type:
float
- initialization_fid
Initialization fidelity for newly prepared qubits.
- Type:
float
- gate_error_channel
Gate-noise channel mode, either depolarize (uniform) or Pauli-weighted.
- Type:
str
- idle_error_channel
Idle-noise channel mode, either depolarize (uniform) or Pauli-weighted (T1/T2-derived asymmetric channel).
- Type:
str
- pauli_1q_weights
Normalized X/Y/Z weights for one-qubit Pauli errors.
- Type:
tuple[float, …]
- pauli_2q_weights
Normalized Stim-order weights for two-qubit Pauli errors.
- Type:
tuple[float, …]
- last_idle_time_ps_by_key
Last idle-time watermark for each state key.
- Type:
dict[int, int]
- gate_1q_count
Number of sampled one-qubit gates.
- Type:
int
- gate_2q_count
Number of sampled two-qubit gates.
- Type:
int
- gate_1q_error_count
Number of inserted one-qubit gate errors.
- Type:
int
- gate_2q_error_count
Number of inserted two-qubit gate errors.
- Type:
int
- measurement_count
Number of sampled measurements.
- Type:
int
- measurement_error_count
Number of inserted measurement reporting errors.
- Type:
int
- apply_idling_decoherence(keys: list[int], now_ps: int, t1_sec: float, t2_sec: float)
- Apply time-based idling decoherence to the provided keys.
The PAULI_CHANNEL_1 applies the standard T1/T2 to Pauli approximation and requires 0 < T2 <= 2*T1
- Parameters:
keys – Quantum-manager keys to decohere.
now_ps – Current simulation time in picoseconds.
t1_sec – Shared T1 time constant in seconds.
t2_sec – Shared T2 time constant in seconds.
- get_circuit_duration(circuit: Circuit) int
Return the estimated execution time of a circuit in picoseconds.
- Parameters:
circuit – Stim circuit to estimate.
- Returns:
Estimated circuit duration in picoseconds.
- Return type:
int
- get_error_statistics() dict[str, int | float]
Return per-run gate accounting statistics.
- Returns:
One- and two-qubit gate counts, sampled gate-error counts, and measurement counts.
- Return type:
dict[str, int | float]
- get_reset_duration(num_qubits: int) int
Return the estimated reset time in picoseconds.
- Parameters:
num_qubits – Number of qubits being reset.
- Returns:
Estimated reset duration in picoseconds.
- Return type:
int
- new(state: StabilizerState | Tableau | TableauSimulator | list | None = None) int
Create and register a new stabilizer-state key.
- Parameters:
state (Optional[Union[StabilizerState, Tableau, TableauSimulator, list]]) – Optional initializer: - None: default seeded single-qubit simulator state. - StabilizerState: copied and rebound to the new key. - TableauSimulator: copied and rebound to the new key. - Tableau / state vector list: converted to simulator state.
- Returns:
Newly allocated state key.
- Return type:
int
- Raises:
TypeError – If state is not a supported initializer type.
- remove(key: int)
Remove a key and refresh the debug key layout map.
- Parameters:
key (int) – State key to remove.
- reset_error_statistics()
Clear gate and error counters
- run_circuit(circuit: Circuit, keys: list[int], inject_gate_error: bool = False) dict[int, int]
Execute a Stim circuit on stabilizer states.
- Parameters:
circuit – Stim circuit to execute.
keys (list[int]) – Ordered keys mapped to circuit qubit indices.
inject_gate_error – If True, execute ideal gates and then apply injected gate-noise channels.
- Returns:
Measurement outcomes keyed by measured state keys.
- Return type:
dict[int, int]
- set(keys: list[int], state: StabilizerState | Tableau | TableauSimulator | list)
Assign a shared stabilizer state object to one or more keys.
- Parameters:
keys (list[int]) – State keys that should reference the same state.
state (StabilizerState | Tableau | TableauSimulator | list) – State payload to assign.