Config¶

`trueq.Config`	Contains the relevant configuration of a system, including which gates are available to be run, how many systems there are and the dimension of the individual systems.
`trueq.config.FixedRotation`	A fixed unitary rotation.
`trueq.config.GateFactory`	Constructs new `NativeGate`s according to a functional description.
`trueq.config.InvolvingRule`	A dictionary containing allowable sets of systems.
`trueq.config.Layer`	Parent class for `Rotation` and `FixedRotation`.
`trueq.config.Rotation`	A representation of a rotation of the form \(exp^{-i \cdot G \cdot \text{param}}\) for some Hermitian matrix \(G\).
`trueq.config.factory.parse_func`	Creates a python function from a string containing numbers, variables, and standard math functions.

Config¶

class trueq.Config(conf)¶

Contains the relevant configuration of a system, including which gates are available to be run, how many systems there are and the dimension of the individual systems. See documentation for description of construction of the configuration file.

A minimal example .yaml file is presented below. The YAML below defines a four-qubit system, where the gates available are:

Arbitrary \(X(\phi)\) rotations, which cannot be applied while the neighboring qubits are in use.
Arbitrary \(Z(\phi)\) rotations, which can be applied in parallel with anything
CNOT, which can never be used in parallel with any other gate.

Note that gates can either be defined by the Hamiltonian or Matrix keyword, but never both.

Since we allow arbitrary functional definition of gates using functions that can be parsed using parse_func, the Config object can be used to generate new NativeGate objects on the fly based upon the variables defined in the YAML.

Here we use a convenience method to create a basic config sufficient for most uses:

import trueq as tq
config = tq.Config.basic(name="Example", entangler=tq.Gate.cnot, mode="ZXZXZ")

# we can access the GateFactory objects via the factories attribute.
config.factories

# for ease of use, individual factories are available as attributes of the config
config.Z

# lets make an Z90 gate using this definition:
config.Z(phi=90)

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

These configs can be saved to a YAML file and loaded back in the future. This facilitates including topology and gate restrictions by specifying Involving keys in the YAML.

import trueq as tq

file_contents = '''
    Name: Example
    Dimension: 2
    Mode: ZXZXZ
    Gate X:
       Hamiltonian:
         - ['X', phi]
       Involving:
         (0,) : (1, 2)
         (1,) : (0, 2)
         (2,) : (1, 3)
         (3,) : (2,)
    Gate Z:
       Hamiltonian:
         - ['Z', phi]
       Involving:
         (0,) : ()
         (1,) : ()
         (2,) : ()
         (3,) : ()
    Gate CNOT:
       Matrix:
         - [1, 0, 0, 0]
         - [0, 1, 0, 0]
         - [0, 0, 0, 1]
         - [0, 0, 1, 0]
       Involving:
         (0, 1) : (2, 3)
         (1, 2) : (0, 3)
         (2, 3) : (0, 1)'''

# Configs can be loaded from either a filename, or the contents of a file:
tq.Config(file_contents)

Name: Example
Mode: ZXZXZ
Dimension: 2
Gate X:
  Hamiltonian:
  - [X, phi]
  Involving: {'(0,)': '(1, 2)', '(1,)': '(0, 2)', '(2,)': '(1, 3)', '(3,)': '(2,)'}
Gate Z:
  Hamiltonian:
  - [Z, phi]
  Involving: {'(0,)': (), '(1,)': (), '(2,)': (), '(3,)': ()}
Gate CNOT:
  Matrix:
  - ['1', '0', '0', '0']
  - ['0', '1', '0', '0']
  - ['0', '0', '0', '1']
  - ['0', '0', '1', '0']
  Involving: {'(0, 1)': '(2, 3)', '(1, 2)': '(0, 3)', '(2, 3)': '(0, 1)'}

The above config contains information about physical limitations of the gates. This information is encoded in the Involving key inside of the gate definitions. This involving key is a dictionary whose keys are the sets of systems on which the gate can act. In the YAML example above, the X gate can be applied to any of qubits 0, 1, 2, 3.

