pygsti.algorithms.compilers
Clifford circuit, CNOT circuit, and stabilizer state/measurement generation compilation routines
Module Contents
Functions

Compiles an nqubit Clifford gate into a circuit over a given processor specification. 

Creates a 

A CNOT circuit compiler. 

Generates a circuit to create the stabilizer state from the standard input state 0,0,0,...>. 

Generates a circuit to map the stabilizer state to the standard state 0,0,0,...>. 
Performs an Albert factorization transform on s. 


Finds circuits that partially (conditional on the input) implement the Clifford given by s. 
 pygsti.algorithms.compilers.compile_clifford(s, p, pspec=None, absolute_compilation=None, paulieq_compilation=None, qubit_labels=None, iterations=20, algorithm='ROGGE', aargs=None, costfunction='2QGC:10:depth:1', prefixpaulis=False, paulirandomize=False, rand_state=None)
Compiles an nqubit Clifford gate into a circuit over a given processor specification.
Compiles an nqubit Clifford gate, described by the symplectic matrix s and vector p, into a circuit over the gates given by a processor specification or a standard processor. Clifford gates/circuits can be converted to, or sampled in, the symplectic representation using the functions in
pygsti.tools.symplectic
.The circuit created by this function will be over the gates in the given processor spec, respecting its connectivity, when a QubitProcessorSpec object is provided. Otherwise, it is over a canonical processor containing alltoall CNOTs, Hadamard, Phase, 3 products of Hadamard and Phase, and the Pauli gates.
Parameters
 sarray over [0,1]
An (2n X 2n) symplectic matrix of 0s and 1s integers.
 parray over [0,1]
A length2n vector over [0,1,2,3] that, together with s, defines a valid nqubit Clifford gate.
 pspecQubitProcessorSpec, optional
An nbarqubit QubitProcessorSpec object that encodes the device that the Clifford is being compiled for, where nbar >= n. If this is specified, the output circuit is over the gates available in this device. If this is None, the output circuit is over the “canonical” processor of CNOT gates between all qubits, consisting of “H”, “HP”, “PH”, “HPH”, “I”, “X”, “Y” and “Z”, which is the set used internally for the compilation. In most circumstances, the output will be more useful if a QubitProcessorSpec is provided.
If nbar > n it is necessary to provide qubit_labels, that specifies which of the qubits in pspec the Clifford acts on. (All other qubits will not be part of the returned circuit, regardless of whether that means an overhead is required to avoid using gates that act on those qubits. If these additional qubits should be used, then the input Clifford needs to be “padded” to be the identity on those qubits).
The ordering of the indices in (s,`p`) is w.r.t to ordering of the qubit labels in pspec.qubit_labels, unless qubit_labels is specified. Then, the ordering is taken w.r.t the ordering of the list qubit_labels.
 absolute_compilationCompilationRules
Rules for exactly (absolutely) compiling the “native” gates of pspec into clifford gates.
 paulieq_compilationCompilationRules
Rules for compiling, up to singlequbit Pauli gates, the “native” gates of pspec into clifford gates.
 qubit_labelslist, optional
Required if the Clifford to compile is over less qubits than pspec. In this case this is a list of the qubits to compile the Clifford for; it should be a subset of the elements of pspec.qubit_labels. The ordering of the qubits in (s,`p`) is taken w.r.t the ordering of this list.
 iterationsint, optional
Some of the allowed algorithms are randomized. This is the number of iterations used in algorithm if it is a randomized algorithm specified. If any randomized algorithms are specified, the time taken by this function increases linearly with iterations. Increasing iterations will often improve the obtained compilation (the “cost” of the obtained circuit, as specified by costfunction may decrease towards some asymptotic value).
 algorithmstr, optional
Specifies the algorithm used for the core part of the compilation: finding a circuit that is a Clifford with s the symplectic matrix in its symplectic representation (a circuit that implements that desired Clifford up to Pauli operators). The allowed values of this are:
 ‘BGGE’: A basic, deterministic global Gaussian elimination algorithm. Circuits obtained from this algorithm
