qiskit-aer 0.17.2__cp314-cp314-win_amd64.whl

qiskit_aer/jobs/aerjob.py

@@ -0,0 +1,143 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2019.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+# pylint: disable=arguments-differ
+
+"""This module implements the job class used for AerBackend objects."""
+
+import logging
+
+from qiskit.providers import JobV1 as Job
+from qiskit.providers import JobStatus, JobError
+from .utils import DEFAULT_EXECUTOR, requires_submit
+
+LOGGER = logging.getLogger(__name__)
+
+
+class AerJob(Job):
+    """AerJob class for Aer Simulators."""
+
+    def __init__(
+        self,
+        backend,
+        job_id,
+        fn,
+        circuits=None,
+        parameter_binds=None,
+        run_options=None,
+        executor=None,
+    ):
+        """Initializes the asynchronous job.
+
+        Args:
+            backend(AerBackend): the backend used to run the job.
+            job_id(str): a unique id in the context of the backend used to run the job.
+            fn(function): a callable function to execute qobj on backend.
+                This should usually be a bound :meth:`AerBackend._run()` method,
+                with the signature `(qobj: QasmQobj, job_id: str) -> Result`.
+            circuits(list of QuantumCircuit): circuits to execute.
+            parameter_binds(list): parameters for circuits.
+            run_options(dict): run_options to execute.
+            executor(ThreadPoolExecutor):
+                The executor to be used to submit the job.
+
+        Raises:
+            JobError: if no qobj and no circuits.
+        """
+        super().__init__(backend, job_id)
+        self._fn = fn
+        self._circuits = circuits
+        self._parameter_binds = parameter_binds
+        self._run_options = run_options
+        self._executor = executor or DEFAULT_EXECUTOR
+        self._future = None
+
+    def submit(self):
+        """Submit the job to the backend for execution.
+
+        Raises:
+            QobjValidationError: if the JSON serialization of the Qobj passed
+            during construction does not validate against the Qobj schema.
+            JobError: if trying to re-submit the job.
+        """
+        if self._future is not None:
+            raise JobError("Aer job has already been submitted.")
+        self._future = self._executor.submit(
+            self._fn, self._circuits, self._parameter_binds, self._run_options, self._job_id
+        )
+
+    @requires_submit
+    def result(self, timeout=None):
+        # pylint: disable=arguments-differ
+        """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
+
+        Args:
+            timeout (float): number of seconds to wait for results.
+
+        Returns:
+            qiskit.Result: Result object
+
+        Raises:
+            concurrent.futures.TimeoutError: if timeout occurred.
+            concurrent.futures.CancelledError: if job cancelled before completed.
+        """
+        return self._future.result(timeout=timeout)
+
+    @requires_submit
+    def cancel(self):
+        """Attempt to cancel the job."""
+        return self._future.cancel()
+
+    @requires_submit
+    def status(self):
+        """Gets the status of the job by querying the Python's future
+
+        Returns:
+            JobStatus: The current JobStatus
+
+        Raises:
+            JobError: If the future is in unexpected state
+            concurrent.futures.TimeoutError: if timeout occurred.
+        """
+        # The order is important here
+        if self._future.running():
+            _status = JobStatus.RUNNING
+        elif self._future.cancelled():
+            _status = JobStatus.CANCELLED
+        elif self._future.done():
+            _status = JobStatus.DONE if self._future.exception() is None else JobStatus.ERROR
+        else:
+            # Note: There is an undocumented Future state: PENDING, that seems to show up when
+            # the job is enqueued, waiting for someone to pick it up. We need to deal with this
+            # state but there's no public API for it, so we are assuming that if the job is not
+            # in any of the previous states, is PENDING, ergo INITIALIZING for us.
+            _status = JobStatus.INITIALIZING
+        return _status
+
+    def backend(self):
+        """Return the instance of the backend used for this job."""
+        return self._backend
+
+    def circuits(self):
+        """Return the list of QuantumCircuit submitted for this job.
+
+        Returns:
+            list of QuantumCircuit: the list of QuantumCircuit submitted for this job.
+        """
+        return self._circuits
+
+    def executor(self):
+        """Return the executor for this job"""
+        return self._executor

qiskit_aer/jobs/utils.py

