quimb.tensor.circuit

Tools for quantum circuit simulation using tensor networks.

Attributes

ALL_GATES
ONE_QUBIT_GATES
TWO_QUBIT_GATES
ALL_PARAM_GATES
ONE_QUBIT_PARAM_GATES
TWO_QUBIT_PARAM_GATES
GATE_TAGS
GATE_SIZE
CONSTANT_GATES
PARAM_GATES
SPECIAL_GATES
_MPS_METHODS

Classes

Gate	A simple class for storing the details of a quantum circuit gate.
Circuit	Class for simulating quantum circuits using tensor networks. The class
CircuitMPS	Quantum circuit simulation keeping the state always in a MPS form. If
CircuitPermMPS	Quantum circuit simulation keeping the state always in an MPS form, but
CircuitDense	Quantum circuit simulation keeping the state in full dense form.

Functions

recursive_stack(x)
_convert_ints_and_floats(x)
_put_registers_last(x)
parse_qsim_str(contents)	Parse a 'qsim' input format string into circuit information.
parse_qsim_file(fname, **kwargs)	Parse a qsim file.
parse_qsim_url(url, **kwargs)	Parse a qsim url.
to_clean_list(s, delimiter)	Split, strip and filter a string by a given character into a list.
multi_replace(s, replacements)	Replace multiple substrings in a string.
_openqasm_replace_tokens(s, replacements)	Replace whole identifier-like tokens in an OpenQASM fragment.
get_openqasm2_regexes()
get_openqasm3_regexes()
_openqasm_split_top_level(s[, sep])
_openqasm_eval_expr(expr, env)
_is_interface_placeholder(x)
_placeholder_param_vector(values)
parse_openqasm2_str(contents)	Parse the string contents of an OpenQASM 2.0 file. This parser does not
parse_openqasm2_file(fname, **kwargs)	Parse an OpenQASM 2.0 file.
parse_openqasm2_url(url, **kwargs)	Parse an OpenQASM 2.0 url.
parse_openqasm3_str(contents)	Parse an OpenQASM 3.0 program from a string.
parse_openqasm3_file(fname, **kwargs)	Parse an OpenQASM 3.0 file.
parse_openqasm3_url(url, **kwargs)	Parse an OpenQASM 3.0 program from a URL.
register_constant_gate(name, G, num_qubits[, tag])
register_param_gate(name, param_fn, num_qubits[, tag])
register_special_gate(name, fn, num_qubits[, tag, array])
rx_gate_param_gen(params)
ry_gate_param_gen(params)
rz_gate_param_gen(params)
u3_gate_param_gen(params)
u2_gate_param_gen(params)
u1_gate_param_gen(params)
cu3_param_gen(params)
cu2_param_gen(params)
cu1_param_gen(params)
crx_param_gen(params)	Parametrized controlled X-rotation.
cry_param_gen(params)	Parametrized controlled Y-rotation.
crz_param_gen(params)	Parametrized controlled Z-rotation.
fsim_param_gen(params)
fsimg_param_gen(params)
givens_param_gen(params)
givens2_param_gen(params)
xx_plus_yy_param_gen(params)
xx_minus_yy_param_gen(params)
rxx_param_gen(params)	Parametrized two qubit XX-rotation.
ryy_param_gen(params)	Parametrized two qubit YY-rotation.
rzz_param_gen(params)	Parametrized two qubit ZZ-rotation.
su4_gate_param_gen(params)	See https://arxiv.org/abs/quant-ph/0308006 - Fig. 7.
apply_swap(psi, i, j, **gate_opts)
build_controlled_gate_htn(ncontrol, gate, upper_inds, ...)	Build a low rank hyper tensor network (CP-decomp like) representation of
_apply_controlled_gate_mps(psi, gate[, tags])	Apply a multi-controlled gate to a state represented as an MPS.
_apply_controlled_gate_htn(psi, gate[, tags, ...])
apply_controlled_gate(psi, gate[, tags, contract, ...])
_cached_param_gate_build(fn, params)
sample_bitstring_from_prob_ndarray(p[, seed])	Sample a bitstring from n-dimensional tensor p of probabilities.
rehearsal_dict(tn, tree)
parse_to_gate(gate_id, *gate_args[, params, qubits, ...])	Map all types of gate specification into a Gate object.

Module Contents

quimb.tensor.circuit.recursive_stack(x)

quimb.tensor.circuit._convert_ints_and_floats(x)

quimb.tensor.circuit._put_registers_last(x)

quimb.tensor.circuit.parse_qsim_str(contents)

Parse a ‘qsim’ input format string into circuit information.

The format is described here: https://quantumai.google/qsim/input_format.

Parameters:

contents (str) – The full string of the qsim file.

Returns:

circuit_info – Information about the circuit:

• circuit_info[‘n’]: the number of qubits

• circuit_info[‘n_gates’]: the number of gates in total

• circuit_info[‘gates’]: list[list[str]], list of gates, each of which is a list of strings read from a line of the qsim file.

Return type:

dict

quimb.tensor.circuit.parse_qsim_file(fname, **kwargs)

Parse a qsim file.

quimb.tensor.circuit.parse_qsim_url(url, **kwargs)

Parse a qsim url.

quimb.tensor.circuit.to_clean_list(s, delimiter)

Split, strip and filter a string by a given character into a list.

quimb.tensor.circuit.multi_replace(s, replacements)

Replace multiple substrings in a string.

quimb.tensor.circuit._openqasm_replace_tokens(s, replacements)

Replace whole identifier-like tokens in an OpenQASM fragment.

quimb.tensor.circuit.get_openqasm2_regexes()

quimb.tensor.circuit.get_openqasm3_regexes()

quimb.tensor.circuit._openqasm_split_top_level(s, sep=',')

quimb.tensor.circuit._openqasm_eval_expr(expr, env)

quimb.tensor.circuit._is_interface_placeholder(x)

quimb.tensor.circuit._placeholder_param_vector(values)

quimb.tensor.circuit.parse_openqasm2_str(contents)

Parse the string contents of an OpenQASM 2.0 file. This parser does not support classical control flow is not guaranteed to check the full openqasm grammar.

quimb.tensor.circuit.parse_openqasm2_file(fname, **kwargs)

Parse an OpenQASM 2.0 file.

quimb.tensor.circuit.parse_openqasm2_url(url, **kwargs)

Parse an OpenQASM 2.0 url.

quimb.tensor.circuit.parse_openqasm3_str(contents)

Parse an OpenQASM 3.0 program from a string.

This parser is dependency free and supports a practical subset of OpenQASM 3 for circuit import, including qubit declarations, input declarations, arithmetic expressions, custom gates, and register broadcasting.

Parameters:

contents (str) – The OpenQASM 3 source code to parse.

Returns:

A dictionary describing the circuit with the following entries:

• "n": total number of qubits.

• "sitemap": mapping from OpenQASM qubit names to qubit indices.

• "gates": parsed sequence of Gate objects.

• "n_gates": total number of parsed gates.

• "inputs": tuple of symbolic input names declared with input.

• "symbols": mapping of symbolic names to their current values or symbolic placeholders.

• "expressions": mapping from gate indices to symbolic parameter expressions requiring later binding.

