qsearch

Submodules

Package Contents

Classes

Options

This class manages options that are passed between various Qsearch objects.

Compiler

This class defines the pattern for compilers that convert a unitary matrix to a circuit that implements that matrix.

SearchCompiler

This Compiler uses an A* search strategy to synthesize a unitary, as described in the paper Towards Optimal Topology Aware Quantum Circuit Synthesis.

Gate

This class shows the framework for working with quantum gates in Qsearch.

IdentityGate

Represents an identity gate of any number of qudits of any size.

XGate

Represents a parameterized X rotation on one qubit.

YGate

Represents a parameterized Y rotation on one qubit.

ZGate

Represents a parameterized Z rotation on one qubit.

SXGate

Represents a sqrt(X) rotation on one qubit, which is equivalent to XGate() with a paramter of pi/2, up to an overall phase.

ZXZXZGate

Represents an arbitrary parameterized single-qubit gate, decomposed into 3 parameterized Z gates separated by X(PI/2) gates.

XZXZGate

Represents a partially parameterized single qubit gate, equivalent to ZXZXZ but without the first Z gate. This is useful because that first Z gate can commute through the control of a CNOT, thereby reducing the number of parameters we need to solve for.

U3Gate

Represents an arbitrary parameterized single qubit gate, parameterized in the same way as IBM's U3 gate.

U2Gate

Represents a parameterized single qubit gate, parameterized in the same way as IBM's U2 gate.

U1Gate

Represents an parameterized single qubit gate, parameterized in the same way as IBM's U1 gate.

SingleQutritGate

This gate represents an arbitrary parameterized single-qutrit gate.

CSUMGate

Represents the constant two-qutrit gate CSUM

CPIGate

Represents the constant two-qutrit gate CPI.

CPIPhaseGate

Represents the constant two-qutrit gate CPI with phase differences.

CNOTGate

Represents the constant two-qubit gate CNOT.

CZGate

Represents the constant two-qubit gate Controlled-Z.

ISwapGate

Represents the constant two-qubit gate ISwap.

XXGate

Represents the constant two-qubit gate XX(pi/2).

NonadjacentCNOTGate

Represents the two-qubit gate CNOT, but between two qubits that are not necessarily next to each other.

UGate

Represents an arbitrary constant gate, defined by the unitary passed to the initializer.

UpgradedConstantGate

Represents a constant gate, based on the Gate passed to its initializer, but upgraded to act on qudits of a larger size.

CUGate

Represents an arbitrary controlled gate, defined by the unitary passed to the initializer.

CNOTRootGate

Represents the sqrt(CNOT) gate. Two sqrt(CNOT) gates in a row will form a CNOT gate.

KroneckerGate

Represents the Kronecker product of a list of gates. This is equivalent to performing those gate in parallel in a quantum circuit.

ProductGate

Represents a matrix product of Gates. This is equivalent to performing those gates sequentially in a quantum circuit.

Project

The project class wraps most of the functionality of Qsearch as intended to help manage working with Qsearch.

Attributes

standard_defaults

standard_smart_defaults

native_from_object

class qsearch.Options(defaults={}, smart_defaults={}, **xtraargs)

This class manages options that are passed between various Qsearch objects.

filtered(self, *names)

Returns an Options object with only parameters in the specified list names.

__getitem__(self, name)
__delitem__(self, name)
__getattr__(self, name)
__setattr__(self, name, value)

Implement setattr(self, name, value).

__contains__(self, name)
manually_entered(self, *names, location='dict', operator='all')
empty_copy(self)

Create an Options object with the same defaults but without any specific values.

copy(self)

Create a full copy of an Options object.

__copy__(self)
updated(self, other=None, **xtraargs)

Return a new Options object that is a copy of this object, updated with the contents of other and xtraargs.

update(self, other=None, **xtraargs)

Mutate the current Options object with the contents of other and xtraargs.

_update_dict(self, otherdict)
set_defaults(self, **args)

Set default values for this Options object.