The values of the dictionary list which systems cannot have any gates applied to them while the gate acts on the systems specified by the key. For example, when the X gate in the above config is run on qubit 0, no other gates may be applied in parallel on either qubit 1 or 2.

This Involving information is used during compilation to ensure that circuits are compatable with the physical limitations of the hardware.

Parameters: conf (str) – Path to a configuration YAML file, or a parsed YAML file as a string.

static basic(name, entangler=Gate.cx, mode='ZXZXZ', dim=2)¶

Create a new Config object containing a fixed entangling gate and the Pauli rotation gates required to decompose single-qubit gates into the specified mode.

Parameters

name (str) – Name of the configuration.
entangler (Gate) – The entangling gate.
mode (str) – The single qubit decomposition mode, defaults to 'ZXZXZ'
dim (int) – The dimension of computational system, defaults to 2 (qubits)

Return type

Config

static from_params(name, mode='ZXZXZ', dim=2, factories=None)¶

Create a new Config object from the given parameters; an alternate constructor that bypasses the YAML input.

Parameters

name (str) – Name of the configuration.
mode (str) – The single qubit decomposition mode, defaults to 'ZXZXZ'
dim (int) – The dimension of computational system, defaults to 2 (qubits)
factories (Iterable) – An iterable of GateFactory objects.

Return type

Config

subset(labels=None, names=None, strict=True)¶

Create a new Config object containing a subset of the gate factories present in this configuration, and each of whose involving rules has been trimmed based on the given labels.

import trueq as tq

# create an basic config using cz gates as the entangler
config = tq.Config.basic("example", entangler=tq.Gate.cz)

# make a new config acting only on qubits 2, 3 restricted to gates z, cz
config.subset(labels=[2, 3], names=["z", "cz"])

Name: example
Mode: ZXZXZ
Dimension: 2
Gate cz:
  Matrix:
  - [(1+0j), 0j, 0j, 0j]
  - [0j, (1+0j), 0j, 0j]
  - [0j, 0j, (1+0j), 0j]
  - [0j, 0j, 0j, (-1+0j)]
  Involving: {}

Parameters

labels (Iterable) – The labels to be present in the new config. If None, no filtering based on labels is done.
names (Iterable) – A list of gate factory names to keep. If None, no filtering based on factory names is done.
strict (bool) – Whether to filter gate factories based on being a strict subset of the given labels (True), or based on overlapping with labels at all (False).

Return type

Config

static make_config(multiqubit_fact, parameters, name, mode='ZXZ')¶

A convenience method for making a configuration file for a quantum system with fixed multi-qubit gates with nonhomogenous parameters.

import trueq as tq
iSwapLike_mat = [[1, 0, 0, 0],
                 [0, 0, -1j, 0],
                 [0, -1j, 0, 0],
                 [0, 0, 0, "exp(-1j * phi / 180)"],
                 ]
iSwapLike_factory = tq.config.GateFactory("iSwapLike", matrix=iSwapLike_mat)
parameters = {(0, 1): 90, (2, 3): 45}
conf = tq.Config.make_config(iSwapLike_factory, parameters, "Example")
conf.iSwapLike_0_1()

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

Parameters

multiqubit_fact (GateFactory) – A gate factory that can generate the nonhomogenous gates that can be implemented in the system.
parameters (dict) – A dictionary mapping tuples of qubit labels to parameters of the given mulit-qubit factory to be used on those particular qubits.
name (str) – The name for the resulting config file.
mode (str) – The mode used to decompose single-qubit operations.

Return type

Config

property dim¶

The dimension of systems (e.g., 2 for qubits, 3 for qutrits).

Return type: int

property mode¶

The mode by which arbitrary single-qubit gates are decomposed in the system to native gates.

Return type: str

property name¶

Name of this device configuration.

Return type: str

property connectivity¶

The connectivity graph of all multi-qubit gates in the config.

A set of frozensets which contain all multi-qubit connections defined by the factories present in the config.

Type: set

to_dict()¶

Returns a dictionary representation of the Config.

Return type: dict

to_yaml()¶

Returns a YAML representation of the Config.

Type: str

FixedRotation¶

class trueq.config.FixedRotation(mat)¶

A fixed unitary rotation.