@@ -0,0 +1,66 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2017, 2019.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+
+"""Utility functions for Aer job management."""
+from functools import singledispatch, update_wrapper, wraps
+from concurrent.futures import ThreadPoolExecutor
+
+from qiskit.providers import JobError
+
+DEFAULT_EXECUTOR = ThreadPoolExecutor(max_workers=1)
+
+
+def requires_submit(func):
+    """
+    Decorator to ensure that a submit has been performed before
+    calling the method.
+
+    Args:
+        func (callable): test function to be decorated.
+
+    Returns:
+        callable: the decorated function.
+    """
+
+    @wraps(func)
+    def _wrapper(self, *args, **kwargs):
+        if self._future is None:
+            raise JobError("Job not submitted yet!. You have to .submit() first!")
+        return func(self, *args, **kwargs)
+
+    return _wrapper
+
+
+def methdispatch(func):
+    """
+    Returns a wrapper function that selects which registered function
+    to call based on the type of args[2]
+    """
+    dispatcher = singledispatch(func)
+
+    def wrapper(*args, **kw):
+        return dispatcher.dispatch(args[2].__class__)(*args, **kw)
+
+    wrapper.register = dispatcher.register
+    update_wrapper(wrapper, func)
+    return wrapper
+
+
+def _check_custom_instruction(experiments, optypes=None):
+    """Return True if circuits contain instructions that cant be split"""
+    # Check via optype list if available
+    if optypes is not None:
+        # Optypes store class names as strings
+        return any({"SaveData"}.intersection(optype) for optype in optypes)
+
+    # Otherwise iterate over instruction names
+    return any("save_" in inst.name for exp in experiments for inst in exp.instructions)

qiskit_aer/library/__init__.py

@@ -0,0 +1,204 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+=========================================================
+Instruction Library (:mod:`qiskit_aer.library`)
+=========================================================
+
+.. currentmodule:: qiskit_aer.library
+
+This library contains custom qiskit :class:`~qiskit.QuantumCircuit`
+:class:`~qiskit.circuit.Instruction` subclasses that can be used
+with the Aer circuit simulator backends.
+
+Setting a Custom Simulator State
+================================
+
+The following instruction classes can be used to set the specific
+simulator methods to a custom state. Note that these instructions
+are only valid when applied to all qubits in a circuit. Applying
+to a subset of qubits will raise an exception during execution.
+
+Instruction Classes
+-------------------
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    SetStatevector
+    SetDensityMatrix
+    SetStabilizer
+    SetSuperOp
+    SetUnitary
+    SetMatrixProductState
+
+QuantumCircuit Methods
+----------------------
+
+The set instructions can also be added to circuits by using the
+following ``QuantumCircuit`` methods which are patched when importing Aer.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    set_statevector
+    set_density_matrix
+    set_stabilizer
+    set_unitary
+    set_superop
+    set_matrix_product_state
+
+
+Saving Simulator Data
+=====================
+
+Simulator State Save Instruction Classes
+----------------------------------------
+
+The following instructions can be used to save the state of the simulator
+into the returned result object. The :class:`SaveState` instruction will
+automatically select the format based on the simulation method (eg.
+:class:`SaveStatevector` for statevector method, :class:`SaveDensityMatrix`
+for density matrix method etc.).
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    SaveState
+    SaveStatevector
+    SaveStatevectorDict
+    SaveDensityMatrix
+    SaveMatrixProductState
+    SaveClifford
+    SaveStabilizer
+    SaveSuperOp
+    SaveUnitary
+
+.. note::
+    The :class:`SaveDensityMatrix` instruction can be used to save the
+    reduced densit matrix of a subset of qubits for supported simulation
+    methods, however all other save state instructions must be applied
+    to all qubits in a run circuit.
+
+.. note::
+    The :class:`~qiskit_aer.StatevectorSimulator` (and
+    :class:`~qiskit_aer.UnitarySimulator`) backend automatically
+    append every run circuit with the a :func:`SaveStatevector``
+    (:func:`SaveUnitary``) instruction using the default label. Hence adding
+    any additional save instructions of that type will require specifying a
+    custom label for those instructions.
+
+Simulator Derived Data Save Instruction Classes
+-----------------------------------------------
+
+The following classes can be used to directly save data derived from the
+simulator state to the returned result object. One some are compatible
+with certain simulation methods.
+
+For convenience the save instructions can be accessed using
+custom ``QuantumCircuit`` methods
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    SaveExpectationValue
+    SaveExpectationValueVariance
+    SaveProbabilities
+    SaveProbabilitiesDict
+    SaveAmplitudes
+    SaveAmplitudesSquared
+
+.. note ::
+    When saving pershot data by using the ``pershot=True`` kwarg
+    in the above instructions, the resulting list may only contain
+    a single value rather than the number of shots. This
+    happens when a run circuit supports measurement sampling because
+    it is either
+
+    1. An ideal simulation with all measurements at the end.
+
+    2. A noisy simulation using the density matrix method with all
+    measurements at the end.
+
+    In both these cases only a single shot is actually simulated and
+    measurement samples for all shots are calculated from the final
+    state.
+
+QuantumCircuit Methods
+----------------------
+
+The save instructions can also be added to circuits by using the
+following ``QuantumCircuit`` methods which are patched when importing Aer.
+
+.. note ::
+    Each save method has a default label for accessing from the
+    circuit result data, however duplicate labels in results will result
+    in an exception being raised. If you use more than 1 instance of a
+    specific save instruction you must set a custom label for the
+    additional instructions.
+
+.. autosummary::
+    :toctree: ../stubs/
+
+    save_amplitudes
+    save_amplitudes_squared
+    save_clifford
+    save_density_matrix
+    save_expectation_value
+    save_expectation_value_variance
+    save_matrix_product_state
+    save_probabilities
+    save_probabilities_dict
+    save_stabilizer
+    save_state
+    save_statevector
+    save_statevector_dict
+    save_superop
+    save_unitary
+
+Method Compatibility
+====================
+
+The following table summarizes which instructions are compatible with
+which simulation methods
+
+.. csv-table::
+    :file: instructions_table.csv
+    :header-rows: 1
+"""
+
+__all__ = [
+    "SaveAmplitudes",
+    "SaveAmplitudesSquared",
+    "SaveClifford",
+    "SaveDensityMatrix",
+    "SaveExpectationValue",
+    "SaveExpectationValueVariance",
+    "SaveMatrixProductState",
+    "SaveProbabilities",
+    "SaveProbabilitiesDict",
+    "SaveStabilizer",
+    "SaveState",
+    "SaveStatevector",
+    "SaveStatevectorDict",
+    "SaveSuperOp",
+    "SaveUnitary",
+    "SetDensityMatrix",
+    "SetStabilizer",
+    "SetStatevector",
+    "SetSuperOp",
+    "SetUnitary",
+    "SetMatrixProductState",
+]
+
+from .save_instructions import *
+from .set_instructions import *

qiskit_aer/library/control_flow_instructions/__init__.py

@@ -0,0 +1,16 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""Instructions to support control-flow for the Aer simulator"""
+
+from .jump import AerJump
+from .mark import AerMark
+from .store import AerStore

