quimb.tensor.circuit.mps

Matrix-product-state circuit simulators.

Classes

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

CircuitMPSLazy

Quantum circuit simulation keeping the state always in an MPS form, but

Module Contents

class quimb.tensor.circuit.mps.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)[source]

Bases: quimb.tensor.circuit.exact.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')[source]
apply_gates(gates, progbar=False, **gate_opts)[source]

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)[source]

MPS already has a natural ordering.

get_psi_reverse_lightcone(where, keep_psi0=False)[source]

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)[source]

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()[source]

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()[source]

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)[source]

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.mps.CircuitPermMPS(N=None, psi0=None, gate_opts=None, gate_contract='swap+split', **circuit_opts)[source]

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)[source]

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)[source]

Given by the current qubit permutation.

get_psi_unordered()[source]

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

sample(C, seed=None, dtype=None)[source]

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.

to_dense(reverse=False, optimize='auto-hq', backend=None, dtype=None)[source]

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

amplitude(b, optimize='auto-hq', backend=None, dtype=None)[source]

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.

local_expectation(G, where, *args, **kwargs)[source]

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.mps.CircuitMPSLazy(N=None, *, psi0=None, max_bond=None, cutoff=1e-10, compress_opts=None, method='dm', compress_every=2, dtype=None, to_backend=None, convert_eager=True, **circuit_opts)[source]

Bases: CircuitMPS

Quantum circuit simulation keeping the state always in an MPS form, but lazily applying gates (via sub-MPO representation) and regularly contracting and compressing the gates with the state using tensor_network_1d_compress(). This is in contrast to the TEBD approach of eagerly applying gates and then compressing which is used in CircuitMPS.

The periodicity of compression is arbitrary and can be tuned with compress_every, and one can find a goldilocks point for fastest runtime. This circuit class is best utilized for long-range gates, and provides a speedup over CircuitMPS when using "src" compression method.

Note gate_contract is obsolete for this class as 2+ qubit gates are lazily applied via "nonlocal" and 1 qubit gates are eagerly applied via True.

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.

  • compress_opts (dict, optional) – Default options to pass to tensor_network_1d_compress(), for example, “method”, “max_bond” and “cutoff” etc.

  • method (str, optional) – The method to use for compressing the state with the gates, passed to tensor_network_1d_compress(), e.g. "dm" for density matrix truncation, "src" for successive randomized compression, or "direct" for direct SVD truncation.

  • compress_every (int, optional) – How many gates to apply to any qubit before contracting and compressing the state with the gates.

  • 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 “src” compression method using maximum bond dimension and compressing when 5 gates are applied to any qubit:

circ = qtn.CircuitMPSLazy(
    N=56,
    max_bond=1024,
    cutoff=0.0,
    compress_every=5,
    method="src",
)
compress_opts
_uncompressed_sites
compress_every = 2
property max_bond
property cutoff
property method
_compress()[source]

Compress the current state by contracting in all gates and then applying the specified compression method via tensor_network_1d_compress().

_apply_gate(gate, tags=None, **gate_opts)[source]

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

property psi

Tensor network representation of the wavefunction.

sample(C, *args, **kwargs)[source]

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.

local_expectation(G, where, *args, **kwargs)[source]

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

fidelity_estimate()[source]

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