Config¶

class trueq.config.Config(conf)¶

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

Minimal Example .yaml file: The YAML below defines a 4 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) rotation, which can be applied in parallel with anything
CNOTS, which can never be used in parallel with any other gate.

Note that gates can be defined either by the Hamiltonian, or Matrix keyword, but never both. Any variables used in the definitions of the Hamiltonian or Matrix must be present in the name of the gate. For example: Gate CZ(phi, theta)

Name: Example
Dimension: 2
Mode: ZXZXZ
Gate X(phi):
  Hamiltonian:
    - ['X', phi]
  Involving:
    (0,) : (1,)
    (1,) : (0, 2)
    (2,) : (1, 3)
    (3,) : (2,)
Gate Z(phi):
  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)

Since we allow arbitrary functional definition of gates, the Config object can be used to generate new trueq.NativeGate objects on the fly, based upon the variables as defined in the YAML. An example of this, lets say we import the above YAML file

conf = Config('example.yaml')

We gain access to trueq.config.GateFactory objects.

conf.factories

For ease of use these are made available through attributes of the Config

conf.X

Lets make an X90 gate using this defition:

>>> conf.X(phi=90)
>>> NativeGate(expansion={'I': (0.7071+0j), 'X': (0-0.7071j)})

Additionally the config contains information about physical limitations of the gates as well. This information is encoded in the involving key inside of the gate definitions. This involving key is dictionary like, where the keys of the dictionary define the qubits where the gate can act.

For example:: In the above yaml config, gates X can be applied on qubits 0, 1, 2, 3.

The values associated with these keys provide information about physical limitations, what this means is that some physical gates cannot be run at the same time as other gates and these values reflect this.

Continuing the example of gate X:: When it is used on qubit (0,), no other gates may be applied on qubit (1,).

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 from_params(name, mode='ZXZXZ', dim=2, factories=None)¶

Creates 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 trueq.config.GateFactory objects.

Return type

Config

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

Creates 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

# load a config from file
config = tq.Config("my_config.yaml")

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

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

property dim¶

The dimension of systems (IE: 2 for qubit, 3 for qutrit) as defined in the provided config file.

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-qudit gates in the config.

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

Type: set

to_dict()¶

Returns a dictionary representation of the Config object

Return type: dict

to_yaml()¶

Returns a YAML representation of the Config object

Type: str

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

Stores the YAML-like formatted description of a gate and allows for the creation of new trueq.Gate objects based upon it. This is useful in the case where you have a functional description of a gate such as X(theta) which would be 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. Example:

y_factory = GateFactory(name='y', hamiltonian=[['Y', 'phi']])
y_factory
GateFactory(name='y', hamiltonian=[['Y', 'phi']])
Y90_gate = y_factory(phi=90)
iSwap_matrix = [[1,  0,  0,                          0],
                [0,  0,-1j,                          0],
                [0,-1j,  0,                          0],
                [0,  0,  0,'exp(-1j * phi * pi / 180)']]
iSwap_factory = GateFactory(name="iSwapLike", matrix=iSwap_matrix)
iSwap_gate = iSwap_factory(phi=45)

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, can include string function definitions which will be parsed into a trueq.Gate when the factory is called.
hamiltonian (list) – A hamiltonian generator description of the gate, as described in the trueq.Gate object. However the values can be string values which can be parsed into values.
involving (dict) – A dictionary describing the limitations of the gate, see trueq.Config description for a more in-depth description.
conf_name (str) – Used for correctly generating __repr__, used primarily by trueq.Config.

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

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,)}

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 single_qubit_axis¶

If this factory is a simple qubit rotation about a single Pauli axis, then a tuple (axis, angle) where axis is one of 'X', 'Y', or 'Z' and angle is the rotation angle in degrees if a fixed gate, and None if an arbitrary angle.

If this factory is not a simple qubit rotation about a single Pauli axis, then None. Also None if this is a simple qubit rotation but the single parameter is not in terms of degrees.

Type: tuple | None

get_gate(*args, **kwargs)¶

Returns a trueq.NativeGate based upon the parameters provided.

Since Gates are defined by text strings, some live parsing is done on this text description to generate the Gate object.

Note

If the gate is defined by only 1 parameter, it is not required to provide the keyword, the parameter is inferred from what is expected. Otherwise all parameters must be specified in full by their keywords. constructed trueq.Gate objects are memoized and cached based upon the kwargs.

find_closest(gate)¶

Given a trueq.Gate object, optimize the Factory parameters such that we get the closest gate possible up to a global phase.

Returns the closest gate possible, as well as the error.

Note

Where ‘close’ is defined by the Frobenous Norm of: Gate.mat.T.conj() @ Factory(**params).mat - I Where the global phase has been removed from the product matrix. This uses scipy.optimize to find these values.

Parameters: gate (Gate) – A Gate
Return type: (Gate, float)

property n_sys¶

The number of qubits this gate generator acts on.

Type: int

property dim¶

The dimension of this gate, IE: 2 for single qubit, 4 for 2 etc.

Type: int

property parameters¶

Returns a list of all expected parameters defined in the functional definition of the gate.

Type: list

property n_params¶

Returns the number of expected parameters required in the functional definition of the gate.

Type: int

property involving¶

Returns a dict-like object containing the qubits involved with the gate operation, see trueq.config.InvolvingRule for more details.

Type: trueq.config.InvolvingRule

to_dict()¶

Returns a dictionary representation of the factory object.

Return type: dict

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

A dict like object which contains rules for when different labels are restricted.

Examples:

# In the default case, any involving check returns as valid

rule = InvolvingRule()

(5, ) in rule
# True

rule[(1, 5)]
# tuple()

(5, 5) in rule
# KeyError('Keys must contain unique labels only')

# 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,)]
# (2, 3, 4)

rule[(1,)]
# KeyError("Labels not present in rules")

# 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,)]
# (2, 3, 4)

rule[(1,)]
# tuple()

See trueq.Config for more details on involving.

Parameters

rules (dict or dict-like) – A dict like object 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 or 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)¶

Get 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.

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 of int) – The key to fetch, must be a tuple of ints.
Return type: tuple

unordered_contains(key)¶

Returns boolean conditioned on if the given key is present in rules, regardless of the ordering of the key.

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 of int) – The key to fetch, must be a tuple of ints.
Return type: bool

trueq.config.make_config(multiqubit_factory, parameters, name, mode='ZXZ')¶

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

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(
    name="iSwapLike", matrix=iSwapLike_mat
)
parameters = {(0, 1): 90, (2, 3): 45}
conf = make_config(iSwapLike_factory, parameters, "nonhomogenous_gates")
conf.iswaplike_0_1().mat

Parameters

multiqubit_factory (trueq.config.GateFactory) – A GateFactory 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

trueq.Config

trueq.config.parse_func(func_str)¶

Creates a python function from a string containing numbers, variables and standard math functions. See trueq.config.factory.KNOWN_FUNCTIONS for list of functions that can be parsed.

Note

In simple test cases runs approx 20x slower than numpy. For example:

>>> f = parse_func('5*sin(x) + y')
>>> f(x=np.pi, y=1)
>>> 1.0

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