import trueq as tq
import numpy as np
from trueq.config import FixedRotation

g = FixedRotation(tq.Gate.x.mat)
assert g.pauli_angle == ("X", 180)

Parameters: mat (numpy.array) – A Unitary matrix.

property pauli_angle¶

If this layer can be represented by a fixed rotation along a Pauli axis such as \(exp^{-i \cdot \frac{\pi}{360} \text{Pauli} \cdot \text{angle}}\), this will be a tuple (Pauli, angle), otherwise this is (None, None)

import trueq as tq
from trueq.config import FixedRotation

g = FixedRotation.from_pauli("XY", 90)
assert g.pauli_angle == ("XY", 90)

g = FixedRotation.from_pauli("Y", 11)
assert g.pauli_angle == ("Y", 11)

Type: tuple

static from_pauli(pauli, angle)¶

A convenience method to create a FixedRotation from a Pauli string.

This is the equivalent to \(exp^{-i \frac{\pi}{360} \text{pauli} \cdot \text{angle}}\).

import trueq as tq
from trueq.config import FixedRotation

gen = FixedRotation.from_pauli("XY", 90)
assert gen.pauli_angle == ("XY", 90)

gen = FixedRotation.from_pauli("Y", 11)
assert gen.pauli_angle == ("Y", 11)

Parameters

pauli (str) – A Pauli which describes the axis of the rotation.
param_name (str) – The name of the associated free parameter.
angle (float) – The angle of rotation as defined above.

property width¶

The width of the matrix returned by this layer.

Type: int

Gate Factory¶

class trueq.config.GateFactory(name, matrix=None, hamiltonian=None, involving=None, conf_name=None, parameters=None, sys_dim=2)¶

Constructs new NativeGates according to a functional description.

This is useful when you have a description of a gate such as \(X(\theta)\) which is an arbitrary rotation around the X axis by some angle \(\theta\). Either a unitary matrix definition or hamiltonian description of the gate may be provided, but not both.

Examples:

import trueq as tq
y_factory = tq.config.GateFactory(name='y', hamiltonian=[['Y', 'phi']])
y_factory(phi=90)

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

import trueq as tq
iSwapLike_mat = [[1,  0,  0,                      0],
                 [0,  0,-1j,                      0],
                 [0,-1j,  0,                      0],
                 [0,  0,  0, "exp(-1j * phi / 180)"]]
iSwap_factory = tq.config.GateFactory("iSwapLike", matrix=iSwapLike_mat)
iSwap_factory(phi=45)

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

import trueq as tq
import numpy as np
u3_factory = tq.config.GateFactory(
    name="U3Gate",
    hamiltonian=[
        ["Z", "phi * 180 / pi"],
        ["Y", "theta * 180 / pi"],
        ["Z", "lam * 180 / pi"],
    ],
    parameters=["theta", "phi", "lam"],
)

u3_factory(np.pi/2, 0, 0)

True-Q formatting will not be loaded without trusting this notebook or rerunning the affected cells. Notebooks can be marked as trusted by clicking "File -> Trust Notebook".

The U3 gate as defined by IBM, in this case the gate is defined in terms of radians in the IBM definition (note that this definition is in multiplicative order, but the above Hamiltonian definition is in time order):

\(U3(\theta, \phi, \lambda) = Z(\lambda)Y(\theta)Z(\phi)\)

This radian based definition means that there has to be a conversion constant on each of the parameters phi, theta, lam from radians to degrees. Additionally, the order of the parameters is important in the U3 definition, so the GateFactory is defined with the parameters options so that the order is recorded correctly.

Parameters

