ddsim package

Submodules

ddsim.error module

Exception for errors raised by DDSIM simulator.

exception ddsim.error.DDSIMError(*message)[source]

Bases: QiskitError

Class for errors raised by the DDSIM simulator.

ddsim.hybridqasmsimulator module

Backend for DDSIM Hybrid Schrodinger-Feynman Simulator.

class ddsim.hybridqasmsimulator.HybridQasmSimulatorBackend(configuration=None, provider=None)[source]

Bases: BackendV1

Python interface to MQT DDSIM Hybrid Schrodinger-Feynman Simulator

SHOW_STATE_VECTOR = False

run(quantum_circuits: QuantumCircuit | List[QuantumCircuit], **options)[source]

Run on the backend.

This method returns a Job object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation.

Parameters:

run_input (QuantumCircuit or Schedule or list) – An individual or a list of QuantumCircuit or Schedule objects to run on the backend. For legacy providers migrating to the new versioned providers, provider interface a QasmQobj or PulseQobj objects should probably be supported too (but deprecated) for backwards compatibility. Be sure to update the docstrings of subclasses implementing this method to document that. New provider implementations should not do this though as qiskit.qobj will be deprecated and removed along with the legacy providers interface.
options – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object.

Returns:

The job object for the run

Return type:

Job

run_experiment(qobj_experiment: QasmQobjExperiment, **options)[source]

status()[source]: Return backend status. :returns: the status of the backend. :rtype: BackendStatus

ddsim.hybridstatevectorsimulator module

Backend for DDSIM Hybrid Schrodinger-Feynman Simulator.

class ddsim.hybridstatevectorsimulator.HybridStatevectorSimulatorBackend(configuration=None, provider=None)[source]

Bases: HybridQasmSimulatorBackend

Python interface to MQT DDSIM Hybrid Schrodinger-Feynman Simulator

SHOW_STATE_VECTOR = True

ddsim.job module

class ddsim.job.DDSIMJob(backend, job_id, fn, qobj_experiment, **args)[source]

Bases: JobV1

AerJob class. .. attribute:: _executor

executor to handle asynchronous jobs

type:

futures.Executor

backend()[source]: Return the instance of the backend used for this job.

cancel()[source]: Attempt to cancel the job.

result(timeout=None)[source]

Get job result. The behavior is the same as the underlying concurrent Future objects, https://docs.python.org/3/library/concurrent.futures.html#future-objects :param timeout: number of seconds to wait for results. :type timeout: float

Returns:

Result object

Return type:

qiskit.Result

Raises:

concurrent.futures.TimeoutError – if timeout occurred.
concurrent.futures.CancelledError – if job cancelled before completed.

status() → JobStatus[source]

Gets the status of the job by querying the Python’s future :returns: The current JobStatus :rtype: JobStatus

Raises:

JobError – If the future is in unexpected state
concurrent.futures.TimeoutError – if timeout occurred.

submit()[source]: Submit the job to the backend for execution. :raises QobjValidationError: if the JSON serialization of the Qobj passed :raises during construction does not validate against the Qobj schema.: :raises JobError: if trying to re-submit the job.

ddsim.job.requires_submit(func)[source]

Decorator to ensure that a submit has been performed before calling the method. :param func: test function to be decorated. :type func: callable

Returns:: the decorated function.
Return type:: callable

ddsim.pathqasmsimulator module

Backend for DDSIM Task-Based Simulator.

class ddsim.pathqasmsimulator.PathQasmSimulatorBackend(configuration=None, provider=None)[source]

Bases: BackendV1

Python interface to MQT DDSIM Simulation Path Framework

SHOW_STATE_VECTOR = False

run(quantum_circuits: QuantumCircuit | List[QuantumCircuit], **options)[source]

Run on the backend.

This method returns a Job object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation.

Parameters:

run_input (QuantumCircuit or Schedule or list) – An individual or a list of QuantumCircuit or Schedule objects to run on the backend. For legacy providers migrating to the new versioned providers, provider interface a QasmQobj or PulseQobj objects should probably be supported too (but deprecated) for backwards compatibility. Be sure to update the docstrings of subclasses implementing this method to document that. New provider implementations should not do this though as qiskit.qobj will be deprecated and removed along with the legacy providers interface.
options – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object.

Returns:

The job object for the run

Return type:

Job

run_experiment(qobj_experiment: QasmQobjExperiment, **options)[source]

status()[source]: Return backend status. :returns: the status of the backend. :rtype: BackendStatus

ddsim.pathqasmsimulator.create_tensor_network(qc)[source]