If an Options object is queried for a value, and it does not contain it, it will check its defaults list before throwing an error.

set_smart_defaults(self, **args)

Set smart_defaults values for this Options object.

If an Options object is queried for a value, and it does not contain it, it will check its smart_defaults list before throwing an error. If it does find a function in smart_defaults, it calls that function, passing itself as the argument, and returns the return value of that function, caching it for next time.

make_required(self, *names)

Marking names as required will cause the Options object to throw an error if it does not contain it, even if it has defaults or smart_defaults defined.

remove_defaults(self, *names)

Removes the defaults for the specified names.

remove_smart_defaults(self, *names)

Removes the smart_defaults for the specified names.

generate_cache(self)

Caches valuesa for all functions in smart_defaults.

save(self, filepath=None)

Saves the Options object to a file, or to a returned tuple.

load(self, filepath_or_tuple, strict=False)

Loads the Options object from a file or tuple.

If strict is left as False, the Options object will attempt to gracefully handle errors when loading its contents, relying on its ability to fallback to defaults or smart_defaults if those are able to load successfully.

If strict is set to True, the Options object will throw an error upon any error while loading.

__getstate__(self)
__setstate__(self, state)
qsearch.standard_defaults
qsearch.standard_smart_defaults
class qsearch.Compiler(options=Options())

This class defines the pattern for compilers that convert a unitary matrix to a circuit that implements that matrix.

abstract compile(self, options)
class qsearch.SearchCompiler(options=Options())

Bases: Compiler

This Compiler uses an A* search strategy to synthesize a unitary, as described in the paper Towards Optimal Topology Aware Quantum Circuit Synthesis.

Options:

target (required) : The unitary matrix to be synthesized, in the form of a numpy ndarray with dtype=”complex128”. gateset : The Gateset used for synthesis. weight_limit : A limit on the maximum weight for circuits to be expanded for further searching. See gatesets.py for more information. The default is None for unlimited. heuristic : A heuristic used to order the search tree. See heuristics.py for more information. solver : A Solver used for optimizing the parameters in parameterized circuits generated by the search tree. parallelizer : A Parallelizer used for solving multiple parameterized circuits in parallel. beams : The number of nodes to pop from the search tree at a time. The default value of -1 will create enough branches to maximize utilization of your CPU. objective : An Objective used for scoring the quality of a parameterization for both synthesis and search. timeout : An uper limit on the amount of time the compiler will spend trying to synthesize a circuit. The default is float(‘inf’), for unlimited. checkpoint : The compiler will use this Checkpoint to save intermediate state, and will resume from this Checkpoint if there was an existing state. logger : A qsearch.logging.Logger that will be used for logging the synthesis process.

Parameters

options – See class level documentation for the options SearchCompiler uses

compile(self, options=Options())
Parameters

options – See class level documentation for the options SearchCompiler uses

qsearch.native_from_object
class qsearch.Gate

This class shows the framework for working with quantum gates in Qsearch.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

abstract matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

abstract assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__eq__(self, other)

Return self==value.

__hash__(self)

Return hash(self).

copy(self)
_parts(self)
__copy__(self)
__deepcopy__(self, memo)
__repr__(self)

Return repr(self).

validate_structure(self)
class qsearch.IdentityGate(qudits=1, d=2)

Bases: Gate

Represents an identity gate of any number of qudits of any size.

Parameters
  • qudits – The number of qudits represented by this identity.

  • d – The size of qudits represented by this identity (2 for qubits, 3 for qutrits, etc.)

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.XGate

Bases: Gate

Represents a parameterized X rotation on one qubit.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.YGate

Bases: Gate

Represents a parameterized Y rotation on one qubit.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.ZGate

Bases: Gate

Represents a parameterized Z rotation on one qubit.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.SXGate

Bases: Gate

Represents a sqrt(X) rotation on one qubit, which is equivalent to XGate() with a paramter of pi/2, up to an overall phase.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.ZXZXZGate

Bases: Gate

Represents an arbitrary parameterized single-qubit gate, decomposed into 3 parameterized Z gates separated by X(PI/2) gates.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.XZXZGate