name (str) – Name of the gate operation which must be a valid identifier examples: CZ, X, CNOT.
matrix (list) – A unitary matrix description of the gate, this may include string definitions of functions which will be parsed on instantiation and converted into numerical representations which are equivalent to the Hamiltonian description. The matrix definition must be writable as a product of generator matrices \(\prod_i e^{i A_i \cdot t_i}\), where each parameter \(t_i\) appear only once. If this requirement is too restrictive, the gate may be defined more generally using the Hamiltonian.
hamiltonian (list) – A hamiltonian generator description of the gate, defined above. The values may be strings which are parsable into values. The list of provided Hamiltonians will be applied in time ordering, and are not required to commute.
involving (dict) – A dictionary describing the limitations of the gate, see Config description for a more in-depth description.
conf_name (str) – Used for correctly generating repr, used primarily by Config.
parameters (list) – An optional list of the parameters present in the definition, this allows for the preferred ordering of the parameters to be specified. If None is provided, then parameter names are inferred from the definition in a deterministic but arbitrary order.
sys_dim (int) – The dimension of the subsystem defined by this gate, defaults to 2 for qubits.

subset(labels=None, strict=True)¶

Creates a new GateFactory object with a set of involving rules that is a subset of this factory’s rules.

import trueq as tq
import numpy as np

involving = {(0, 1): (2, 3), (1, 2): (3,), (2, 3): (1,), (3, 8): ()}
factory = tq.config.GateFactory(
     name="cz", matrix=np.diag([1, 1, 1, -1]), involving=involving
)

subset = factory.subset(labels=(0, 1, 2), strict=True)
assert subset.involving.rules == {(0, 1): (2, 3), (1, 2): (3,)}
subset

GateFactory(name='cz', matrix=[[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, -1]], involving=InvolvingRule(rules={(0, 1): (2, 3), (1, 2): (3,)}, default_allow=False))

Parameters

labels (Iterable) – The labels to be present in the new config. If None, no filtering based on labels is done.
strict (bool) – Whether to filter involving labels based on being a strict subset of the given labels (True), or based on overlapping with labels at all (False).

Return type

Config

property pauli_const¶

If this factory is a simple rotation about a single Pauli axis, specifically a gate which is representable by \(exp^{-i \frac{\pi}{360} \text{pauli} \cdot \text{constant} \cdot \text{param}}\), then pauli_const is a tuple which represents the rotation, (Pauli, constant).

If the gate cannot be written in terms of a single Pauli rotation, then pauli_const is (None, None).

import trueq as tq
import numpy as np

factory = tq.config.GateFactory(name="Rz", hamiltonian=[['Z', '5 * phi']])

assert factory.pauli_const[0] == 'Z'
assert abs(factory.pauli_const[1] - 5) < 1e-10

Type: tuple

property pauli_angle¶

If this factory is a simple fixed angle rotation about a single Pauli axis which may be written as \(exp^{-i \frac{\pi}{360} \cdot \text{Pauli} \cdot \text{angle}}\), then pauli_angle is a tuple which represents the rotation, (Pauli, angle).

If the gate cannot be written in terms of a single Pauli rotation, then pauli_angle is (None, None).

import trueq as tq

factory = tq.config.GateFactory(name="Rz", hamiltonian=[['Z', '90']])
assert factory.pauli_angle == ('Z', 90)

Type: tuple

make_gate(*args, **kwargs)¶

Returns a NativeGate based upon the parameters provided.

Raises ValueError if the arguments do not match the parameters found in the description of the gate.

Note

Constructed NativeGate objects are memoized and cached based upon the kwargs.

Return type: NativeGate

property n_sys¶

The number of systems this gate factory acts on.

Type: int

property sys_dim¶

The dimension of the subsystems this gate factory acts on.

Type: int

property width¶

The width of gates produced by this factory, e.g., 2 for a single qubit, 4 for two qubits, etc.

Type: int

property parameters¶

The list of all the parameters in the functional definition of the gate.

Type: list

property n_params¶

The number of parameters in the functional definition of the gate.

Type: int

property involving¶

A specification of which systems can be involved in the gate operation.

Type: InvolvingRule

to_dict()¶

Returns a dictionary representation of the factory object.

Return type: dict

Involving Rule¶

class trueq.config.InvolvingRule(rules=None, default_allow=None)¶

A dictionary containing allowable sets of systems.

from trueq.config import InvolvingRule

# In the default case, any involving check returns as valid
rule = InvolvingRule()

(5, ) in rule,  rule[(1, 5)]

(True, ())

from trueq.config import InvolvingRule

# In the case where rules are provided, it will return the rules
# if asked specifically about the items, and nothing otherwise
rule = InvolvingRule(rules={(0,): (2, 3, 4)})