contain, in expectation, O(n^2) 2qubit gates. Although the returned circuit will respect device connectivity, this algorithm does not take connectivity into account in an intelligient way. More details on this algorithm are given in compile_symplectic_with_ordered_global_gaussian_elimination(); it is the algorithm described in that docstring but with the qubit ordering fixed to the order in the input s.
 ‘ROGGE’: A randomized elimination order global Gaussian elimination algorithm. This is the same algorithm as
‘BGGE’ except that the order that the qubits are eliminated in is randomized. This results in significantly lowercost circuits than the ‘BGGE’ method (given sufficiently many iterations). More details are given in the compile_symplectic_with_random_ordered_global_gaussian_elimination() docstring.
 ‘iAGvGE’: Our improved version of the AaraonsonGottesman method for compiling a Clifford circuit, which
uses 3 CNOT circuits and 3 1Qgate layers (rather than the 5 CNOT circuit used in the algorithm of AG in Phys. Rev. A 70 052328 (2004)), with the CNOT circuits compiled using Gaussian elimination. Note that this algorithm appears to perform substantially worse than ‘ROGGE’, even though with an upgraded CNOT compiler it is asymptotically optimal (unlike any of the GGE methods). Also, note that this algorithm is randomized: there are many possible CNOT circuits (with nonequivalent action, individually) for the 2 of the 3 CNOT stages, and we randomize over those possible circuits. This randomization is equivalent to the randomization used in the stabilizer state/measurement compilers.
 aargslist, optional
If the algorithm can take optional arguments, not already specified as separate arguments above, then this list is passed to the compile_symplectic algorithm as its final arguments.
 costfunctionfunction or string, optional
If a function, it is a function that takes a circuit and pspec as the first and second inputs and returns a ‘cost’ (a float) for the circuit. The circuit input to this function will be over the gates in pspec, if a pspec has been provided, and as described above if not. This costfunction is used to decide between different compilations when randomized algorithms are used: the lowest cost circuit is chosen. If a string it must be one of:
‘2QGC’ : the cost of the circuit is the number of 2qubit gates it contains.
‘depth’ : the cost of the circuit is the depth of the circuit.
 ‘2QGC:x:depth:y’the cost of the circuit is x * the number of 2qubit gates in the circuit +
y * the depth of the circuit, where x and y are integers.
 prefixpaulisbool, optional
A Pauli layer is needed to compile the correct Clifford (and not just the correct Clifford up to Paulis). When prefixpaulis = True this Pauli layer is placed at the beginning of the circuit; when False, it is placed at the end. Note that the required Pauli layer depends on whether we prefix or postfix it to the main symplecticgenerating circuit.
 paulirandomizebool, optional
If True then independent, uniformly random Pauli layers (a Pauli on each qubit) are inserted in between every layer in the circuit. These Paulis are then compiled into the gates in pspec, if pspec is provided. That is, this Pauliframerandomizes / Paulitwirls the internal layers of this Clifford circuit. This can be useful for preventing coherent addition of errors in the circuit.
 rand_state: RandomState, optional
A np.random.RandomState object for seeding RNG
Returns
 Circuit
A circuit implementing the input Clifford gate/circuit.
 pygsti.algorithms.compilers.compile_symplectic(s, pspec=None, absolute_compilation=None, paulieq_compilation=None, qubit_labels=None, iterations=20, algorithms=None, costfunction='2QGC:10:depth:1', paulirandomize=False, aargs=None, check=True, rand_state=None)
Creates a
Circuit
that implements a Clifford gate given in the symplectic representation.Returns an nqubit circuit that implements an nqubit Clifford gate that is described by the symplectic matrix s and some vector p. The circuit created by this function will be over the gates in the processor specification pspec, respecting any desired connectivity if a QubitProcessorSpec object is provided. Otherwise, the circuit is over the gates of a canonical processor containing alltoall CNOTs, Hadamard, Phase, 3 products of Hadamard and Phase, and the Pauli gates.
Parameters
 sarray over [0,1]