qiskit_aer/library/control_flow_instructions/jump.py

@@ -0,0 +1,47 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+Simulator instruction to set a program counter
+"""
+
+from qiskit.circuit import Instruction
+from qiskit.circuit.classical.expr import Expr
+
+
+class AerJump(Instruction):
+    """
+    Jump instruction
+
+    This instruction sets a program counter to specified mark instruction.
+    """
+
+    _directive = True
+
+    def __init__(self, jump_to, num_qubits, num_clbits=0):
+        super().__init__("jump", num_qubits, num_clbits, [jump_to])
+        self.condition_expr = None
+        self.condition = None
+
+    def set_conditional(self, cond):
+        """Set condition to perform this jump instruction.
+
+        Args:
+            cond (Expr or tuple): `Expr` to call `eval_bool` or tuple for `c_if`
+
+        Returns:
+            AerJump: jump instruction added specified condition
+        """
+        if isinstance(cond, Expr):
+            self.condition_expr = cond
+        else:
+            self.condition = cond
+        return self

qiskit_aer/library/control_flow_instructions/mark.py

@@ -0,0 +1,30 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+Simulator instruction to set a program counter
+"""
+
+from qiskit.circuit import Instruction
+
+
+class AerMark(Instruction):
+    """
+    Mark instruction
+
+    This instruction is a destination of jump instruction.
+    Conditional is not allowed in Aer controller.
+    """
+
+    _directive = True
+
+    def __init__(self, name, num_qubits, num_clbits=0):
+        super().__init__("mark", num_qubits, num_clbits, [name])

qiskit_aer/library/control_flow_instructions/store.py