Return type:

dict

Raises:

• NotImplementedError – If the program uses unsupported OpenQASM 3 features such as control flow, calibration blocks, output declarations, or unsupported operations.

• SyntaxError – If the source contains an instruction that does not match the supported grammar subset.

quimb.tensor.circuit.parse_openqasm3_file(fname, **kwargs)

Parse an OpenQASM 3.0 file.

Parameters:

• fname (str or path-like) – Path to the OpenQASM 3 file.

• **kwargs – Forwarded to parse_openqasm3_str().

Returns:

The parsed circuit information returned by parse_openqasm3_str().

Return type:

dict

quimb.tensor.circuit.parse_openqasm3_url(url, **kwargs)

Parse an OpenQASM 3.0 program from a URL.

Parameters:

• url (str) – URL pointing to an OpenQASM 3 source file.

• **kwargs – Forwarded to parse_openqasm3_str().

Returns:

The parsed circuit information returned by parse_openqasm3_str().

Return type:

dict

quimb.tensor.circuit.ALL_GATES

quimb.tensor.circuit.ONE_QUBIT_GATES

quimb.tensor.circuit.TWO_QUBIT_GATES

quimb.tensor.circuit.ALL_PARAM_GATES

quimb.tensor.circuit.ONE_QUBIT_PARAM_GATES

quimb.tensor.circuit.TWO_QUBIT_PARAM_GATES

quimb.tensor.circuit.GATE_TAGS

quimb.tensor.circuit.GATE_SIZE

quimb.tensor.circuit.CONSTANT_GATES

quimb.tensor.circuit.PARAM_GATES

quimb.tensor.circuit.SPECIAL_GATES

quimb.tensor.circuit.register_constant_gate(name, G, num_qubits, tag=None)

quimb.tensor.circuit.register_param_gate(name, param_fn, num_qubits, tag=None)

quimb.tensor.circuit.register_special_gate(name, fn, num_qubits, tag=None, array=None)

quimb.tensor.circuit.rx_gate_param_gen(params)

quimb.tensor.circuit.ry_gate_param_gen(params)

quimb.tensor.circuit.rz_gate_param_gen(params)

quimb.tensor.circuit.u3_gate_param_gen(params)

quimb.tensor.circuit.u2_gate_param_gen(params)

quimb.tensor.circuit.u1_gate_param_gen(params)

quimb.tensor.circuit.cu3_param_gen(params)

quimb.tensor.circuit.cu2_param_gen(params)

quimb.tensor.circuit.cu1_param_gen(params)

quimb.tensor.circuit.crx_param_gen(params)

Parametrized controlled X-rotation.

quimb.tensor.circuit.cry_param_gen(params)

Parametrized controlled Y-rotation.

quimb.tensor.circuit.crz_param_gen(params)

Parametrized controlled Z-rotation.

quimb.tensor.circuit.fsim_param_gen(params)

quimb.tensor.circuit.fsimg_param_gen(params)

quimb.tensor.circuit.givens_param_gen(params)

quimb.tensor.circuit.givens2_param_gen(params)

quimb.tensor.circuit.xx_plus_yy_param_gen(params)

quimb.tensor.circuit.xx_minus_yy_param_gen(params)

quimb.tensor.circuit.rxx_param_gen(params)

Parametrized two qubit XX-rotation.

\[\mathrm{RXX}(\theta) = \exp(-i \frac{\theta}{2} X_i X_j)\]

quimb.tensor.circuit.ryy_param_gen(params)

Parametrized two qubit YY-rotation.

\[\mathrm{RYY}(\theta) = \exp(-i \frac{\theta}{2} Y_i Y_j)\]

quimb.tensor.circuit.rzz_param_gen(params)

Parametrized two qubit ZZ-rotation.

\[\mathrm{RZZ}(\theta) = \exp(-i \frac{\theta}{2} Z_i Z_j)\]

quimb.tensor.circuit.su4_gate_param_gen(params)

See https://arxiv.org/abs/quant-ph/0308006 - Fig. 7. params: # theta1, phi1, lamda1, # theta2, phi2, lamda2, # theta3, phi3, lamda3, # theta4, phi4, lamda4, # t1, t2, t3,

quimb.tensor.circuit._MPS_METHODS

quimb.tensor.circuit.apply_swap(psi, i, j, **gate_opts)

quimb.tensor.circuit.build_controlled_gate_htn(ncontrol, gate, upper_inds, lower_inds, tags_each=None, tags_all=None, bond_ind=None)

Build a low rank hyper tensor network (CP-decomp like) representation of a multi controlled gate.

quimb.tensor.circuit._apply_controlled_gate_mps(psi, gate, tags=None, **gate_opts)

Apply a multi-controlled gate to a state represented as an MPS.

quimb.tensor.circuit._apply_controlled_gate_htn(psi, gate, tags=None, propagate_tags='register', **gate_opts)

quimb.tensor.circuit.apply_controlled_gate(psi, gate, tags=None, contract='auto-split-gate', propagate_tags='register', **gate_opts)

quimb.tensor.circuit._cached_param_gate_build(fn, params)

class quimb.tensor.circuit.Gate(label, params, qubits=None, controls=None, round=None, parametrize=False)

A simple class for storing the details of a quantum circuit gate.

Parameters:

• label (str) – The name or ‘identifier’ of the gate.

• params (Iterable[float]) – The parameters of the gate.

• qubits (Iterable[int], optional) – Which qubits the gate acts on.

• controls (Iterable[int], optional) – Which qubits are the controls.

• round (int, optional) – If given, which round or layer the gate is part of.

• parametrize (bool, optional) – Whether the gate will correspond to a parametrized tensor.