An (2n X 2n) symplectic matrix of 0s and 1s integers.
 pspecQubitProcessorSpec, optional
An nbarqubit QubitProcessorSpec object that encodes the device that s is being compiled for, where nbar >= n. If this is specified, the output circuit is over the gates available in this device. If this is None, the output circuit is over the “canonical” processor of CNOT gates between all qubits, consisting of “H”, “HP”, “PH”, “HPH”, “I”, “X”, “Y” and “Z”, which is the set used internally for the compilation.
If nbar > n it is necessary to provide qubit_labels, that specifies which of the qubits in pspec the Clifford acts on. (All other qubits will not be part of the returned circuit, regardless of whether that means an overhead is required to avoid using gates that act on those qubits. If these additional qubits should be used, then the input s needs to be “padded” to be the identity on those qubits).
The indexing s is assumed to be the same as that in the list pspec.qubit_labels, unless qubit_labels is specified. Then, the ordering is taken w.r.t the ordering of the list qubit_labels.
 absolute_compilationCompilationRules
Rules for exactly (absolutely) compiling the “native” gates of pspec into clifford gates.
 paulieq_compilationCompilationRules
Rules for compiling, up to singlequbit Pauli gates, the “native” gates of pspec into clifford gates.
 qubit_labelslist, optional
Required if the Clifford to compile is over less qubits than pspec. In this case this is a list of the qubits to compile the Clifford for; it should be a subset of the elements of pspec.qubit_labels. The ordering of the qubits in (s,`p`) is taken w.r.t the ordering of this list.
 iterationsint, optional
Some of the allowed algorithms are randomized. This is the number of iterations used in each algorithm specified that is a randomized algorithm.
 algorithmslist of strings, optional
Specifies the algorithms used. Defaults to [‘ROGGE’]. If more than one algorithm is specified, then all the algorithms are implemented and the lowest “cost” circuit obtained from all the algorithms (and iterations of those algorithms, if randomized) is returned.
The allowed elements of this list are:
 ‘BGGE’: A basic, deterministic global Gaussian elimination algorithm. Circuits obtained from this algorithm
contain, in expectation, O(n^2) 2qubit gates. Although the returned circuit will respect device connectivity, this algorithm does not take connectivity into account in an intelligient way. More details on this algorithm are given in compile_symplectic_with_ordered_global_gaussian_elimination(); it is the algorithm described in that docstring but with the qubit ordering fixed to the order in the input s.
 ‘ROGGE’: A randomized elimination order global Gaussian elimination algorithm. This is the same algorithm as
‘BGGE’ except that the order that the qubits are eliminated in is randomized. This results in significantly lowercost circuits than the ‘BGGE’ method (given sufficiently many iterations). More details are given in the compile_symplectic_with_random_ordered_global_gaussian_elimination() docstring.
 ‘iAGvGE’: Our improved version of the AaraonsonGottesman method for compiling a symplectic matrix, which
uses 3 CNOT circuits and 3 1Qgate layers (rather than the 5 CNOT circuit used in the algorithm of AG in Phys. Rev. A 70 052328 (2004)), with the CNOT circuits compiled using Gaussian elimination. Note that this algorithm appears to perform substantially worse than ‘ROGGE’, even though with an upgraded CNOT compiler it is asymptotically optimal (unlike any of the GGE methods). Also, note that this algorithm is randomized: there are many possible CNOT circuits (with nonequivalent action, individually) for the 2 of the 3 CNOT stages, and we randomize over those possible circuits. This randomization is equivalent to the randomization used in the stabilizer state/measurement compilers.
 costfunctionfunction or string, optional
If a function, it is a function that takes a circuit and pspec as the first and second inputs and returns a cost (a float) for the circuit. The circuit input to this function will be over the gates in pspec, if a pspec has been provided, and as described above if not. This costfunction is used to decide between different compilations when randomized algorithms are used: the lowest cost circuit is chosen. If a string it must be one of:
‘2QGC’ : the cost of the circuit is the number of 2qubit gates it contains.
‘depth’ : the cost of the circuit is the depth of the circuit.
 ‘2QGC:x:depth:y’the cost of the circuit is x * the number of 2qubit gates in the circuit +