rule[(0,)], (1, ) in rule

((2, 3, 4), False)

from trueq.config import InvolvingRule

# In the case where rules are provided, and `default_allow=True`
# it will return if asked specifically about the contained items,
# and will return `True` for all other cases
rule = InvolvingRule(rules={(0,): (2, 3, 4)}, default_allow=True)

rule[(0,)], rule[(1,)]

((2, 3, 4), ())

See Config for more details on how these rules are used.

Parameters

rules (dict) – A dictionary with both keys and values being tuples of ints. The key represents allowed operations, and the values represent blocking operations that get placed on other qubits due to the key labels.
default_allow (bool | None) – Defines the behavior if a key is not present in the ruleset. If True, then if a key is not found in the rules, InvolvingRule acts as though it were present. If False, InvolvingRule raise KeyErrors. If None, then default_allow is set to True if no rules are provided, and False if rules are provided.

keys()¶

Returns the keys for given rules.

Return type: generator of tuple

values()¶

Returns the values for given rules.

Return type: generator of tuple

items()¶

Returns the key, value pairs for given rules.

Return type: generator of tuple

unordered_get(key)¶

Gets the value associated with a given key, regardless of the ordering.

This returns a list of tuples, where the tuples contain the required ordering as defined by the rules, along with the value associated with that key.

from trueq.config import InvolvingRule
rule = InvolvingRule(rules={(0, 1): (2, 3, 4)})

rule.unordered_get((1, 0))

[((0, 1), (2, 3, 4))]

This is useful when connectivity matters, but not the strict ordering of labels.

Parameters: key (tuple) – The key to fetch, must be a tuple of ints.
Return type: tuple

unordered_contains(key)¶

Determines if any permutation of the given key is present in rules.

from trueq.config import InvolvingRule
rule = InvolvingRule(rules={(0, 1): (2, 3, 4)})

rule.unordered_contains((1, 0))

True

This is useful when connectivity matters, but not the strict ordering of labels.

Parameters: key (tuple) – The key to fetch, must be a tuple of ints.
Return type: bool

Layer¶

class trueq.config.Layer¶

Parent class for Rotation and FixedRotation.

property pauli_angle¶

If this layer can be represented by a fixed rotation along a Pauli axis such as \(exp^{-i \cdot \frac{\pi}{360} \text{Pauli} \cdot \text{angle}}\), this will be a tuple (Pauli, angle), otherwise this is (None, None)

import trueq as tq
from trueq.config import FixedRotation

g = FixedRotation.from_pauli("XY", 90)
assert g.pauli_angle == ("XY", 90)

g = FixedRotation.from_pauli("Y", 11)
assert g.pauli_angle == ("Y", 11)

Type: tuple

property pauli_const¶

If this layer can be represented by a rotation along a Pauli axis such as: \(exp^{-i \frac{\pi}{360} \text{Pauli} \cdot \text{constant} \cdot \text{param}}\), this will be a tuple (Pauli, constant), otherwise this is (None, None).

import trueq as tq
import numpy as np
from trueq.config import Rotation

g = Rotation(tq.Gate.y.mat * np.pi / 360, "theta")
assert g.pauli_const == ("Y", 1)

g = Rotation.from_pauli("X", "phi", 5)
assert g.pauli_const == ("X", 5)

g = Rotation(tq.Gate.random(2).mat, "theta")
assert g.pauli_const == (None, None)

Type: tuple

abstract property width¶

The width of the matrix returned by this layer.

Type: int

Rotation¶

class trueq.config.Rotation(gen, param_name)¶

A representation of a rotation of the form \(exp^{-i \cdot G \cdot \text{param}}\) for some Hermitian matrix \(G\).

import trueq as tq
import numpy as np
from trueq.config import Rotation

g = Rotation(tq.Gate.x.mat / 2, "theta")
assert tq.Gate(g(np.pi / 2)) == tq.Gate.cliff5
assert g.pauli_const == ("X", 180 / np.pi)

Parameters

gen (numpy.array) – A Hermitian matrix to generate this rotation.
param_name (str) – The name associated with the param, e.g. theta, phi, t, etc.