Bases: Gate

Represents a partially parameterized single qubit gate, equivalent to ZXZXZ but without the first Z gate. This is useful because that first Z gate can commute through the control of a CNOT, thereby reducing the number of parameters we need to solve for.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.U3Gate

Bases: Gate

Represents an arbitrary parameterized single qubit gate, parameterized in the same way as IBM’s U3 gate.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__eq__(self, other)

Return self==value.

__repr__(self)

Return repr(self).

class qsearch.U2Gate

Bases: Gate

Represents a parameterized single qubit gate, parameterized in the same way as IBM’s U2 gate.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__eq__(self, other)

Return self==value.

__repr__(self)

Return repr(self).

class qsearch.U1Gate

Bases: Gate

Represents an parameterized single qubit gate, parameterized in the same way as IBM’s U1 gate.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__eq__(self, other)

Return self==value.

__repr__(self)

Return repr(self).

class qsearch.SingleQutritGate

Bases: Gate

This gate represents an arbitrary parameterized single-qutrit gate.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CSUMGate

Bases: Gate

Represents the constant two-qutrit gate CSUM

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_csum
matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CPIGate

Bases: Gate

Represents the constant two-qutrit gate CPI.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_cpi
matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CPIPhaseGate

Bases: Gate

Represents the constant two-qutrit gate CPI with phase differences.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CNOTGate

Bases: Gate

Represents the constant two-qubit gate CNOT.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_cnot
__eq__(self, other)

Return self==value.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CZGate

Bases: Gate

Represents the constant two-qubit gate Controlled-Z.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_gate
__eq__(self, other)

Return self==value.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.ISwapGate

Bases: Gate

Represents the constant two-qubit gate ISwap.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_gate
__eq__(self, other)

Return self==value.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.XXGate

Bases: Gate

Represents the constant two-qubit gate XX(pi/2).

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_gate
__eq__(self, other)

Return self==value.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.NonadjacentCNOTGate(qudits, control, target)

Bases: Gate

Represents the two-qubit gate CNOT, but between two qubits that are not necessarily next to each other.

Parameters
  • qudits – The total number of qubits that a unitary of the size returned by this gate would represent. For this gate, usually this is the total number of qubits in the larger circuit.

  • control – The index of the control qubit, relative to the 0th qubit that would be affected by the unitary returned by this gate.

  • target – The index of the target qubit, relative to the 0th qubit that would be affected by the unitary returned by this gate.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

validate_structure(self)
class qsearch.UGate(U, d=2, gatename='CUSTOM', gateparams=(), gateindices=None)

Bases: Gate

Represents an arbitrary constant gate, defined by the unitary passed to the initializer.

Parameters
  • U – The unitary for the operation that this gate represents, as a numpy ndarray with datatype=”complex128”.

  • d – The size of qudits for the operation that this gate represents. The default is 2, for qubits.

  • gatename – A name for this gate, which will get passed to the Assembler at assembly time.

  • gateparams – A tuple of parameters that will get passed to the Assembler at assembly time.

  • gateindices – A tuple of indices for the qubits that this gate acts on, which will get passed to the Assembler at assembly time. This overrides the default behavior, which is to return a tuple of all the indices starting with the one passed in assemble(v, i), and ending at i+self.qudits

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.UpgradedConstantGate(other, df=3)

Bases: Gate

Represents a constant gate, based on the Gate passed to its initializer, but upgraded to act on qudits of a larger size.

Parameters
  • other – A Gate of a lower qudit size.

  • df – The final, upgraded qudit size. The default is 3, for upgrading gates from qubits to qutrits.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CUGate(U, gatename='Name', gateparams=(), flipped=False)

Bases: Gate

Represents an arbitrary controlled gate, defined by the unitary passed to the initializer.