@@ -0,0 +1,29 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+Simulator instruction to set a program counter
+"""
+
+from qiskit.circuit import Instruction
+
+
+class AerStore(Instruction):
+    """
+    Store instruction for Aer to work around transpilation issue
+    of qiskit.circuit.Store
+    """
+
+    _directive = True
+
+    def __init__(self, num_qubits, num_clbits, store):
+        super().__init__("aer_store", num_qubits, num_clbits, [store.lvalue, store.rvalue])
+        self.store = store

qiskit_aer/library/default_qubits.py

@@ -0,0 +1,44 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""
+Helper function
+"""
+
+from qiskit.circuit import QuantumRegister
+
+
+def default_qubits(circuit, qubits=None):
+    """Helper method to return list of qubits.
+
+    Args:
+        circuit (QuantumCircuit): a quantum circuit.
+        qubits (list or QuantumRegister): Optional, qubits argument,
+            If None the returned list will be all qubits in the circuit.
+            [Default: None]
+
+    Raises:
+        ValueError: if default qubits fails.
+
+    Returns:
+        list: qubits list.
+    """
+    # Convert label to string for backwards compatibility
+    # If no qubits are specified we add all qubits so it acts as a barrier
+    # This is needed for full register snapshots like statevector
+    if isinstance(qubits, QuantumRegister):
+        qubits = qubits[:]
+    if qubits is None:
+        qubits = list(circuit.qubits)
+        if len(qubits) == 0:
+            raise ValueError("no qubits for snapshot")
+
+    return qubits

qiskit_aer/library/instructions_table.csv

@@ -0,0 +1,21 @@
+Instruction,Automatic,Statevector,Density Matrix,MPS,Stabilizer,Ext. Stabilizer,Unitary,SuperOp
+:class:`SaveAmplitudes`,✔,✔,✘,✔,✘,✘,✘,✘
+:class:`SaveAmplitudesSquared`,✔,✔,✔,✔,✔,✘,✘,✘
+:class:`SaveClifford`,✔,✘,✘,✘,✔,✘,✘,✘
+:class:`SaveDensityMatrix`,✔,✔,✔,✔,✘,✘,✘,✘
+:class:`SaveExpectationValue`,✔,✔,✔,✔,✔,✘,✘,✘
+:class:`SaveExpectationValueVariance`,✔,✔,✔,✔,✔,✘,✘,✘
+:class:`SaveMatrixProductState`,✘,✘,✘,✔,✘,✘,✘,✘
+:class:`SaveProbabilities`,✔,✔,✔,✔,✔,✘,✘,✘
+:class:`SaveProbabilitiesDict`,✔,✔,✔,✔,✔,✘,✘,✘
+:class:`SaveStabilizer`,✔,✘,✘,✘,✔,✘,✘,✘
+:class:`SaveState`,✔,✔,✔,✔,✔,✔,✔,✔
+:class:`SaveStatevector`,✔,✔,✘,✔,✘,✔,✘,✘
+:class:`SaveStatevectorDict`,✔,✔,✘,✘,✘,✘,✘,✘
+:class:`SaveSuperOp`,✘,✘,✘,✘,✘,✘,✘,✔
+:class:`SaveUnitary`,✘,✘,✘,✘,✘,✘,✔,✘
+:class:`SetDensityMatrix`,✔,✘,✔,✘,✘,✘,✘,✘
+:class:`SetStabilizer`,✔,✘,✘,✘,✔,✘,✘,✘
+:class:`SetStatevector`,✔,✔,✘,✘,✘,✘,✘,✘
+:class:`SetUnitary`,✘,✘,✘,✘,✘,✘,✔,✘
+,,,,,,,,

qiskit_aer/library/save_instructions/__init__.py

@@ -0,0 +1,44 @@
+# This code is part of Qiskit.
+#
+# (C) Copyright IBM 2018, 2021.
+#
+# This code is licensed under the Apache License, Version 2.0. You may
+# obtain a copy of this license in the LICENSE.txt file in the root directory
+# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+#
+# Any modifications or derivative works of this code must retain this
+# copyright notice, and modified files need to carry a notice indicating
+# that they have been altered from the originals.
+"""Save directive instructions for the Aer simulator"""
+
+from .save_state import SaveState, save_state
+from .save_expectation_value import (
+    SaveExpectationValue,
+    save_expectation_value,
+    SaveExpectationValueVariance,
+    save_expectation_value_variance,
+)
+from .save_probabilities import (
+    SaveProbabilities,
+    save_probabilities,
+    SaveProbabilitiesDict,
+    save_probabilities_dict,
+)
+from .save_statevector import (
+    SaveStatevector,
+    save_statevector,
+    SaveStatevectorDict,
+    save_statevector_dict,
+)
+from .save_density_matrix import SaveDensityMatrix, save_density_matrix
+from .save_amplitudes import (
+    SaveAmplitudes,
+    save_amplitudes,
+    SaveAmplitudesSquared,
+    save_amplitudes_squared,
+)
+from .save_stabilizer import SaveStabilizer, save_stabilizer
+from .save_clifford import SaveClifford, save_clifford
+from .save_unitary import SaveUnitary, save_unitary
+from .save_matrix_product_state import SaveMatrixProductState, save_matrix_product_state
+from .save_superop import SaveSuperOp, save_superop