y * the depth of the circuit, where x and y are integers.
 paulirandomizebool, optional
If True then independent, uniformly random Pauli layers (a Pauli on each qubit) are inserted in between every layer in the circuit. These Paulis are then compiled into the gates in pspec, if pspec is provided. That is, this Pauliframerandomizes / Paulitwirls the internal layers of this Clifford circuit. This can be useful for preventing coherent addition of errors in the circuit.
 aargsdict, optional
If the algorithm can take optional arguments, not already specified as separate arguments above, then the list arrgs[algorithmname] is passed to the compile_symplectic algorithm as its final arguments, where algorithmname is the name of algorithm specified in the list algorithms.
 checkbool, optional
Whether to check that the output circuit implements the correct symplectic matrix (i.e., tests for algorithm success).
 rand_state: RandomState, optional
A np.random.RandomState object for seeding RNG
Returns
 Circuit
A circuit implementing the input Clifford gate/circuit.
 pygsti.algorithms.compilers.compile_cnot_circuit(s, pspec, compilation, qubit_labels=None, algorithm='COiCAGE', compile_to_native=False, check=True, aargs=None, rand_state=None)
A CNOT circuit compiler.
Takes an arbitrary CNOT circuit, input as a symplectic matrix s that corresponds to the matrix portion of the symplectic representation of this Clifford circuit, and decomposes it into a sequences of gates from the processor spec pspec.
Parameters
 sarray over [0,1]
An (2n X 2n) symplectic matrix of 0s and 1s integers that represents a Clifford circuit: so it must be blockdiagonal. Specifically, it has the form s = ((A,0),(0,B)) where B is the inverse transpose of A (over [0,1] mod 2).
 pspecQubitProcessorSpec
An nbarqubit QubitProcessorSpec object that encodes the device that s is being compiled for, where nbar >= n. If this is specified, the output circuit is over the gates available in this device. If this is None, the output circuit is over the “canonical” processor of CNOT gates between all qubits, consisting of “H”, “HP”, “PH”, “HPH”, “I”, “X”, “Y” and “Z”, which is the set used internally for the compilation.
If nbar > n it is necessary to provide qubit_labels, that specifies which of the qubits in pspec the Clifford acts on. (All other qubits will not be part of the returned circuit, regardless of whether that means an overhead is required to avoid using gates that act on those qubits. If these additional qubits should be used, then the input s needs to be “padded” to be the identity on those qubits).
The indexing s is assumed to be the same as that in the list pspec.qubit_labels, unless qubit_labels is specified. Then, the ordering is taken w.r.t the ordering of the list qubit_labels.
 compilationCompilationRules
Rules for compiling the “native” gates of pspec into clifford gates, used if compile_to_native==True.
 qubit_labelslist, optional
Required if the Clifford to compile is over less qubits than pspec. In this case this is a list of the qubits to compile the Clifford for; it should be a subset of the elements of pspec.qubit_labels. The ordering of the qubits in (s,`p`) is taken w.r.t the ordering of this list.
 algorithmstr, optional
The algorithm to use. The optionas are:
 ‘BGE’A basic Gaussian elimination algorithm, that uses CNOT to perform rowreduction on the upper
LHS (or lower RHS) of s. This algorithm does not take device connectivity into account.
 ‘OCAGE’Userordered connectivityadjusted Gaussian elimination. The qubits are eliminated in the
specified order; the first element of arrgs must be a list specify this order. The algorithm is also “connectivityadjusted” in the sense that it uses the connectivity graph (in pspec.qubit_graph) to try and avoid using CNOTs between unconnected pairs whenever possible, and to decide the order of various operations.
 ‘OiCAGE’The same as ‘OCAGE’ except that it has some improvements, and it requires connectivity
graph of the remaining qubits, after each qubit has been ‘eliminated’, to be connected. In the current format this algorithm is only slightly betterperforming than ‘OCAGE’, and only on average. (This algorithm will possibly be improved in the future, whereas ‘OCAGE’ will remain asis for reproducability of previously obtained results.)
 ‘ROCAGE’: Same as ‘OCAGE’ except that the elimination order is chosen at random, rather than user