Parameters
  • U – The unitary to form the controlled-unitary gate, in the form of a numpy ndarray with dtype=”complex128”

  • gatename – A name for this controlled gate which will get passed to the Assembler at assembly time.

  • gateparams – A tuple of parameters that will get passed to the Assembler at assembly time.

  • flipped – A boolean flag, which if set to true, will flip the direction of the gate. The default direction is for the control qubit to be the lower indexed qubit.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.CNOTRootGate

Bases: Gate

Represents the sqrt(CNOT) gate. Two sqrt(CNOT) gates in a row will form a CNOT gate.

Gates must set the following variables in __init__

self.num_inputs : The number of parameters needed to generate a unitary. This can be 0. self.qudits : The number of qudits acted on by a unitary of the size generated by the gate. For example, this would be 1 for U3, 2 for CNOT.

_cnr
matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

__repr__(self)

Return repr(self).

class qsearch.KroneckerGate(*subgates)

Bases: Gate

Represents the Kronecker product of a list of gates. This is equivalent to performing those gate in parallel in a quantum circuit.

Parameters

*subgates – An sequence of Gates. KroneckerGate will return the kronecker product of the unitaries returned by those Gates.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

appending(self, gate)

Returns a new KroneckerGate with the new gate added to the list.

Parameters

gate – A Gate to be added to the end of the list of gates in the new KroneckerGate.

_parts(self)
__deepcopy__(self, memo)
__repr__(self)

Return repr(self).

validate_structure(self)
class qsearch.ProductGate(*subgates)

Bases: Gate

Represents a matrix product of Gates. This is equivalent to performing those gates sequentially in a quantum circuit.

Parameters

subgates – A list of Gates to be multiplied together. ProductGate returns the matrix product of the unitaries returned by those Gates.

matrix(self, v)

Generates a matrix using the given vector of input parameters. For a constant gate, v will be empty.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A unitary matrix with dtype=”complex128”, equal in size to d**self.qudits, where d is the intended qudit size (d is 2 for qubits, 3 for qutrits, etc.)

Return type

np.ndarray

mat_jac(self, v)

Generates a matrix and the jacobian(s) using the given vector of input parameters.

It is not required to implement mat_jac for constant gates, nor is it required when using gradient-free Solvers.

The jacobian matrices will be complex valued, and should be the elementwise partial derivative with respect to each of the parameters. There should be self.num_inputs matrices in the array, with the ith entry being the partial derivative with respect to v[i]. See U3Gate for an example implementation.

Parameters

v – A numpy array of real floating point numbers, ranging from 0 to 2*PI. Its size is equal to self.num_inputs

Returns

A tuple of the same unitary that would be returned by matrix(v), and an array of Jacobian matrices.

Return type

tuple

assemble(self, v, i=0)

Generates an array of tuples as an intermediate format before being processed by an Assembler for conversion to other circuit formats.

Parameters
  • v – The same numpy array of real floating point numbers that might be passed to matrix(v).

  • i – The index of the lowest-indexed qubit that the unitary generated by the gate acts on.

Returns

A list of tuples following the format described above.

Return type

list

The format of the tuples returned looks like:

(“gate”, gatename, (*gateparameters), (*gateindices))

Where gatename corresponds to a gate that an Assembler will recognize, gateparameters corresponds to the parameters for the specified gate (usually but not always calculated from v), and gateindices corresponds to the qubit indices that the gate acts on (usually but not always calculated from i).

You can also have tuples of the form (“block”, *tuples) Where tuples is an array of tuples in this same format.

For some helpful examples, look at U3Gate, XZXZGate, CNOTGate, and NonadjacentCNOTGate.

appending(self, *gates)

Returns a new ProductGate with the new gates appended to the end.

Parameters

gates – A list of Gates to be appended.

inserting(self, *gates, depth=- 1)

Returns a new ProductGate with new gates inserted at some index depth.

Parameters
  • gates – A list of Gates to be inserted.

  • depth – An index in the subgates of the ProductGate after which the new gates will be inserted. The default value of -1 will insert these gates at the begining of the ProductGate.

__deepcopy__(self, memo)
__repr__(self)

Return repr(self).

