:py:mod:`pygsti.tools.internalgates` ==================================== .. py:module:: pygsti.tools.internalgates .. autoapi-nested-parse:: The standard unitaries and gate names, used internal compilers and short-hand model init Module Contents --------------- Classes ~~~~~~~ .. autoapisummary:: pygsti.tools.internalgates.Gzr pygsti.tools.internalgates.Gczr pygsti.tools.internalgates.Gu3 Functions ~~~~~~~~~ .. autoapisummary:: pygsti.tools.internalgates.internal_gate_unitaries pygsti.tools.internalgates.is_gate_this_standard_unitary pygsti.tools.internalgates.is_gate_pauli_equivalent_to_this_standard_unitary pygsti.tools.internalgates.standard_gatename_unitaries pygsti.tools.internalgates.unitary_to_standard_gatename pygsti.tools.internalgates.standard_gatenames_stim_conversions pygsti.tools.internalgates.standard_gatenames_cirq_conversions pygsti.tools.internalgates.cirq_gatenames_standard_conversions pygsti.tools.internalgates.standard_gatenames_quil_conversions pygsti.tools.internalgates.standard_gatenames_chp_conversions pygsti.tools.internalgates.standard_gatenames_openqasm_conversions pygsti.tools.internalgates.qiskit_gatenames_standard_conversions pygsti.tools.internalgates.standard_gatenames_qiskit_conversions pygsti.tools.internalgates.qasm_u3 .. py:class:: Gzr Bases: :py:obj:`pygsti.baseobjs.unitarygatefunction.UnitaryGateFunction` A convenient base class for building serializable "functions" for unitary gate matrices. Subclasses that don't need to initialize any attributes other than `shape` only need to impliement the `__call__` method and declare their shape as either a class or instance variable. .. py:attribute:: shape :value: '(2, 2)' .. py:class:: Gczr Bases: :py:obj:`pygsti.baseobjs.unitarygatefunction.UnitaryGateFunction` A convenient base class for building serializable "functions" for unitary gate matrices. Subclasses that don't need to initialize any attributes other than `shape` only need to impliement the `__call__` method and declare their shape as either a class or instance variable. .. py:attribute:: shape :value: '(4, 4)' .. py:class:: Gu3 Bases: :py:obj:`pygsti.baseobjs.unitarygatefunction.UnitaryGateFunction` A convenient base class for building serializable "functions" for unitary gate matrices. Subclasses that don't need to initialize any attributes other than `shape` only need to impliement the `__call__` method and declare their shape as either a class or instance variable. .. py:attribute:: shape :value: '(2, 2)' .. py:function:: internal_gate_unitaries() The unitaries for the *internally* defined gates. These are gates that are used in some circuit-compilation methods internally (e.g., compiling multi-qubit Clifford gates), and under normal usage of functions/methods that internally make use of these labels, circuits containing these gate names will not be returned to the user -- they are first converted into gates with user-defined names and actions (with names starting with 'G'). Note that some unitaries in this dict do not have unique names. E.g., the key 'I' is the 1-qubit identity unitary, but so is 'C0' (which refers to the zeroth element of the 1-qubit Clifford group). Returns ------- dict of numpy.ndarray objects that are complex, unitary matrices. .. py:function:: is_gate_this_standard_unitary(gate_unitary, standard_gate_name) Whether a unitary is, up to a phase, the standard gate specified by the name `standard_gate_name`. The correspondence between the standard names and unitaries is w.r.t the internally-used gatenames (see internal_gate_unitaries()). For example, one use of this function is to check whether some gate specifed by a user with the name 'Ghadamard' is the Hadamard gate, denoted internally by 'H'. Parameters ---------- gate_unitary : complex np.array The unitary to test. standard_gate_name : str The standard gatename to check whether the unitary `gate_unitary` is (e.g., 'CNOT'). Returns ------- bool True if the `gate_unitary` is, up to phase, the unitary specified `standard_gate_name`. False otherwise. .. py:function:: is_gate_pauli_equivalent_to_this_standard_unitary(gate_unitary, standard_gate_name) Whether a unitary is the standard gate specified by `standard_gate_name`. This equivalence is tested up to pre- and post-multiplication by some Pauli and up to a phase, The correspondence between the standard names and unitaries is w.r.t the internally-used gatenames (see internal_gate_unitaries()). Currently only supported for Clifford gates. Parameters ---------- gate_unitary : complex np.array The unitary to test. standard_gate_name : str The standard gatename to check whether the unitary `gate_unitary` is (e.g., 'CNOT'). Returns ------- bool True if the `gate_unitary` is, up to phase and Pauli-multiplication, the unitary specified `standard_gate_name`. False otherwise. .. py:function:: standard_gatename_unitaries() Constructs and returns a dictionary of unitary matrices describing the action of "standard" gates. These gates (the keys of the returned dictionary) are: * Clifford Gates: * 'Gi' : the 1Q idle operation. * 'Gxpi','Gypi','Gzpi' : 1Q pi rotations around X, Y and Z. * 'Gxpi2','Gypi2','Gzpi2' : 1Q pi/2 rotations around X, Y and Z. * 'Gxmpi2','Gympi2','Gzmpi2' : 1Q -pi/2 rotations around X, Y and Z. * 'Gh' : Hadamard. * 'Gp', 'Gpdag' : phase and inverse phase (an alternative notation/name for Gzpi and Gzmpi2). * 'Gci' where `i = 0, 1, ..., 23` : the 24 1-qubit Clifford gates (all the gates above are included as one of these). * 'Gcphase','Gcnot','Gswap', 'Giswap' : standard 2Q gates. * 'Gsqrtiswap' : square-root of ISWAP gate, used in some superconducting qubit platforms. * 'Gxx', 'Gzz' : MS-style parity gates * 'Gcres', 'Gecres' : Cross-resonance and echoed cross-resonance gates. Native gate operations common on transmon systems (including IBM). * 'Gecr' : alternative name for the echoed cross-resonance gate, matching OpenQASM / IBM conventions. * Non-Clifford gates: * 'Gt', 'Gtdag' : the T and inverse T gates (T is a Z rotation by pi/4). * 'Gzr' : a parameterized gate that is a Z rotation by an angle, where when the angle = pi then it equals Z. * 'Gn' : N gate, pi/2 rotation about the (np.sqrt(3)/2, 0, -1/2) axis of the Bloch sphere, native gate in some spin qubit systems. * 'Gu3' : parameterized gate that can encode any single-qubit rotation with three parameters (theta, phi, lambda). Mostly, pyGSTi does not assume that a gate with one of these names is indeed the unitary specified here. Instead, these names are intended as short-hand for defining ProcessorSpecs and n-qubit models. Moreover, when these names are used then conversion of circuits to QUIL or QISKIT is particular convenient, and does not require the user to specify the syntax conversion. Returns ------- dict of numpy.ndarray objects. .. py:function:: unitary_to_standard_gatename(unitary, up_to_phase=False, return_phase=False) Looks up and returns the standard gate name for a unitary gate matrix, if one exists. Parameters ---------- unitary : complex np.array The unitary to convert. up_to_phase : bool, optional (default False) If true then after checking if the unitary is exactly equivalent to a built-in one, this then checks if the input unitary is equal to to a built-in one up to a global phase. return_phase : bool, optional (default False) If true, and up_to_phase is true, then if a unitary is equivalent up to a global phase to a built-in one, we return that phase (i.e. the phase the built-in one would need to be multiplied by). Returns ------- str or None If `gate_unitary` matches a standard gate, the standard name of this gate (a key in the dictionary given by :func:`standard_gatename_unitaries`). `None` otherwise. .. py:function:: standard_gatenames_stim_conversions() A dictionary converting the gates with standard names to stim tableus for these gates. Currently is only capable of converting clifford gates, no capability for T gates TODO: Add all standard clifford gate names in Returns ------- A dict mapping string to tableu .. py:function:: standard_gatenames_cirq_conversions() A dictionary converting the gates with standard names to the cirq names for these gates. See :func:`standard_gatename_unitaries`. By default, an idle operation will not be converted to a gate. If you want an idle to be converted to a `cirq.WaitGate`, you will have to modify this dictionary. Note that throughout pyGSTi the standard gatenames (e.g., 'Gh' for Hadamard) are not enforced to correspond to the expected unitaries. So, if the user as, say, defined 'Gh' to be something other than the Hadamard gate this conversion dictionary will be incorrect. Currently there are some standard gate names with no conversion to cirq. Returns ------- std_gatenames_to_cirq dict mapping strings corresponding to standard built-in pyGSTi names to corresponding cirq operation objects. .. py:function:: cirq_gatenames_standard_conversions() A dictionary converting cirq gates to built-in pyGSTi names for these gates. Does not currently support conversion of all cirq gate types. .. py:function:: standard_gatenames_quil_conversions() A dictionary converting the gates with standard names to the QUIL names for these gates. See :func:`standard_gatename_unitaries`. Note that throughout pyGSTi the standard gatenames (e.g., 'Gh' for Hadamard) are not enforced to correspond to the expected unitaries. So, if the user as, say, defined 'Gh' to be something other than the Hadamard gate this conversion dictionary will be incorrect. Currently there are some standard gate names with no conversion to quil. Returns ------- dict mapping strings to strings. .. py:function:: standard_gatenames_chp_conversions() A dictionary converting the gates with standard names to CHP native operations. See :func:`standard_gatename_unitaries`. Note that the native operations are assumed to act on qubit 0 or qubits 0 and 1, depending on whether it is a one-qubit or two-qubit operation. It is recommended to use ComposedOp and EmbeddedOp to get compositions/different target qubits for CHP operations. Note that throughout pyGSTi the standard gatenames (e.g., 'Gh' for Hadamard) are not enforced to correspond to the expected unitaries. So, if the user as, say, defined 'Gh' to be something other than the Hadamard gate this conversion dictionary will be incorrect. Returns ------- dict mapping strings to string .. py:function:: standard_gatenames_openqasm_conversions(version='u3') A dictionary converting the gates with standard names to the QASM names for these gates. See :func:`standard_gatename_unitaries`. Note that throughout pyGSTi the standard gatenames (e.g., 'Gh' for Hadamard) are not enforced to correspond to the expected unitaries. So, if the user has, say, defined 'Gh' to be something other than the Hadamard gate this conversion dictionary will be incorrect. Parameters ---------- version : string, optional Either 'u3' or 'x-sx-rz'. Specifies the naming convention for the QASM gates. With 'u3', all single-qubit gates are specified in terms of the 'u3' gate, used by IBM and QisKit until ~2021 (see the qasm_u3 function). With 'x-sx-rz', all single-gates are specified in terms of 'x' (an x pi rotation), 'sx' (an x pi/2 rotation) and 'rz' (a parameterized rotation around z by an angle theta). Returns ------- dict mapping strings (representing pyGSTi standard gate names) to list of strings (representing QASM gate names). dict mapping strings (representing pyGSTi standard gate names) to functions that map the parameters of a pyGSTi gate to a string to be combined with the QASM name to specify the specific gate, in QASM. .. py:function:: qiskit_gatenames_standard_conversions() -> Dict[str, List[str, bool]] A dictionary converting Qiskit gates (based on Instruction.name) to built-in pyGSTi names for these gates. Additional flag in dict value indicates if the gate has params. Does not currently support conversion of all qiskit gate types. Returns --------- Dictionary mapping qiskit gate names to pyGSTi gate names and a flag for whether or not the gate has parameters. .. py:function:: standard_gatenames_qiskit_conversions() -> Dict[str, Tuple[qiskit.circuit.Instruction, str, bool]] A dictionary converting the gates with standard names to the Qiskit gates/names. See :func:`standard_gatename_unitaries`. Note that throughout pyGSTi the standard gatenames (e.g., 'Gh' for Hadamard) are not enforced to correspond to the expected unitaries. So, if the user as, say, defined 'Gh' to be something other than the Hadamard gate this conversion dictionary will be incorrect. Later versions of qiskit may be able to utilize an accelerated circuit append. Returns ------- dict[str, tuple[qiskit.circuit.Instruction, str, bool]] Maps pyGSTi gatenames to tuples of the qiskit gate class, gatename, and a boolean that indicates whether the append of the gate to the circuit can be accelerated in a later version of qiskit. .. py:function:: qasm_u3(theta, phi, lamb, output='unitary') The u3 1-qubit gate of QASM, returned as a unitary. if output = 'unitary' and as a processmatrix in the Pauli basis if out = 'superoperator.' Parameters ---------- theta : float The theta parameter of the u3 gate. phi : float The phi parameter of the u3 gate. lamb : float The lambda parameter of the u3 gate. output : {'unitary', 'superoperator'} Whether the returned value is a unitary matrix or the Pauli-transfer-matrix superoperator representing that unitary action. Returns ------- numpy.ndarray