specified.
 ‘COCAGE’, ‘COiCAGE’The same as ‘OCAGE’ and ‘OiCAGE’, respectively, except that the elimination order
is fixed to eliminate qubits with the worse connectivity before those with better connectivity.
 compile_to_nativebool, optional
Whether the circuit should be given in terms of the native gates of the processor defined in pspec.
 checkbool, optional
Whether to check the output is correct.
 aargslist, optional
A list of arguments handed to the CNOT compiler algorithm. For some choices of algorithm (e.g., ‘OCAGE’) this list must not be empty. For algorithms where there are X nonoptional arguements after s and pspec these are specified as the first X arguments of aargs. The remaining elements in aargs, if any, are handed to the algorithm as the arguments after the optional qubit_labels and check arguments (the first of which is set by the input qubit_labels in this function).
 rand_state: RandomState, optional
A np.random.RandomState object for seeding RNG
Returns
 Circuit
A circuit that implements the same unitary as the CNOT circuit represented by s.
 pygsti.algorithms.compilers.compile_stabilizer_state(s, p, pspec, absolute_compilation, paulieq_compilation, qubit_labels=None, iterations=20, paulirandomize=False, algorithm='COiCAGE', aargs=None, costfunction='2QGC:10:depth:1', rand_state=None)
Generates a circuit to create the stabilizer state from the standard input state 0,0,0,…>.
The stabilizer state is specified by s and p. The circuit returned is over the gates in the processor spec. See
compile_stabilizer_state()
for the inverse of this.Parameters
 sarray over [0,1]
An (2n X 2n) symplectic matrix of 0s and 1s integers. This is a symplectic matrix representing any Clifford gate that, when acting on 0,0,0,…>, generates the desired stabilizer state. So s is not unique.
 parray over [0,1]
A length2n vector over [0,1,2,3] that, together with s, defines a valid nqubit Clifford gate. This phase vector matrix should, together with s, represent any Clifford gate that, when acting on 0,0,0,…>, generates the desired stabilizer state. So p is not unique.
 pspec, pspecQubitProcessorSpec, optional
An nbarqubit QubitProcessorSpec object that encodes the device that the stabilizer is being compiled for, where nbar >= n. If this is specified, the output circuit is over the gates available in this device. If this is None, the output circuit is over the “canonical” processor of CNOT gates between all qubits, consisting of “H”, “HP”, “PH”, “HPH”, “I”, “X”, “Y” and “Z”, which is the set used internally for the compilation. In most circumstances, the output will be more useful if a QubitProcessorSpec is provided.
If nbar > n it is necessary to provide qubit_labels, that specifies which of the qubits in pspec the stabilizer is over. (All other qubits will not be part of the returned circuit, regardless of whether that means an overhead is required to avoid using gates that act on those qubits. If these additional qubits should be used, then the input (s,p) needs to be “padded” to be the identity on those qubits).
The ordering of the indices in (s,`p`) is w.r.t to ordering of the qubit labels in pspec.qubit_labels, unless qubit_labels is specified. Then, the ordering is taken w.r.t the ordering of the list qubit_labels.
 absolute_compilationCompilationRules
Rules for exactly (absolutely) compiling the “native” gates of pspec into clifford gates.
 paulieq_compilationCompilationRules
Rules for compiling, up to singlequbit Pauli gates, the “native” gates of pspec into clifford gates.
 qubit_labelsList, optional
Required if the stabilizer state is over less qubits than pspec. In this case this is a list of the qubits to compile the Clifford for; it should be a subset of the elements of pspec.qubit_labels. The ordering of the qubits in (s,`p`) is taken w.r.t the ordering of this list.
 iterationsint, optional
This algorithm is randomized. This is the number of iterations used in the algorithm. the time taken by this function increases linearly with iterations. Increasing iterations will often improve the obtained compilation (the “cost” of the obtained circuit, as specified by costfunction may decrease towards some asymptotic value).
 paulirandomizebool, optional