ddsim.pathqasmsimulator.get_simulation_path(qc, max_time: int = 60, max_repeats: int = 1024, parallel_runs: int = 1, dump_path: bool = True, plot_ring: bool = False)[source]

ddsim.pathqasmsimulator.read_tensor_network_file(filename)[source]

ddsim.pathstatevectorsimulator module

Backend for DDSIM.

class ddsim.pathstatevectorsimulator.PathStatevectorSimulatorBackend(configuration=None, provider=None)[source]

Bases: PathQasmSimulatorBackend

Python interface to MQT DDSIM Simulation Path Framework

SHOW_STATE_VECTOR = True

ddsim.provider module

class ddsim.provider.DDSIMProvider[source]

Bases: ProviderV1

backends(name=None, filters=None, **kwargs)[source]

Return a list of backends matching the specified filtering.

Parameters:

name (str) – name of the backend.
**kwargs – dict used for filtering.

Returns:

a list of Backends that match the filtering: criteria.

Return type:

list[Backend]

get_backend(name=None, **kwargs)[source]

Return a single backend matching the specified filtering.

Parameters:

name (str) – name of the backend.
**kwargs – dict used for filtering.

Returns:

a backend matching the filtering.

Return type:

Backend

Raises:

QiskitBackendNotFoundError – if no backend could be found or more than one backend matches the filtering criteria.

ddsim.pyddsim module

ddsim.qasmsimulator module

Backend for DDSIM.

class ddsim.qasmsimulator.QasmSimulatorBackend(configuration=None, provider=None)[source]

Bases: BackendV1

Python interface to MQT DDSIM

SHOW_STATE_VECTOR = False

run(quantum_circuits: QuantumCircuit | List[QuantumCircuit], **options) → DDSIMJob[source]

Run on the backend.

This method returns a Job object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation.

Parameters:

run_input (QuantumCircuit or Schedule or list) – An individual or a list of QuantumCircuit or Schedule objects to run on the backend. For legacy providers migrating to the new versioned providers, provider interface a QasmQobj or PulseQobj objects should probably be supported too (but deprecated) for backwards compatibility. Be sure to update the docstrings of subclasses implementing this method to document that. New provider implementations should not do this though as qiskit.qobj will be deprecated and removed along with the legacy providers interface.
options – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object.

Returns:

The job object for the run

Return type:

Job

run_experiment(qobj_experiment: QasmQobjExperiment, **options) → Dict[source]

status() → BackendStatus[source]: Return backend status. :returns: the status of the backend. :rtype: BackendStatus

ddsim.statevectorsimulator module

Backend for DDSIM.

class ddsim.statevectorsimulator.StatevectorSimulatorBackend(configuration=None, provider=None)[source]

Bases: QasmSimulatorBackend

Python interface to MQT DDSIM

SHOW_STATE_VECTOR = True

ddsim.unitarysimulator module

Backend for DDSIM Unitary Simulator.

class ddsim.unitarysimulator.UnitarySimulatorBackend(configuration=None, provider=None, **fields)[source]

Bases: BackendV1

Decision diagram-based unitary simulator.

run(quantum_circuits: QuantumCircuit | List[QuantumCircuit], **options)[source]

Run on the backend.

This method returns a Job object that runs circuits. Depending on the backend this may be either an async or sync call. It is at the discretion of the provider to decide whether running should block until the execution is finished or not: the Job class can handle either situation.

Parameters:

run_input (QuantumCircuit or Schedule or list) – An individual or a list of QuantumCircuit or Schedule objects to run on the backend. For legacy providers migrating to the new versioned providers, provider interface a QasmQobj or PulseQobj objects should probably be supported too (but deprecated) for backwards compatibility. Be sure to update the docstrings of subclasses implementing this method to document that. New provider implementations should not do this though as qiskit.qobj will be deprecated and removed along with the legacy providers interface.
options – Any kwarg options to pass to the backend for running the config. If a key is also present in the options attribute/object then the expectation is that the value specified will be used instead of what’s set in the options object.

Returns:

The job object for the run

Return type:

Job

run_experiment(qobj_experiment: QasmQobjExperiment, **options)[source]

Module contents

class ddsim.CircuitSimulator

Bases: pybind11_object

expectation_value(self: mqt.ddsim.pyddsim.CircuitSimulator, observable: object) → float

get_active_matrix_node_count(self: mqt.ddsim.pyddsim.CircuitSimulator) → int: Get the number of active matrix nodes, i.e., the number of matrix DD nodes in the unique table with a non-zero reference count.

get_active_vector_node_count(self: mqt.ddsim.pyddsim.CircuitSimulator) → int: Get the number of active vector nodes, i.e., the number of vector DD nodes in the unique table with a non-zero reference count.