__slots__ = ('_label', '_params', '_qubits', '_controls', '_round', '_parametrize', '_tag', '_special',...

_label

_params

_round

_parametrize = False

_tag

_special

_constant

_array = None

classmethod from_raw(U, qubits=None, controls=None, round=None)

copy()

property label

property params

property qubits

property total_qubit_count

property controls

property round

property special

property parametrize

property tag

copy_with(**kwargs)

Take a copy of this gate but with some attributes changed.

build_array()

Build the array representation of the gate. For controlled gates this excludes the control qubits.

property array

build_mpo(L=None, **kwargs)

Build an MPO representation of this gate.

__repr__()

quimb.tensor.circuit.sample_bitstring_from_prob_ndarray(p, seed=None)

Sample a bitstring from n-dimensional tensor p of probabilities.

Examples

>>> import numpy as np
>>> p = np.zeros(shape=(2, 2, 2, 2, 2))
>>> p[0, 1, 0, 1, 1] = 1.0
>>> sample_bitstring_from_prob_ndarray(p)
'01011'

quimb.tensor.circuit.rehearsal_dict(tn, tree)

quimb.tensor.circuit.parse_to_gate(gate_id, *gate_args, params=None, qubits=None, controls=None, gate_round=None, parametrize=None)

Map all types of gate specification into a Gate object.

class quimb.tensor.circuit.Circuit(N=None, psi0=None, gate_opts=None, gate_contract='auto-split-gate', gate_propagate_tags='register', tags=None, psi0_dtype='complex128', psi0_tag='PSI0', tag_gate_numbers=True, gate_tag_id='GATE_{}', tag_gate_rounds=True, round_tag_id='ROUND_{}', tag_gate_labels=True, bra_site_ind_id='b{}', dtype=None, to_backend=None, convert_eager=False)

Class for simulating quantum circuits using tensor networks. The class keeps a list of Gate objects in sync with a tensor network representing the current state of the circuit.

Parameters:

• N (int, optional) – The number of qubits.

• psi0 (TensorNetwork1DVector, optional) – The initial state, assumed to be |00000....0> if not given. The state is always copied and the tag PSI0 added.

• gate_opts (dict_like, optional) – Default keyword arguments to supply to each gate_TN_1D() call during the circuit.

• gate_contract (str, optional) – Shortcut for setting the default ‘contract’ option in gate_opts.

• gate_propagate_tags (str, optional) – Shortcut for setting the default ‘propagate_tags’ option in gate_opts.

• tags (str or sequence of str, optional) – Tag(s) to add to the initial wavefunction tensors (whether these are propagated to the rest of the circuit’s tensors depends on gate_opts).

• psi0_dtype (str, optional) – Ensure the initial state has this dtype.

• psi0_tag (str, optional) – Ensure the initial state has this tag.

• tag_gate_numbers (bool, optional) – Whether to tag each gate tensor with its number in the circuit, like "GATE_{g}". This is required for updating the circuit parameters.

• gate_tag_id (str, optional) – The format string for tagging each gate tensor, by default e.g. "GATE_{g}".

• tag_gate_rounds (bool, optional) – Whether to tag each gate tensor with its number in the circuit, like "ROUND_{r}".

• round_tag_id (str, optional) – The format string for tagging each round of gates, by default e.g. "ROUND_{r}".

• tag_gate_labels (bool, optional) – Whether to tag each gate tensor with its gate type label, e.g. {"X_1/2", "ISWAP", "CCX", ...}..

• bra_site_ind_id (str, optional) – Use this to label ‘bra’ site indices when creating certain (mostly internal) intermediate tensor networks.

• dtype (str, optional) – A default dtype to perform calculations in. Depending on convert_eager, this is enforced after circuit construction and simplification (the default for exact simulation), or eagerly to the initial state and as gates are applied (the default for MPS simulation).

• to_backend (callable, optional) – If given, apply this function to both the initial state arrays and to every gate as it is applied.

• convert_eager (bool, optional) – Whether to eagerly perform dtype casting and application of to_backend as gates are supplied, or wait until after the necessary TNs for a particular task such as sampling are formed and simplified. Deferred conversion (convert_eager=False) is the default mode for full contraction.

psi

The current circuit wavefunction as a tensor network.

Type:

TensorNetwork1DVector

uni

The current circuit unitary operator as a tensor network.

Type:

TensorNetwork1DOperator

gates

The gates in the circuit.

Type:

tuple[Gate]

Examples

Create 3-qubit GHZ-state:

>>> qc = qtn.Circuit(3)
>>> gates = [
        ('H', 0),
        ('H', 1),
        ('CNOT', 1, 2),
        ('CNOT', 0, 2),
        ('H', 0),
        ('H', 1),
        ('H', 2),
    ]
>>> qc.apply_gates(gates)
>>> qc.psi
<TensorNetwork1DVector(tensors=12, indices=14, L=3, max_bond=2)>

>>> qc.psi.to_dense().round(4)
qarray([[ 0.7071+0.j],
        [ 0.    +0.j],
        [ 0.    +0.j],
        [-0.    +0.j],
        [-0.    +0.j],
        [ 0.    +0.j],
        [ 0.    +0.j],
        [ 0.7071+0.j]])

>>> for b in qc.sample(10):
...     print(b)
000
000
111
000
111
111
000
111
000
000

See also

Gate

tag_gate_numbers = True

tag_gate_rounds = True

tag_gate_labels = True

dtype = None

to_backend = None

convert_eager = False

_backend_gate_cache

gate_opts

_gates = []

_ket_site_ind_id

_bra_site_ind_id = 'b{}'

_gate_tag_id = 'GATE_{}'

_round_tag_id = 'ROUND_{}'

_sample_n_gates = -1

_storage

_sampled_conditionals

_named_params

_named_param_exprs

copy()

Copy the circuit and its state.

_maybe_convert(obj, dtype=None)

apply_to_arrays(fn)

Apply a function to all the arrays in the circuit.

static _normalize_named_param_value(value)

property named_params

Named circuit parameters and their current values.

property named_param_names

Names of registered circuit parameters.

property param_expressions

Gate parameter expressions keyed by gate index.

register_named_params(named_params, gate_expressions=None)

Register named circuit parameters and gate dependencies.

Parameters:

• named_params (sequence[str] or mapping[str, scalar]) – Either names to register, which default to nan until bound, or a mapping supplying initial values.

• gate_expressions (mapping[int, tuple], optional) – Mapping from gate index to the expressions used to generate that gate’s parameters. Each expression can be a constant, a string expression referencing the named parameters, or a callable taking the current named parameter mapping.

_set_gate_params(i, params)

_apply_named_param_updates()

get_params()

Get a pytree - in this case a dict - of all the parameters in the circuit.

Returns:

Dictionary containing any named parameters plus any directly parametrized gates not driven by named parameter expressions.

Return type:

dict

set_params(params)

Set the parameters of the circuit.

Parameters:

params (dict) – Dictionary mapping gate numbers and/or registered named parameter names to new values.

classmethod from_qsim_str(contents, progbar=False, **circuit_opts)

Generate a Circuit instance from a ‘qsim’ string.

classmethod from_qsim_file(fname, progbar=False, **circuit_opts)

Generate a Circuit instance from a ‘qsim’ file.

The qsim file format is described here: https://quantumai.google/qsim/input_format.

classmethod from_qsim_url(url, progbar=False, **circuit_opts)

Generate a Circuit instance from a ‘qsim’ url.

from_qasm

from_qasm_file

from_qasm_url

classmethod from_openqasm2_str(contents, progbar=False, **circuit_opts)

Generate a Circuit instance from an OpenQASM 2.0 string.

classmethod from_openqasm2_file(fname, progbar=False, **circuit_opts)

Generate a Circuit instance from an OpenQASM 2.0 file.

classmethod from_openqasm2_url(url, progbar=False, **circuit_opts)

Generate a Circuit instance from an OpenQASM 2.0 url.

classmethod from_openqasm3_str(contents, progbar=False, **circuit_opts)

Construct a circuit from an OpenQASM 3.0 string.

Parameters:

• contents (str) – The OpenQASM 3 source code to parse.

• progbar (bool, optional) – Whether to show a progress bar while applying the parsed gates.

• **circuit_opts – Options forwarded to the Circuit constructor.

Returns:

A circuit populated with the parsed gates. If symbolic input declarations are present, they are registered as generic named circuit parameters so that set_params() can bind them later.

Return type:

Circuit

classmethod from_openqasm3_file(fname, progbar=False, **circuit_opts)

Construct a circuit from an OpenQASM 3.0 file.

Parameters:

• fname (str or path-like) – Path to the OpenQASM 3 file.

• progbar (bool, optional) – Whether to show a progress bar while applying the parsed gates.

• **circuit_opts – Options forwarded to the Circuit constructor.

Returns:

The parsed circuit instance.

Return type:

Circuit

classmethod from_openqasm3_url(url, progbar=False, **circuit_opts)

Construct a circuit from an OpenQASM 3.0 URL.

Parameters:

• url (str) – URL pointing to an OpenQASM 3 source file.

• progbar (bool, optional) – Whether to show a progress bar while applying the parsed gates.

• **circuit_opts – Options forwarded to the Circuit constructor.

Returns:

The parsed circuit instance.

Return type:

Circuit

classmethod from_gates(gates, N=None, progbar=False, **kwargs)

Generate a Circuit instance from a sequence of gates.

Parameters:

• gates (sequence[Gate] or sequence[tuple]) – The sequence of gates to apply.

• N (int, optional) – The number of qubits. If not given, will be inferred from the gates.

• progbar (bool, optional) – Whether to show a progress bar.

• kwargs – Supplied to the Circuit constructor.

property gates

property num_gates

ket_site_ind(i)

Get the site index for the given qubit.

bra_site_ind(i)

Get the ‘bra’ site index for the given qubit, if forming an operator.

gate_tag(g)

Get the tag for the given gate, indexed linearly.

round_tag(r)

Get the tag for the given round (/layer).

_init_state(N, dtype='complex128')

_apply_gate(gate, tags=None, **gate_opts)

Apply a Gate to this Circuit. This is the main method that all calls to apply a gate should go through.

Parameters:

• gate (Gate) – The gate to apply.

• tags (str or sequence of str, optional) – Tags to add to the gate tensor(s).

apply_gate(gate_id, *gate_args, params=None, qubits=None, controls=None, gate_round=None, parametrize=None, **gate_opts)

Apply a single gate to this tensor network quantum circuit. If gate_round is supplied the tensor(s) added will be tagged with 'ROUND_{gate_round}'. Alternatively, putting an integer first like so:

circuit.apply_gate(10, 'H', 7)

Is automatically translated to:

circuit.apply_gate('H', 7, gate_round=10)

Parameters:

• gate_id (Gate, str, or array_like) –

  Which gate to apply. This can be:

  • A Gate instance, i.e. with parameters and qubits already specified.

  • A string, e.g. 'H', 'U3', etc. in which case gate_args should be supplied with (*params, *qubits).

  • A raw array, in which case gate_args should be supplied with (*qubits,).

• gate_args (list[str]) – The arguments to supply to it.

• gate_round (int, optional) – The gate round. If gate_id is integer-like, will also be taken from here, with then gate_id, gate_args = gate_args[0], gate_args[1:].

• gate_opts – Supplied to the gate function, options here will override the default gate_opts.

apply_gate_raw(U, where, controls=None, gate_round=None, **gate_opts)

Apply the raw array U as a gate on qubits in where. It will be assumed to be unitary for the sake of computing reverse lightcones.

apply_gates(gates, progbar=False, **gate_opts)

Apply a sequence of gates to this tensor network quantum circuit.

Parameters:

• gates (Sequence[Gate] or Sequence[Tuple]) – The sequence of gates to apply.

• gate_opts – Supplied to apply_gate().

h(i, gate_round=None, **kwargs)

x(i, gate_round=None, **kwargs)

y(i, gate_round=None, **kwargs)

z(i, gate_round=None, **kwargs)

s(i, gate_round=None, **kwargs)

sdg(i, gate_round=None, **kwargs)

t(i, gate_round=None, **kwargs)

tdg(i, gate_round=None, **kwargs)

sx(i, gate_round=None, **kwargs)

sxdg(i, gate_round=None, **kwargs)

x_1_2(i, gate_round=None, **kwargs)

y_1_2(i, gate_round=None, **kwargs)

z_1_2(i, gate_round=None, **kwargs)

w_1_2(i, gate_round=None, **kwargs)

hz_1_2(i, gate_round=None, **kwargs)

cnot(i, j, gate_round=None, **kwargs)

cx(i, j, gate_round=None, **kwargs)

cy(i, j, gate_round=None, **kwargs)

cz(i, j, gate_round=None, **kwargs)

iswap(i, j, gate_round=None, **kwargs)

iden(i, gate_round=None)

swap(i, j, gate_round=None, **kwargs)

rx(theta, i, gate_round=None, parametrize=False, **kwargs)

ry(theta, i, gate_round=None, parametrize=False, **kwargs)

rz(theta, i, gate_round=None, parametrize=False, **kwargs)

u3(theta, phi, lamda, i, gate_round=None, parametrize=False, **kwargs)

u2(phi, lamda, i, gate_round=None, parametrize=False, **kwargs)

u1(lamda, i, gate_round=None, parametrize=False, **kwargs)

phase(lamda, i, gate_round=None, parametrize=False, **kwargs)

cu3(theta, phi, lamda, i, j, gate_round=None, parametrize=False, **kwargs)

cu2(phi, lamda, i, j, gate_round=None, parametrize=False, **kwargs)

cu1(lamda, i, j, gate_round=None, parametrize=False, **kwargs)

cphase(lamda, i, j, gate_round=None, parametrize=False, **kwargs)

fsim(theta, phi, i, j, gate_round=None, parametrize=False, **kwargs)

fsimg(theta, zeta, chi, gamma, phi, i, j, gate_round=None, parametrize=False, **kwargs)

givens(theta, i, j, gate_round=None, parametrize=False, **kwargs)

givens2(theta, phi, i, j, gate_round=None, parametrize=False, **kwargs)

xx_plus_yy(theta, beta, i, j, gate_round=None, parametrize=False, **kwargs)

xx_minus_yy(theta, beta, i, j, gate_round=None, parametrize=False, **kwargs)

rxx(theta, i, j, gate_round=None, parametrize=False, **kwargs)

ryy(theta, i, j, gate_round=None, parametrize=False, **kwargs)

rzz(theta, i, j, gate_round=None, parametrize=False, **kwargs)

crx(theta, i, j, gate_round=None, parametrize=False, **kwargs)

cry(theta, i, j, gate_round=None, parametrize=False, **kwargs)

crz(theta, i, j, gate_round=None, parametrize=False, **kwargs)

su4(theta1, phi1, lamda1, theta2, phi2, lamda2, theta3, phi3, lamda3, theta4, phi4, lamda4, t1, t2, t3, i, j, gate_round=None, parametrize=False, **kwargs)

ccx(i, j, k, gate_round=None, **kwargs)

ccnot(i, j, k, gate_round=None, **kwargs)

toffoli(i, j, k, gate_round=None, **kwargs)

ccy(i, j, k, gate_round=None, **kwargs)

ccz(i, j, k, gate_round=None, **kwargs)

cswap(i, j, k, gate_round=None, **kwargs)

fredkin(i, j, k, gate_round=None, **kwargs)

property psi

Tensor network representation of the wavefunction.

get_uni(transposed=False)

Tensor network representation of the unitary operator (i.e. with the initial state removed).

property uni

get_reverse_lightcone_tags(where)

Get the tags of gates in this circuit corresponding to the ‘reverse’ lightcone propagating backwards from registers in where.

Parameters:

where (int or sequence of int) – The register or register to get the reverse lightcone of.

Returns:

The sequence of gate tags (GATE_{i}, …) corresponding to the lightcone.

Return type:

tuple[str]

get_psi_reverse_lightcone(where, keep_psi0=False)

Get just the bit of the wavefunction in the reverse lightcone of sites in where - i.e. causally linked.

Parameters:

• where (int, or sequence of int) – The sites to propagate the the lightcone back from, supplied to get_reverse_lightcone_tags().

• keep_psi0 (bool, optional) – Keep the tensors corresponding to the initial wavefunction regardless of whether they are outside of the lightcone.

Returns:

psi_lc

Return type:

TensorNetwork1DVector

clear_storage()

Clear all cached data.

_maybe_init_storage()

get_psi_simplified(seq='ADCRS', atol=1e-12, equalize_norms=False)

Get the full wavefunction post local tensor network simplification.

Parameters:

• seq (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

Returns:

psi

Return type:

TensorNetwork1DVector

get_rdm_lightcone_simplified(where, seq='ADCRS', atol=1e-12, equalize_norms=False)

Get a simplified TN of the norm of the wavefunction, with gates outside reverse lightcone of where cancelled, and physical indices within where preserved so that they can be fixed (sliced) or used as output indices.

Parameters:

• where (int or sequence of int) – The region assumed to be the target density matrix essentially. Supplied to get_reverse_lightcone_tags().

• seq (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

Return type:

TensorNetwork

amplitude(b, optimize='auto-hq', simplify_sequence='ADCRS', simplify_atol=1e-12, simplify_equalize_norms=True, backend=None, dtype=None, rehearse=False)

Get the amplitude coefficient of bitstring b.

\[c_b = \langle b | \psi \rangle\]

Parameters:

• b (str or sequence of int) – The bitstring to compute the transition amplitude for.

• optimize (str, optional) – Contraction path optimizer to use for the amplitude, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• backend (str, optional) – Backend to perform the contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• rehearse (bool or "tn", optional) – If True, generate and cache the simplified tensor network and contraction tree but don’t actually perform the contraction. Returns a dict with keys "tn" and 'tree' with the tensor network that will be contracted and the corresponding contraction tree if so.

amplitude_rehearse(b='random', simplify_sequence='ADCRS', simplify_atol=1e-12, simplify_equalize_norms=True, optimize='auto-hq', dtype=None, rehearse=True)

Perform just the tensor network simplifications and contraction tree finding associated with computing a single amplitude (caching the results) but don’t perform the actual contraction.

Parameters:

• b ('random', str or sequence of int) – The bitstring to rehearse computing the transition amplitude for, if 'random' (the default) a random bitstring will be used.

• optimize (str, optional) – Contraction path optimizer to use for the marginal, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

Return type:

dict

amplitude_tn

partial_trace(keep, optimize='auto-hq', simplify_sequence='ADCRS', simplify_atol=1e-12, simplify_equalize_norms=True, backend=None, dtype=None, rehearse=False)

Perform the partial trace on the circuit wavefunction, retaining only qubits in keep, and making use of reverse lightcone cancellation:

\[\rho_{\bar{q}} = Tr_{\bar{p}} |\psi_{\bar{q}} \rangle \langle \psi_{\bar{q}}|\]

Where \(\bar{q}\) is the set of qubits to keep, \(\psi_{\bar{q}}\) is the circuit wavefunction only with gates in the causal cone of this set, and \(\bar{p}\) is the remaining qubits.

Parameters:

• keep (int or sequence of int) – The qubit(s) to keep as we trace out the rest.

• optimize (str, optional) – Contraction path optimizer to use for the reduced density matrix, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• rehearse (bool or "tn", optional) – If True, generate and cache the simplified tensor network and contraction tree but don’t actually perform the contraction. Returns a dict with keys "tn" and 'tree' with the tensor network that will be contracted and the corresponding contraction tree if so.

Return type:

array or dict

partial_trace_rehearse

partial_trace_tn

local_expectation(G, where, optimize='auto-hq', simplify_sequence='ADCRS', simplify_atol=1e-12, simplify_equalize_norms=True, backend=None, dtype=None, rehearse=False)

Compute the a single expectation value of operator G, acting on sites where, making use of reverse lightcone cancellation.

\[\langle \psi_{\bar{q}} | G_{\bar{q}} | \psi_{\bar{q}} \rangle\]

where \(\bar{q}\) is the set of qubits \(G\) acts one and \(\psi_{\bar{q}}\) is the circuit wavefunction only with gates in the causal cone of this set. If you supply a tuple or list of gates then the expectations will be computed simultaneously.

Parameters:

• G (array or sequence[array]) – The raw operator(s) to find the expectation of.

• where (int or sequence of int) – Which qubits the operator acts on.

• optimize (str, optional) – Contraction path optimizer to use for the local expectation, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• gate_opts (None or dict_like) – Options to use when applying G to the wavefunction.

• rehearse (bool or "tn", optional) – If True, generate and cache the simplified tensor network and contraction tree but don’t actually perform the contraction. Returns a dict with keys 'tn' and 'tree' with the tensor network that will be contracted and the corresponding contraction tree if so.

Return type:

scalar, tuple[scalar] or dict

local_expectation_rehearse

local_expectation_tn

compute_marginal(where, fix=None, optimize='auto-hq', backend=None, dtype='complex64', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True, rehearse=False)

Compute the probability tensor of qubits in where, given possibly fixed qubits in fix and tracing everything else having removed redundant unitary gates.

Parameters:

• where (sequence of int) – The qubits to compute the marginal probability distribution of.

• fix (None or dict[int, str], optional) – Measurement results on other qubits to fix.

• optimize (str, optional) – Contraction path optimizer to use for the marginal, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• rehearse (bool or "tn", optional) – Whether to perform the marginal contraction or just return the associated TN and contraction tree.

compute_marginal_rehearse

compute_marginal_tn

calc_qubit_ordering(qubits=None, method='greedy-lightcone')

Get a order to measure qubits in, by greedily choosing whichever has the smallest reverse lightcone followed by whichever expands this lightcone least.

Parameters:

qubits (None or sequence of int) – The qubits to generate a lightcone ordering for, if None, assume all qubits.

Returns:

The order to ‘measure’ qubits in.

Return type:

tuple[int]

_parse_qubits_order(qubits=None, order=None)

Simply initializes the default of measuring all qubits, and the default order, or checks that order is a permutation of qubits.

_group_order(order, group_size=1)

Take the qubit ordering order and batch it in groups of size group_size, sorting the qubits (for caching reasons) within each group.

get_qubit_distances(method='dijkstra', alpha=2)

Get a nested dictionary of qubit distances. This is computed from a graph representing qubit interactions. The graph has an edge between qubits if they are acted on by the same gate, and the distance-weight of the edge is exponentially small in the number of gates between them.

Parameters:

• method ({'dijkstra', 'resistance'}, optional) – The method to use to compute the qubit distances. See networkx.all_pairs_dijkstra_path_length() and networkx.resistance_distance().

• alpha (float, optional) – The distance weight between qubits is alpha**(num_gates - 1 ).

Returns:

The distance between each pair of qubits, accessed like distances[q1][q2]. If two qubits are not connected, the distance is missing.

Return type:

dict[int, dict[int, float]]

reordered_gates_dfs_clustered()

Get the gates reordered by a depth first search traversal of the multi-qubit gate graph that greedily selects successive gates which are ‘close’ in graph distance, and shifts single qubit gates to be adjacent to multi-qubit gates where possible.

sample(C, qubits=None, order=None, group_size=10, max_marginal_storage=2**20, seed=None, optimize='auto-hq', backend=None, dtype='complex64', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True)

Sample the circuit given by gates, C times, using lightcone cancelling and caching marginal distribution results. This is a generator. This proceeds as a chain of marginal computations.

Assuming we have group_size=1, and some ordering of the qubits, \(\{q_0, q_1, q_2, q_3, \ldots\}\) we first compute:

\[p(q_0) = \mathrm{diag} \mathrm{Tr}_{1, 2, 3,\ldots} | \psi_{0} \rangle \langle \psi_{0} |\]

I.e. simply the probability distribution on a single qubit, conditioned on nothing. The subscript on \(\psi\) refers to the fact that we only need gates from the causal cone of qubit 0. From this we can sample an outcome, either 0 or 1, if we call this \(r_0\) we can then move on to the next marginal:

\[p(q_1 | r_0) = \mathrm{diag} \mathrm{Tr}_{2, 3,\ldots} \langle r_0 | \psi_{0, 1} \rangle \langle \psi_{0, 1} | r_0 \rangle\]

I.e. the probability distribution of the next qubit, given our prior result. We can sample from this to get \(r_1\). Then we compute:

\[p(q_2 | r_0 r_1) = \mathrm{diag} \mathrm{Tr}_{3,\ldots} \langle r_0 r_1 | \psi_{0, 1, 2} \rangle \langle \psi_{0, 1, 2} | r_0 r_1 \rangle\]

Eventually we will reach the ‘final marginal’, which we can compute as

\[|\langle r_0 r_1 r_2 r_3 \ldots | \psi \rangle|^2\]

since there is nothing left to trace out.

Parameters:

• C (int) – The number of times to sample.

• qubits (None or sequence of int, optional) – Which qubits to measure, defaults (None) to all qubits.

• order (None or sequence of int, optional) – Which order to measure the qubits in, defaults (None) to an order based on greedily expanding the smallest reverse lightcone. If specified it should be a permutation of qubits.

• group_size (int, optional) – How many qubits to group together into marginals, the larger this is the fewer marginals need to be computed, which can be faster at the cost of higher memory. The marginal themselves will each be of size 2**group_size.

• max_marginal_storage (int, optional) – The total cumulative number of marginal probabilites to cache, once this is exceeded caching will be turned off.

• seed (None or int, optional) – A random seed, passed to numpy.random.seed if given.

• optimize (str, optional) – Contraction path optimizer to use for the marginals, shouldn’t be a non-reusable path optimizer as called on many different TNs. Passed to cotengra.array_contract_tree().

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

Yields:

bitstrings (sequence of str)

sample_rehearse(qubits=None, order=None, group_size=10, result=None, optimize='auto-hq', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True, rehearse=True, progbar=False)

Perform the preparations and contraction tree findings for sample(), caching various intermedidate objects, but don’t perform the main contractions.

Parameters:

• qubits (None or sequence of int, optional) – Which qubits to measure, defaults (None) to all qubits.

• order (None or sequence of int, optional) – Which order to measure the qubits in, defaults (None) to an order based on greedily expanding the smallest reverse lightcone.

• group_size (int, optional) – How many qubits to group together into marginals, the larger this is the fewer marginals need to be computed, which can be faster at the cost of higher memory. The marginal’s size itself is exponential in group_size.

• result (None or dict[int, str], optional) – Explicitly check the computational cost of this result, assumed to be all zeros if not given.

• optimize (str, optional) – Contraction path optimizer to use for the marginals, shouldn’t be a non-reusable path optimizer as called on many different TNs. Passed to cotengra.array_contract_tree().

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• progbar (bool, optional) – Whether to show the progress of finding each contraction tree.

Returns:

One contraction tree object per grouped marginal computation. The keys of the dict are the qubits the marginal is computed for, the values are a dict containing a representative simplified tensor network (key: ‘tn’) and the main contraction tree (key: ‘tree’).

Return type:

dict[tuple[int], dict]

sample_tns

sample_chaotic(C, marginal_qubits, fix=None, max_marginal_storage=2**20, seed=None, optimize='auto-hq', backend=None, dtype='complex64', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True)

Sample from this circuit, assuming it to be chaotic. Which is to say, only compute and sample correctly from the final marginal, assuming that the distribution on the other qubits is uniform. Given marginal_qubits=5 for instance, for each sample a random bit-string \(r_0 r_1 r_2 \ldots r_{N - 6}\) for the remaining \(N - 5\) qubits will be chosen, then the final marginal will be computed as

\[p(q_{N-5}q_{N-4}q_{N-3}q_{N-2}q_{N-1} | r_0 r_1 r_2 \ldots r_{N-6}) = |\langle r_0 r_1 r_2 \ldots r_{N - 6} | \psi \rangle|^2\]

and then sampled from. Note the expression on the right hand side has 5 open indices here and so is a tensor, however if marginal_qubits is not too big then the cost of contracting this is very similar to a single amplitude.

Note

This method assumes the circuit is chaotic, if its not, then the samples produced will not be an accurate representation of the probability distribution.

Parameters:

• C (int) – The number of times to sample.

• marginal_qubits (int or sequence of int) – The number of qubits to treat as marginal, or the actual qubits. If an int is given then the qubits treated as marginal will be circuit.calc_qubit_ordering()[:marginal_qubits].

• fix (None or dict[int, str], optional) – Measurement results on other qubits to fix. These will be randomly sampled if fix is not given or a qubit is missing.

• seed (None or int, optional) – A random seed, passed to numpy.random.seed if given.

• optimize (str, optional) – Contraction path optimizer to use for the marginal, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

Yields:

str

sample_chaotic_rehearse(marginal_qubits, result=None, optimize='auto-hq', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True, dtype='complex64', rehearse=True)

Rehearse chaotic sampling (perform just the TN simplifications and contraction tree finding).

Parameters:

• marginal_qubits (int or sequence of int) – The number of qubits to treat as marginal, or the actual qubits. If an int is given then the qubits treated as marginal will be circuit.calc_qubit_ordering()[:marginal_qubits].

• result (None or dict[int, str], optional) – Explicitly check the computational cost of this result, assumed to be all zeros if not given.

• optimize (str, optional) – Contraction path optimizer to use for the marginal, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• dtype (str, optional) – Data type to cast the TN to before contraction.

Returns:

The contraction path information for the main computation, the key is the qubits that formed the final marginal. The value is itself a dict with keys 'tn' - a representative tensor network - and 'tree' - the contraction tree.

Return type:

dict[tuple[int], dict]

sample_chaotic_tn

get_gate_by_gate_circuits(group_size=10)

Get a sequence of circuits by partitioning the gates into groups such circuit i + 1 acts on at most group_size new qubits compared to circuit i.

Parameters:

group_size (int, optional) – The maximum number of new qubits that can be acted on by a circuit compared to its predecessor.

Returns:

A sequence of dicts, each with keys 'circuit' and 'where', where the former is a Circuit and the latter the tuple of new qubits that it acts on comparaed to the previous circuit.

Return type:

Sequence[dict]

sample_gate_by_gate(C, group_size=10, seed=None, max_marginal_storage=2**20, optimize='auto-hq', backend=None, dtype='complex64', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True)

Sample this circuit using the gate-by-gate method, where we ‘evolve’ a result bitstring by sequentially including more and more gates, at each step updating the result by computing a full conditional marginal. See “How to simulate quantum measurement without computing marginals” by Sergey Bravyi, David Gosset, Yinchen Liu (https://arxiv.org/abs/2112.08499). The overall complexity of this is guaranteed to be similar to that of computing a single amplitude which can be much better than the naive “qubit-by-qubit” (.sample) method. However, it requires evaluting a number of tensor networks that scales linearly with the number of gates which can offset any practical advantages for shallow circuits for example.

Parameters:

• C (int) – The number of samples to generate.

• group_size (int, optional) – The maximum number of qubits that can be acted on by a circuit compared to its predecessor. This will be the dimension of the marginal computed at each step.

• seed (None or int, optional) – A random seed, passed to numpy.random.seed if given.

• max_marginal_storage (int, optional) – The total cumulative number of marginal probabilites to cache, once this is exceeded caching will be turned off.

• optimize (str, optional) – Contraction path optimizer to use for the marginals, shouldn’t be a non-reusable path optimizer as called on many different TNs. Passed to cotengra.array_contract_tree().

• backend (str, optional) – Backend to perform the marginal contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype (str, optional) – Data type to cast the TN to before contraction.

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• rehearse (bool, optional) – If True, generate and cache the simplified tensor network and contraction tree but don’t actually perform the contraction. Returns a dict with keys 'tn' and 'tree' with the tensor network that will be contracted and the corresponding contraction tree if so.

Yields:

str

sample_gate_by_gate_rehearse(group_size=10, optimize='auto-hq', dtype='complex64', simplify_sequence='ADCRS', simplify_atol=1e-06, simplify_equalize_norms=True, rehearse=True, progbar=False)

Perform the preparations and contraction tree findings for sample_gate_by_gate(), caching various intermedidate objects, but don’t perform the main contractions.

Parameters:

• group_size (int, optional) – The maximum number of qubits that can be acted on by a circuit compared to its predecessor. This will be the dimension of the marginal computed at each step.

• optimize (str, optional) – Contraction path optimizer to use for the marginals, shouldn’t be a non-reusable path optimizer as called on many different TNs. Passed to cotengra.array_contract_tree().

• dtype (str, optional) – Data type to cast the TN to before contraction.

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• rehearse (True or "tn", optional) – If True, generate and cache the simplified tensor network and contraction tree but don’t actually perform the contraction. If “tn”, only generate the simplified tensor networks.

Return type:

Sequence[dict] or Sequence[TensorNetwork]

sample_gate_by_gate_tns

to_dense(reverse=False, optimize='auto-hq', simplify_sequence='R', simplify_atol=1e-12, simplify_equalize_norms=True, backend=None, dtype=None, rehearse=False)

Generate the dense representation of the final wavefunction.

Parameters:

• reverse (bool, optional) – Whether to reverse the order of the subsystems, to match the convention of qiskit for example.

• optimize (str, optional) – Contraction path optimizer to use for the contraction, can be a non-reusable path optimizer as only called once (though path won’t be cached for later use in that case).

• dtype (str, optional) – If given, convert the tensors to this dtype prior to contraction.

• simplify_sequence (str, optional) – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• simplify_equalize_norms (bool, optional) – Actively renormalize tensor norms during simplification.

• backend (str, optional) – Backend to perform the contraction with, e.g. 'numpy', 'cupy' or 'jax'. Passed to cotengra.

• dtype – Data type to cast the TN to before contraction.

• rehearse (bool, optional) – If True, generate and cache the simplified tensor network and contraction tree but don’t actually perform the contraction. Returns a dict with keys 'tn' and 'tree' with the tensor network that will be contracted and the corresponding contraction tree if so.

Returns:

psi – The densely represented wavefunction with dtype data.

Return type:

qarray

to_dense_rehearse

to_dense_tn

simulate_counts(C, seed=None, reverse=False, **to_dense_opts)

Simulate measuring all qubits in the computational basis many times. Unlike sample(), this generates all the samples simultaneously using the full wavefunction constructed from to_dense(), then calling simulate_counts().

Warning

Because this constructs the full wavefunction it always requires exponential memory in the number of qubits, regardless of circuit depth and structure.

Parameters:

• C (int) – The number of ‘experimental runs’, i.e. total counts.

• seed (int, optional) – A seed for reproducibility.

• reverse (bool, optional) – Whether to reverse the order of the subsystems, to match the convention of qiskit for example.

• to_dense_opts – Suppled to to_dense().

Returns:

results – The number of recorded counts for each

Return type:

dict[str, int]

schrodinger_contract(*args, **contract_opts)

xeb(samples_or_counts, cache=None, cache_maxsize=2**20, progbar=False, **amplitude_opts)

Compute the linear cross entropy benchmark (XEB) for samples or counts, amplitude per amplitude.

Parameters:

• samples_or_counts (Iterable[str] or Dict[str, int]) – Either the raw bitstring samples or a dict mapping bitstrings to the number of counts observed.

• cache (dict, optional) – A dictionary to store the probabilities in, if not supplied quimb.utils.LRU(cache_maxsize) will be used.

• cache_maxsize – The maximum size of the cache to be used.

• optional – The maximum size of the cache to be used.

• progbar – Whether to show progress as the bitstrings are iterated over.

• optional – Whether to show progress as the bitstrings are iterated over.

• amplitude_opts – Supplied to amplitude().

xeb_ex(optimize='auto-hq', simplify_sequence='R', simplify_atol=1e-12, simplify_equalize_norms=True, dtype=None, backend=None, autojit=False, progbar=False, **contract_opts)

Compute the exactly expected XEB for this circuit. The main feature here is that if you supply a cotengra optimizer that searches for sliced indices then the XEB will be computed without constructing the full wavefunction.

Parameters:

• optimize (str or PathOptimizer, optional) – Contraction path optimizer.

• simplify_sequence (str, optional) – Simplifications to apply to tensor network prior to contraction.

• simplify_sequence – Which local tensor network simplifications to perform and in which order, see full_simplify().

• simplify_atol (float, optional) – The tolerance with which to compare to zero when applying full_simplify().

• dtype (str, optional) – Data type to cast the TN to before contraction.

• backend (str, optional) – Convert tensors to, and then use contractions from, this library.

• autojit (bool, optional) – Apply autoray.autojit to the contraciton and map-reduce.

• progbar (bool, optional) – Show progress in terms of number of wavefunction chunks processed.

update_params_from(tn)

Assuming tn is a tensor network with tensors tagged GATE_{i} corresponding to this circuit (e.g. from circ.psi or circ.uni) but with updated parameters, update the current circuit parameters and tensors with those values.

This is an inplace modification of the Circuit.

Parameters:

tn (TensorNetwork) – The tensor network to find the updated parameters from.

draw(figsize=None, radius=1 / 3, drawcolor=(0.5, 0.5, 0.5), linewidth=1)

Draw a simple linear schematic of the circuit.

Parameters:

• figsize (tuple, optional) – The size of the figure, if not given will be set based on the number of gates and qubits.

• radius (float, optional) – The radius of the gates.

• drawcolor (tuple, optional) – The color of the wires.

• linewidth (float, optional) – The linewidth of the wires.

Returns:

• fig (matplotlib.Figure) – The figure object.

• ax (matplotlib.Axes) – The axis object.

__repr__()

class quimb.tensor.circuit.CircuitMPS(N=None, *, psi0=None, max_bond=None, cutoff=1e-10, gate_opts=None, gate_contract='auto-mps', dtype=None, to_backend=None, convert_eager=True, **circuit_opts)

Bases: Circuit

Quantum circuit simulation keeping the state always in a MPS form. If you think the circuit will not build up much entanglement, or you just want to keep a rigorous handle on how much entanglement is present, this can be useful.

Parameters:

• N (int, optional) – The number of qubits in the circuit.

• psi0 (TensorNetwork1DVector, optional) – The initial state, assumed to be |00000....0> if not given. The state is always copied and the tag PSI0 added.

• max_bond (int, optional) – The maximum bond dimension to truncate to when applying gates, if any. This is simply a shortcut for setting gate_opts['max_bond'].

• cutoff (float, optional) – The singular value cutoff to use when truncating the state. This is simply a shortcut for setting gate_opts['cutoff'].

• gate_opts (dict, optional) – Default options to pass to each gate, for example, “max_bond” and “cutoff” etc.

• gate_contract (str, optional) –

  The default method for applying gates. Relevant MPS options are:

  • 'auto-mps': automatically choose a method that maintains the MPS form (default). This uses 'swap+split' for 2-qubit gates and 'nonlocal' for 3+ qubit gates.

  • 'swap+split': swap nonlocal qubits to be next to each other, before applying the gate, then swapping them back

  • 'nonlocal': turn the gate into a potentially nonlocal (sub) MPO and apply it directly. See tensor_network_1d_compress().

• dtype (str, optional) – The data type to use for the state tensor.

• to_backend (callable, optional) – A function to convert tensor data to a particular backend.

• convert_eager (bool, optional) – Whether to eagerly perform dtype casting and application of to_backend as gates are supplied, or wait until after the necessary TNs for a particular task such as sampling are formed and simplified. Eager conversion (convert_eager=True) is the default mode for MPS simulation, unlike full contraction.

• circuit_opts – Supplied to Circuit.

psi

The current state of the circuit, always in MPS form.

Type:

MatrixProductState

Examples

Create a circuit object that always uses the “nonlocal” method for contracting in gates, and the “dm” compression method within that, using a large cutoff and maximum bond dimension:

circ = qtn.CircuitMPS(
    N=56,
    gate_opts=dict(
        contract="nonlocal",
        method="dm",
        max_bond=1024,
        cutoff=1e-3,
    )
)

_init_state(N, dtype='complex128')

apply_gates(gates, progbar=False, **gate_opts)

Apply a sequence of gates to this tensor network quantum circuit.

Parameters:

• gates (Sequence[Gate] or Sequence[Tuple]) – The sequence of gates to apply.

• gate_opts – Supplied to apply_gate().

property psi

Tensor network representation of the wavefunction.

property uni

calc_qubit_ordering(qubits=None)

MPS already has a natural ordering.

get_psi_reverse_lightcone(where, keep_psi0=False)

Override get_psi_reverse_lightcone as for an MPS the lightcone is not meaningful.

sample(C, seed=None, dtype=None, *, qubits=None, order=None, group_size=None, max_marginal_storage=None, optimize=None, backend=None, simplify_sequence=None, simplify_atol=None, simplify_equalize_norms=None)

Sample the MPS circuit C times.

Parameters:

• C (int) – The number of samples to generate.

• seed (None, int, or generator, optional) – A random seed or generator to use for reproducibility.

fidelity_estimate()

Estimate the fidelity of the current state based on its norm, which tracks how much the state has been truncated:

\[\tilde{F} = \left| \langle \psi | \psi \rangle \right|^2 \approx \left|\langle \psi_\mathrm{ideal} | \psi \rangle\right|^2\]

See also

error_estimate

error_estimate()

Estimate the error in the current state based on the norm of the discarded part of the state:

\[\epsilon = 1 - \tilde{F}\]

See also

fidelity_estimate

local_expectation(G, where, normalized=False, dtype=None, *, simplify_sequence=None, simplify_atol=None, simplify_equalize_norms=None, backend=None, rehearse=None, **contract_opts)

Compute the local expectation value of a local operator at where (via forming the reduced density matrix). Note this moves the orthogonality around inplace, and records it in info.

Parameters:

• G (Tensor) – The local operator tensor.

• where (int) – The qubit to compute the expectation value at.

• normalized (bool, optional) – Whether to normalize the expectation value by the norm of the state.

• dtype (dtype, optional) – If given, ensure the TN is cast to this dtype before contracting.

Return type:

float

class quimb.tensor.circuit.CircuitPermMPS(N=None, psi0=None, gate_opts=None, gate_contract='swap+split', **circuit_opts)

Bases: CircuitMPS

Quantum circuit simulation keeping the state always in an MPS form, but lazily tracking the qubit ordering rather than ‘swapping back’ qubits after applying non-local gates. This can be useful for circuits with no expectation of locality. The qubit ordering is always tracked in the attribute qubits. The psi attribute returns the TN with the sites reindexed and retagged according to the current qubit ordering, meaning it is no longer an MPS. Use circ.get_psi_unordered() to get the unpermuted MPS and use circ.qubits to get the current qubit ordering if you prefer.

qubits

_apply_gate(gate, tags=None, **gate_opts)

Apply a Gate to this Circuit. This is the main method that all calls to apply a gate should go through.

Parameters:

• gate (Gate) – The gate to apply.

• tags (str or sequence of str, optional) – Tags to add to the gate tensor(s).

calc_qubit_ordering(qubits=None)

Given by the current qubit permutation.

get_psi_unordered()

Return the MPS representing the state but without reordering the sites.

sample(C, seed=None, dtype=None)

Sample the PermMPS circuit C times.

Parameters:

• C (int) – The number of samples to generate.

• seed (None, int, or generator, optional) – A random seed or generator to use for reproducibility.

Yields:

str – The next sample bitstring.

property psi

Tensor network representation of the wavefunction.

class quimb.tensor.circuit.CircuitDense(N=None, psi0=None, gate_opts=None, gate_contract=True, tags=None, convert_eager=True, **circuit_opts)

Bases: Circuit

Quantum circuit simulation keeping the state in full dense form.

property psi

Tensor network representation of the wavefunction.

property uni

calc_qubit_ordering(qubits=None)

Qubit ordering doesn’t matter for a dense wavefunction.

get_psi_reverse_lightcone(where, keep_psi0=False)

Override get_psi_reverse_lightcone as for a dense wavefunction the lightcone is not meaningful.