If True then independent, uniformly random Pauli layers (a Pauli on each qubit) are inserted in between every layer in the circuit. These Paulis are then compiled into the gates in pspec, if pspec is provided. That is, this Pauliframerandomizes / Paulitwirls the internal layers of this circuit. This can be useful for preventing coherent addition of errors in the circuit.
 algorithmstr, optional
Our algorithm finds a circuit consisting of 1Qgates  a CNOT circuit  1Qgates. The CNOT circuit is found using Gaussian elimination, and it can then be recompiled using a CNOTcircuit compiler. algorithm specifies the CNOTcompilation algorithm to use. The allowe values are all those algorithms that permisable in the compile_cnot_circuit() function. See the docstring of that function for more information. The default is likely to be the best out of the inbuilt CNOT compilers under most circumstances.
 aargslist, optional
If the CNOT compilation algorithm can take optional arguments, these are specified here. This is passed to compile_cnot_circuit() as aarg.
 costfunctionfunction or string, optional
If a function, it is a function that takes a circuit and pspec as the first and second inputs and returns a ‘cost’ (a float) for the circuit. The circuit input to this function will be over the gates in pspec, if a pspec has been provided, and as described above if not. This costfunction is used to decide between different compilations when randomized algorithms are used: the lowest cost circuit is chosen. If a string it must be one of:
‘2QGC’ : the cost of the circuit is the number of 2qubit gates it contains.
‘depth’ : the cost of the circuit is the depth of the circuit.
 ‘2QGC:x:depth:y’the cost of the circuit is x * the number of 2qubit gates in the circuit +
y * the depth of the circuit, where x and y are integers.
 rand_state: RandomState, optional
A np.random.RandomState object for seeding RNG
Returns
 Circuit
A circuit that creates the specified stabilizer state from 0,0,0,…>
 pygsti.algorithms.compilers.compile_stabilizer_measurement(s, p, pspec, absolute_compilation, paulieq_compilation, qubit_labels=None, iterations=20, paulirandomize=False, algorithm='COCAGE', aargs=None, costfunction='2QGC:10:depth:1', rand_state=None)
Generates a circuit to map the stabilizer state to the standard state 0,0,0,…>.
The stabilizer state is specified by s and p. The circuit returned is over the gates in the processor spec pspec. See :function”compile_stabilizer_state() for the inverse of this. So, this circuit followed by a Zbasis measurement can be used to simulate a projection onto the stabilizer state C`0,0,0,…>` where C is the Clifford represented by s and p.
Parameters
 sarray over [0,1]
An (2n X 2n) symplectic matrix of 0s and 1s integers. This is a symplectic matrix representing any Clifford gate that, when acting on 0,0,0,…>, generates the stabilizer state that we need to map to 0,0,0,…>. So s is not unique.
 parray over [0,1]
A length2n vector over [0,1,2,3] that, together with s, defines a valid nqubit Clifford gate. This phase vector matrix should, together with s, represent any Clifford gate that, when acting on 0,0,0,…>, generates the stabilizer state that we need to map to 0,0,0,…>. So p is not unique.
 pspecQubitProcessorSpec, optional
An nbarqubit QubitProcessorSpec object that encodes the device that the stabilizer is being compiled for, where nbar >= n. If this is specified, the output circuit is over the gates available in this device. If this is None, the output circuit is over the “canonical” processor of CNOT gates between all qubits, consisting of “H”, “HP”, “PH”, “HPH”, “I”, “X”, “Y” and “Z”, which is the set used internally for the compilation. In most circumstances, the output will be more useful if a QubitProcessorSpec is provided.
If nbar > n it is necessary to provide qubit_labels, that specifies which of the qubits in pspec the stabilizer is over. (All other qubits will not be part of the returned circuit, regardless of whether that means an overhead is required to avoid using gates that act on those qubits. If these additional qubits should be used, then the input (s,p) needs to be “padded” to be the identity on those qubits).
The ordering of the indices in (s,`p`) is w.r.t to ordering of the qubit labels in pspec.qubit_labels, unless qubit_labels is specified. Then, the ordering is taken w.r.t the ordering of the list qubit_labels.
 absolute_compilationCompilationRules