get_max_matrix_node_count(self: mqt.ddsim.pyddsim.CircuitSimulator) → int: Get the maximum number of (active) matrix nodes, i.e., the maximum number of matrix DD nodes in the unique table at any point during the simulation.

get_max_vector_node_count(self: mqt.ddsim.pyddsim.CircuitSimulator) → int: Get the maximum number of (active) vector nodes, i.e., the maximum number of vector DD nodes in the unique table at any point during the simulation.

get_name(self: mqt.ddsim.pyddsim.CircuitSimulator) → str: Get the name of the simulator

get_number_of_qubits(self: mqt.ddsim.pyddsim.CircuitSimulator) → int: Get the number of qubits

get_tolerance(self: mqt.ddsim.pyddsim.CircuitSimulator) → float: Get the tolerance for the DD package.

get_vector(self: mqt.ddsim.pyddsim.CircuitSimulator) → List[complex]: Get the state vector resulting from the simulation.

set_tolerance(self: mqt.ddsim.pyddsim.CircuitSimulator, tol: float) → None: Set the tolerance for the DD package.

simulate(self: mqt.ddsim.pyddsim.CircuitSimulator, shots: int) → Dict[str, int]: Simulate the circuit and return the result as a dictionary of counts.

statistics(self: mqt.ddsim.pyddsim.CircuitSimulator) → Dict[str, str]: Get additional statistics provided by the simulator

class ddsim.ConstructionMode

Bases: pybind11_object

Members:

recursive

sequential

property name

recursive = <ConstructionMode.recursive: 1>

sequential = <ConstructionMode.sequential: 0>

property value

class ddsim.DDSIMProvider[source]

Bases: ProviderV1

backends(name=None, filters=None, **kwargs)[source]

Return a list of backends matching the specified filtering.

Parameters:

name (str) – name of the backend.
**kwargs – dict used for filtering.

Returns:

a list of Backends that match the filtering: criteria.

Return type:

list[Backend]

get_backend(name=None, **kwargs)[source]

Return a single backend matching the specified filtering.

Parameters:

name (str) – name of the backend.
**kwargs – dict used for filtering.

Returns:

a backend matching the filtering.

Return type:

Backend

Raises:

QiskitBackendNotFoundError – if no backend could be found or more than one backend matches the filtering criteria.

class ddsim.HybridCircuitSimulator

Bases: pybind11_object