property pauli_const¶

If this layer can be represented by a rotation along a Pauli axis such as: \(exp^{-i \frac{\pi}{360} \text{Pauli} \cdot \text{constant} \cdot \text{param}}\), this will be a tuple (Pauli, constant), otherwise this is (None, None).

import trueq as tq
import numpy as np
from trueq.config import Rotation

g = Rotation(tq.Gate.y.mat * np.pi / 360, "theta")
assert g.pauli_const == ("Y", 1)

g = Rotation.from_pauli("X", "phi", 5)
assert g.pauli_const == ("X", 5)

g = Rotation(tq.Gate.random(2).mat, "theta")
assert g.pauli_const == (None, None)

Type: tuple

static from_pauli(pauli, param_name, constant=1)¶

A convenience method to create a Rotation from a Pauli string.

This is the equivalent to \(exp^{-i \frac{\pi}{360} \text{pauli} \cdot \text{constant} \cdot \text{param}}\).

import trueq as tq
from trueq.config import Rotation

gen = Rotation.from_pauli("XY", "theta")
assert gen.pauli_const[0] == "XY"

gen = Rotation.from_pauli("XY", "theta", constant=10)
assert gen.pauli_const == ("XY", 10)

Parameters

pauli (str) – A Pauli which describes the axis of the rotation.
param_name (str) – The name of the associated free parameter.
constant (float) – A constant scaling term as defined above.

property width¶

The width of the matrix returned by this layer.

Type: int

Parsing functions¶

trueq.config.factory.parse_func(func_str)¶

Creates a python function from a string containing numbers, variables, and standard math functions.

from trueq.config.factory import parse_func, KNOWN_FUNCTIONS
f = parse_func('5*sin(x) + y')
print(f(x=np.pi, y=1))

# all functions in KNOWN_FUNCTIONS can be parsed
print(KNOWN_FUNCTIONS.keys())

1.0000000000000007
dict_keys(['sin', 'cos', 'tan', 'exp', 'sqrt', 'arcsin', 'arccos', 'arctan', 'round', 'ceil', 'floor', 'int', 'float', 'complex', 'pi', 'list', 'tuple', 'dict', 'set'])

Note

Parsing functions adds an overhead relative to directly calling numpy functions. The overhead is approximately a factor of 20 for simple functions.

Parameters: func_str (str) – A string describing the function to be created.

trueq.config.factory.find_parameters(func_str)¶

Find all free parameters inside the text description of a fuction using exception handling.

from trueq.config.factory import find_parameters

params = find_parameters("sin(x) + phi / 2 + theta")
assert set(params) == {"x", "phi", "theta"}

Parameters: func_str (str) – A string describing the function.

Pre-Defined factories¶

factory.u1_factory = GateFactory(name='U1Gate', hamiltonian=[['Z', 'lam * 180 / pi']])¶

factory.u2_factory = GateFactory(name='U2Gate', hamiltonian=[['Z', 'phi * 180 / pi'], ['Y', '90'], ['Z', 'lam * 180 / pi']])¶

factory.u3_factory = GateFactory(name='U3Gate', hamiltonian=[['Z', 'phi * 180 / pi'], ['Y', 'theta * 180 / pi'], ['Z', 'lam * 180 / pi']])¶

factory.phasedXPow_factory = GateFactory(name='PhasedXPow', hamiltonian=[['Z', 'lam * 180'], ['X', 'theta * 180'], ['Z', '-lam * 180']])¶

factory.r_factory = GateFactory(name='R', hamiltonian=[['Z', '-theta'], ['X', '90'], ['Z', 'theta']])¶

factory.ms_factory = GateFactory(name='MS', hamiltonian=[['XX', 'theta']])¶

factory.fsim_factory = GateFactory(name='FSim', matrix=[[1, 0, 0, 0], [0, 'cos(theta * pi / 180)', '-1j*sin(theta * pi / 180)', 0], [0, '-1j*sin(theta * pi / 180)', 'cos(theta * pi / 180)', 0], [0, 0, 0, 'exp(1j * phi * pi / 180)']])¶