validate_structure(self)
class qsearch.Project(path, use_mpi=False)

The project class wraps most of the functionality of Qsearch as intended to help manage working with Qsearch.

_save(self)
_checkpoint_path(self, name)
add_compilation(self, name, U, options=None, handle_existing=None, **extraargs)

Adds a unitary to be compiled.

Parameters
  • name – A name for this unitary. Must be unique in this Project.

  • U – The unitary to be compiled, in the form of a numpy ndarray with dtype=”complex128”

  • handle_existing – A variable which defines how to behave if a compilation with the given name already exists. If it is set to “ignore”, it will simply return without doing anything. If it is set to “overwrite”, it will overwrite the previous entry. If it is set to the default of None, it will offer a warning asking the user to remove and re-add the compilation.

  • options – The options passed to this function will be used only when this compilation is run.

  • extraargs – The extraargs passed to this function will be used only when this compilation is run.

__setitem__(self, keyword, value)
configure_compiler_override(self, keyword, value)

An unsafe method that allows the user to set global Project Options even if there is existing work.

__getitem__(self, keyword)
__delitem__(self, keyword)
configure(self, **dictionary)

Adds multiple options to the global Project Options at once.

reset(self, name=None)

Resets a Project, removing any work done but not the initial configurations.

Parameters

name – Optionally specify a particular compilation by name to reset

remove_compilation(self, name)

Removes a compilation from a Project.

Parameters

name – The name of the compilation to remove

clear(self, name=None)

Clears a Project, reverting it to a state similar to a newly created Project.

Parameters

name – Optionally specify a particular compilation by name to clear

__enter__(self)
__exit__(self, exc_typ, exc_val, exc_tb)
set_defaults(self, defaults=standard_defaults)

Updates the Project Options with the standard defaults from defaults.py, or a provided dictionary.

set_smart_defaults(self, smart_defaults=standard_smart_defaults)

Updates the Project Options with the standard smart_defaults from defaults.py, or a provided dictionary

run(self)

Runs all of the compilations in the Project.

post_process(self, postprocessor, name=None, options=None, **xtraargs)

Post-processes the specified compilation, or all compilations if name is None, using the specified postprocessor.

Parameters
  • postprocessor – The qsearch.post_processing.PostProcessor to run on the compilation or project

  • name – Optionally specify a particular compilation by name to reset

  • options – Options to pass to the qsearch.post_processing.PostProcessor passed in postprocessor

  • extraargs – Extra arguments passed as options to the qsearch.post_processing.PostProcessor passed in postprocessor

complete(self)

Returns a True if all compilations in the Project have finished and False otherwise.

finish(self)

Called when done running compilations in order to end MPI tasks.

status(self, name=None, logger=None)

Prints a status update on how much of a Project has finished running.

Parameters

name – Optionally specify which compilation to check the status of

property compilations(self)

The list of names corresponding to compilations on this Project.

_compilation_status(self, name)
_overall_status(self)
get_result(self, name)

Get the result of a compilation.

Parameters

name – The name of the compilation to get the result dictionary from

Returns

The result dictionary for a finished compilation. Usually this contains the entries “structure”, a Gate, and “parameters”, an array of real number parameters.

Return type

dict

get_target(self, name)

Get the target unitary of a compilation.

Parameters

name – The name of the compilation to get the target from

Returns

The target unitary of the compilation

Return type

np.ndarray

get_time(self, name)

Get the runtime that it took to run a compilation.

Parameters

name – The name of the compilation to get the runtime of

Returns

The number of seconds the compilation took

Return type

float

get_options(self, name=None)

Get the qsearch.options.Options object from a compilation of project

Parameters

name – Optionally pass the name of the compilation to get the qsearch.options.Options object from

Returns

the requested options object

Return type

qsearch.options.Options

assemble(self, name, options=None, **xtraargs)

Assembles a compilation using the Assembler specified as assembler in the Options. :param name: The compilation to assemble :param options: Contains the qsearch.assemblers.Assembler to use in assembly

Returns

The resulting assembled code

Return type

str