get_active_matrix_node_count(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → int: Get the number of active matrix nodes, i.e., the number of matrix DD nodes in the unique table with a non-zero reference count.

get_active_vector_node_count(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → int: Get the number of active vector nodes, i.e., the number of vector DD nodes in the unique table with a non-zero reference count.

get_final_amplitudes(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → List[complex]

get_max_matrix_node_count(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → int: Get the maximum number of (active) matrix nodes, i.e., the maximum number of matrix DD nodes in the unique table at any point during the simulation.

get_max_vector_node_count(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → int: Get the maximum number of (active) vector nodes, i.e., the maximum number of vector DD nodes in the unique table at any point during the simulation.

get_mode(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → mqt.ddsim.pyddsim.HybridMode

get_name(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → str: Get the name of the simulator

get_number_of_qubits(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → int: Get the number of qubits

get_tolerance(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → float: Get the tolerance for the DD package.

get_vector(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → List[complex]: Get the state vector resulting from the simulation.

set_tolerance(self: mqt.ddsim.pyddsim.HybridCircuitSimulator, tol: float) → None: Set the tolerance for the DD package.

simulate(self: mqt.ddsim.pyddsim.HybridCircuitSimulator, shots: int) → Dict[str, int]: Simulate the circuit and return the result as a dictionary of counts.

statistics(self: mqt.ddsim.pyddsim.HybridCircuitSimulator) → Dict[str, str]: Get additional statistics provided by the simulator

class ddsim.HybridMode

Bases: pybind11_object

Members:

DD

amplitude

DD = <HybridMode.DD: 0>

amplitude = <HybridMode.amplitude: 1>

property name

property value

class ddsim.PathCircuitSimulator

Bases: pybind11_object

get_active_matrix_node_count(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → int: Get the number of active matrix nodes, i.e., the number of matrix DD nodes in the unique table with a non-zero reference count.

get_active_vector_node_count(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → int: Get the number of active vector nodes, i.e., the number of vector DD nodes in the unique table with a non-zero reference count.

get_max_matrix_node_count(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → int: Get the maximum number of (active) matrix nodes, i.e., the maximum number of matrix DD nodes in the unique table at any point during the simulation.

get_max_vector_node_count(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → int: Get the maximum number of (active) vector nodes, i.e., the maximum number of vector DD nodes in the unique table at any point during the simulation.

get_name(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → str: Get the name of the simulator

get_number_of_qubits(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → int: Get the number of qubits

get_tolerance(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → float: Get the tolerance for the DD package.

get_vector(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → List[complex]: Get the state vector resulting from the simulation.

set_simulation_path(self: mqt.ddsim.pyddsim.PathCircuitSimulator, arg0: List[Tuple[int, int]], arg1: bool) → None

set_tolerance(self: mqt.ddsim.pyddsim.PathCircuitSimulator, tol: float) → None: Set the tolerance for the DD package.

simulate(self: mqt.ddsim.pyddsim.PathCircuitSimulator, shots: int) → Dict[str, int]: Simulate the circuit and return the result as a dictionary of counts.

statistics(self: mqt.ddsim.pyddsim.PathCircuitSimulator) → Dict[str, str]: Get additional statistics provided by the simulator

class ddsim.PathSimulatorConfiguration

Bases: pybind11_object

Configuration options for the Path Simulator

property bracket_size: Size of the brackets one wants to combine

property gate_cost: A list that contains the number of gates which are considered in each step

json(self: mqt.ddsim.pyddsim.PathSimulatorConfiguration) → nlohmann::json_abi_v3_11_2::basic_json<std::map, std::vector, std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, bool, long, unsigned long, double, std::allocator, nlohmann::json_abi_v3_11_2::adl_serializer, std::vector<unsigned char, std::allocator<unsigned char> >, void>

property mode: Setting the mode used for determining a simulation path

property seed: Seed for the simulator

property starting_point: Start of the alternating or gate_cost strategy

class ddsim.PathSimulatorMode

Bases: pybind11_object

Members:

sequential

pairwise_recursive

cotengra

bracket

alternating

gate_cost

alternating = <PathSimulatorMode.alternating: 3>

bracket = <PathSimulatorMode.bracket: 2>

cotengra = <PathSimulatorMode.cotengra: 4>

gate_cost = <PathSimulatorMode.gate_cost: 5>

property name

pairwise_recursive = <PathSimulatorMode.pairwise_recursive: 1>

sequential = <PathSimulatorMode.sequential: 0>

property value

class ddsim.UnitarySimulator

Bases: pybind11_object

construct(self: mqt.ddsim.pyddsim.UnitarySimulator) → None: Construct the DD representing the unitary matrix of the circuit.

get_active_matrix_node_count(self: mqt.ddsim.pyddsim.UnitarySimulator) → int: Get the number of active matrix nodes, i.e., the number of matrix DD nodes in the unique table with a non-zero reference count.

get_active_vector_node_count(self: mqt.ddsim.pyddsim.UnitarySimulator) → int: Get the number of active vector nodes, i.e., the number of vector DD nodes in the unique table with a non-zero reference count.

get_construction_time(self: mqt.ddsim.pyddsim.UnitarySimulator) → float

get_final_node_count(self: mqt.ddsim.pyddsim.UnitarySimulator) → int

get_max_matrix_node_count(self: mqt.ddsim.pyddsim.UnitarySimulator) → int: Get the maximum number of (active) matrix nodes, i.e., the maximum number of matrix DD nodes in the unique table at any point during the simulation.

get_max_node_count(self: mqt.ddsim.pyddsim.UnitarySimulator) → int

get_max_vector_node_count(self: mqt.ddsim.pyddsim.UnitarySimulator) → int: Get the maximum number of (active) vector nodes, i.e., the maximum number of vector DD nodes in the unique table at any point during the simulation.

get_mode(self: mqt.ddsim.pyddsim.UnitarySimulator) → mqt.ddsim.pyddsim.ConstructionMode

get_name(self: mqt.ddsim.pyddsim.UnitarySimulator) → str: Get the name of the simulator

get_number_of_qubits(self: mqt.ddsim.pyddsim.UnitarySimulator) → int: Get the number of qubits

get_tolerance(self: mqt.ddsim.pyddsim.UnitarySimulator) → float: Get the tolerance for the DD package.

set_tolerance(self: mqt.ddsim.pyddsim.UnitarySimulator, tol: float) → None: Set the tolerance for the DD package.

statistics(self: mqt.ddsim.pyddsim.UnitarySimulator) → Dict[str, str]: Get additional statistics provided by the simulator

ddsim.dump_tensor_network(circ: object, filename: str) → None: dump a tensor network representation of the given circuit

ddsim.get_matrix(sim: mqt.ddsim.pyddsim.UnitarySimulator, mat: numpy.ndarray[numpy.complex128]) → None