Rules for exactly (absolutely) compiling the “native” gates of pspec into clifford gates.
 paulieq_compilationCompilationRules
Rules for compiling, up to singlequbit Pauli gates, the “native” gates of pspec into clifford gates.
 qubit_labelsList, optional
Required if the stabilizer state is over less qubits than pspec. In this case this is a list of the qubits to compile the Clifford for; it should be a subset of the elements of pspec.qubit_labels. The ordering of the qubits in (s,`p`) is taken w.r.t the ordering of this list.
 iterationsint, optional
This algorithm is randomized. This is the number of iterations used in the algorithm. the time taken by this function increases linearly with iterations. Increasing iterations will often improve the obtained compilation (the “cost” of the obtained circuit, as specified by costfunction may decrease towards some asymptotic value).
 paulirandomizebool, optional
If True then independent, uniformly random Pauli layers (a Pauli on each qubit) are inserted in between every layer in the circuit. These Paulis are then compiled into the gates in pspec, if pspec is provided. That is, this Pauliframerandomizes / Paulitwirls the internal layers of this circuit. This can be useful for preventing coherent addition of errors in the circuit.
 algorithmstr, optional
Our algorithm finds a circuit consisting of 1Qgates  a CNOT circuit  1Qgates. The CNOT circuit is found using Gaussian elimination, and it can then be recompiled using a CNOTcircuit compiler. algorithm specifies the CNOTcompilation algorithm to use. The allowe values are all those algorithms that permisable in the compile_cnot_circuit() function. See the docstring of that function for more information. The default is likely to be the best out of the inbuilt CNOT compilers under most circumstances.
 aargslist, optional
If the CNOT compilation algorithm can take optional arguments, these are specified here. This is passed to compile_cnot_circuit() as aarg.
 costfunctionfunction or string, optional
If a function, it is a function that takes a circuit and pspec as the first and second inputs and returns a ‘cost’ (a float) for the circuit. The circuit input to this function will be over the gates in pspec, if a pspec has been provided, and as described above if not. This costfunction is used to decide between different compilations when randomized algorithms are used: the lowest cost circuit is chosen. If a string it must be one of:
‘2QGC’ : the cost of the circuit is the number of 2qubit gates it contains.
‘depth’ : the cost of the circuit is the depth of the circuit.
 ‘2QGC:x:depth:y’the cost of the circuit is x * the number of 2qubit gates in the circuit +
y * the depth of the circuit, where x and y are integers.
 rand_state: RandomState, optional
A np.random.RandomState object for seeding RNG
Returns
 Circuit
A circuit that maps the specified stabilizer state to 0,0,0,…>
 pygsti.algorithms.compilers.find_albert_factorization_transform_using_cnots(s, optype, position, qubit_labels, rand_state=None)
Performs an Albert factorization transform on s.
Given a symplectic s matrix of the form ((A,B),(C,D)) with the submatrix in the position specified by position symmetric, this function
1. Finds an invertable M such that F = M M.T where F is the submatrix in position position, i.e., F is one of A, B, C and D. (this is known as an albert factorization). 2. Applies a CNOT circuit from the LHS (if optype = ‘row’) or RHS (if optyp`=’colum’)) to `s so that F  > M.
For example, if s = ((A,I),(C,D)), position = ‘LR’ and optype = ‘column’ then it finds an M such that we may write s = ((A,I),(C,M M.T)) and it applies the CNOT circuit ((M,0),(0,M^(1)^T) to the RHS of s, mapping s to s = ((AM,M),(CM^(1)^T) ,M)), so that the upper RHS and lower RHS matrix of the new s are the same and are invertable.
This function returns a CNOT circuit that performs this action, with this CNOT circuit obtained from basic Gaussian elimination on M. Note that neither the returned s nor the CNOT circuit is deterministic: Both depend on M from albert factorisation, but this M is nonunique and our algorithm for finding such an M is randomized.
This function does not alter s, but rather returns an updated version of s.
Parameters
 snp.array
A (2n,2n) matrix over [0,1].
 optype‘row’ or ‘column’
If ‘row’, we use rowoperation CNOTs (CNOTs from the LHS). If ‘column’, we use columnoperation CNOTs (CNOTs from the RHS).
 position‘UL’, ‘UR’, ‘LL’, or ‘LR’
The submatrix to perform the transformation on. ‘UL’ and ‘UR’ correspond to the upper left and right submatrices, respecively. ‘LL’ and ‘LR’ correspond to the lower left and right submatrices, respecively.
 qubit_labelslist
The qubit labels corresponding to the indices of s. This is required because othewise it is ambigious as to what the ‘name’ of a qubit associated with each indices is, so it is not possible to return a suitable list of CNOTs.
 rand_statenp.random.RandomState, optional
Random number generator to allow for determinism.
Returns
 np.array
The updated s matrix.
 list
A list of CNOT gates to implement the transformation requested.
 pygsti.algorithms.compilers.compile_conditional_symplectic(s, pspec, qubit_labels=None, calg='COiCAGE', cargs=None, check=True, rand_state=None)
Finds circuits that partially (conditional on the input) implement the Clifford given by s.
The core of the compile_stabilizer_state() and compile_stabilizer_measurement() functions. Finds circuits C1 and C2 so that:
C1 is a CNOT circuit
C2 is a circuit with the form 1qubitgates – CNOT circuit – 1qubit gates.
The symplectic rep of the circuit consisting of C1 followed by C2 has the form ((.,B)(.,D)) when s has the form ((A,B),(C,D)).
Therefore, the circuit C2 acting on 0,0,0,…> generates the same stabilizer state (up to Paulis) as a circuit that has the symplectic rep (s,p) for any valid p. The circuit is only “conditionally” equivalent to another circuit with the rep (s,p) – conditional on the input state – which is the meaning of the name compile_conditional_symplectic.
Parameters
 sarray over [0,1]
An (2n X 2n) symplectic matrix of 0s and 1s integers.
 pspecQubitProcessorSpec, optional
An nbarqubit QubitProcessorSpec object that encodes the device that s is being “conditionally” compiled for, where nbar >= n. If nbar > n it is necessary to provide qubit_labels, that specifies which of the qubits in pspec the stabilizer is over. (All other qubits will not be part of the returned circuit, regardless of whether that means an overhead is required to avoid using gates that act on those qubits. If these additional qubits should be used, then the input (s,p) needs to be “padded” to be the identity on those qubits). The ordering of the indices in (s,`p`) is w.r.t to ordering of the qubit labels in pspec.qubit_labels, unless qubit_labels is specified. Then, the ordering is taken w.r.t the ordering of the list qubit_labels.
 qubit_labelsList, optional
Required if the s is over less qubits than pspec. In this case this is a list of the qubits to compile the Clifford for; it should be a subset of the elements of pspec.qubit_labels. The ordering of the qubits in (s,`p`) is taken w.r.t the ordering of this list.
 calgstr, optional
Our algorithm finds a circuit consisting of 1Qgates  a CNOT circuit  1Qgates. The CNOT circuit is found using Gaussian elimination, and it can then be recompiled using a CNOTcircuit compiler. calg specifies the CNOTcompilation algorithm to use. The allowed values are all those algorithms that are permisable in the compile_cnot_circuit() function. See the docstring of that function for more information. The default is likely to be the best out of the inbuilt CNOT compilers under most circumstances. Note that this is only used to recompile the CNOT circuit in C2, because the main use for this function only needs C1 for reference, rather than as a part of a final output.
 cargslist, optional
If the CNOT compilation algorithm can take optional arguments, these are specified here. This is passed to compile_cnot_circuit() as aarg.
 checkbool, optional
Whether to check that the output is correct.
 rand_state: RandomState, optional
A np.random.RandomState object for seeding RNG
Returns
 Circuit
The circuit C2 described above.
 Circuit
The circuit C1 described above.