qpe_toolbox.circuit.mpo_circuit_transpilation¶

Attributes¶

list_paulis

Functions¶

`exp_Pauli_string_as_MPO`(ham_term, n_qubits, *, theta)	Construct the MPO representation of the unitary exponential of a Pauli string.
`trotter1_approx_as_MPO`(ham_terms, n_qubits, *, dt, ...)	Construct the first-order Trotter-Suzuki approximation as a Matrix Product Operator (MPO).
`trotter2_approx_as_MPO`(ham_terms, n_qubits, *, dt, ...)	Construct the second-order symmetric Trotter-Suzuki approximation as an MPO.
`trotter4_approx_as_MPO`(ham_terms, n_qubits, *, dt, ...)	Construct the fourth-order Trotter-Suzuki approximation as an MPO.
`trotter_approx_as_MPO`(hamiltonian, *, dt, order, ...)	Construct a Trotter-Suzuki approximation of a Hamiltonian evolution operator as an MPO.
`state_preparation_mpo`(state_mps)	Perform outer product between an MPS and the state 0.
`init_cost_tn`(ref_mpo, depth, *[, param_scaling, ...])	Initialize the tensor network used for optimization.
`get_envs_tns`(n_qubits, x, cost_tn)	Extract the left and right environment TNs associated to a given site.
`find_transfer_structure`(n_qubits, cost_tn)	Determine the transfer structures connecting neighboring environments in a cost TN.
`build_first_sweep`(n_qubits, cost_tn, dict_transf, *[, ...])	Construct the initial set of contracted left and right environments for a sweeping TN optimization.
`build_loc_cost_tn`(n_qubits, x, dict_contr_envs, cost_tn)	Construct the local cost tensor network associated with a given site.
`PRC_loc_cost_tn`(loc_cost_tn, tags, hyperopt)	Perform a Pop-Rehearse-Contract step on a local cost tensor network.
`update_cost_tn`(cost_tn, list_opt_gate_tens)	Update a cost tensor network with newly optimized gate tensors.
`update_dict_contr_envs`(mode, list_opt_gate_tens, ...)	Update contracted environments after local gate optimization.
`optimize_single_gate_update`(n_qubits, cost_tn, rtol, ...)	Optimize a TN ansatz circuit using sequential single-gate updates.

Module Contents¶

qpe_toolbox.circuit.mpo_circuit_transpilation.list_paulis = ['I', 'X', 'Y', 'Z'][source]¶

qpe_toolbox.circuit.mpo_circuit_transpilation.exp_Pauli_string_as_MPO(ham_term, n_qubits, *, theta)[source]¶

Construct the MPO representation of the unitary exponential of a Pauli string.

Given a Hamiltonian term of the form:

H = c * P

where c is a scalar coefficient and P is a tensor product of Pauli operators acting on a subset of qubits, this function builds the Matrix Product Operator (MPO) corresponding to:

exp(i * theta * c * P)

using the identity:

exp(i α P) = cos(α) I + i sin(α) P

where P^2 = I.

The Pauli string is expanded to the full system size by inserting identity operators on inactive qubits.

Parameters:

ham_term (tuple) –
A tuple (coeff, pauli_string, active_qubits) where:
- coeff (float): Scalar coefficient multiplying the Pauli string.
- pauli_string (str): String of Pauli operators (e.g. "ZYXXZ").
- active_qubits (list[int]): Indices of qubits where the Pauli operators act. The length must match pauli_string.
n_qubits (int) – Total number of qubits in the system.
theta (float) – Evolution parameter (e.g. time or rotation angle).

Returns:

MPO representing the operator:

exp(i * theta * coeff * P)

where P is the full Pauli string embedded in the n_qubits system.

Return type:

qtn.MatrixProductOperator

Raises:

ValueError – If the length of pauli_string does not match the number of active_qubits.

Notes

The MPO is constructed in left-right-up-down index ordering.
The Pauli string MPO has bond dimension 1 before summation.
After combining the identity and Pauli MPOs, the result should not exceed a maximum bond dimension of 2.

Examples

>>> ham_term = (-0.345, "ZYXXZ", [0, 2, 3, 6, 9])
>>> mpo = exp_Pauli_string_as_MPO(ham_term, n_qubits=10, theta=0.1)
>>> mpo
<MatrixProductOperator ...>

qpe_toolbox.circuit.mpo_circuit_transpilation.trotter1_approx_as_MPO(ham_terms, n_qubits, *, dt, cutoff, max_bond, reverse_order=False)[source]¶

Construct the first-order Trotter-Suzuki approximation as a Matrix Product Operator (MPO).

This function builds an MPO representation of the first-order product formula for the time-evolution operator

\[U(dt) \approx \prod_j e^{-i dt \, H_j},\]

where ham_terms = [H_0, H_1, ..., H_{m-1}] is a decomposition of the Hamiltonian into terms that can each be exponentiated individually as MPOs.

Each exponential factor is generated with exp_Pauli_string_as_MPO(), and factors are successively multiplied together using MPO compression.

Parameters:

ham_terms (sequence) – Sequence of Hamiltonian terms. Each element must be compatible with exp_Pauli_string_as_MPO().
n_qubits (int) – Number of qubits (sites) in the system.
dt (float) – Time step used in the Trotter approximation.
cutoff (float) – Singular value truncation threshold used during MPO compression.
max_bond (int) – Maximum allowed bond dimension during MPO compression.
reverse_order (bool, optional) – If False (default), terms are applied in forward order. after the first term. If True, terms are applied in reverse index order.

Returns:

MPO representation of the first-order Trotter approximation.

Return type:

MPO

Notes

The resulting MPO is built iteratively using compressed MPO products via apply(..., compress=True). Truncation errors may accumulate depending on cutoff and max_bond.

qpe_toolbox.circuit.mpo_circuit_transpilation.trotter2_approx_as_MPO(ham_terms, n_qubits, *, dt, cutoff, max_bond, verbosity=0)[source]¶

Construct the second-order symmetric Trotter-Suzuki approximation as an MPO.

This function builds the second-order product formula

\[U(dt) \approx U_1(dt/2)\,U_1^{\mathrm{rev}}(dt/2),\]

where \(U_1\) is the first-order Trotter approximation and \(U_1^{\mathrm{rev}}\) uses the reverse operator ordering.

The approximation is accurate to second order in dt.

Parameters:

ham_terms (sequence) – Sequence of Hamiltonian terms. Each term must be compatible with exp_Pauli_string_as_MPO().
n_qubits (int) – Number of qubits (sites) in the system.
dt (float or complex) – Time step used in the Trotter approximation.
cutoff (float) – Singular value truncation threshold used during MPO compression.
max_bond (int) – Maximum allowed bond dimension during MPO compression.
verbosity (int, optional) – If set to 1, prints progress information. Default is 0.

Returns:

MPO representation of the second-order Trotter approximation.

Return type:

MPO

Notes

Two first-order MPO approximants with half time step are constructed and then multiplied together using compression.

qpe_toolbox.circuit.mpo_circuit_transpilation.trotter4_approx_as_MPO(ham_terms, n_qubits, *, dt, cutoff, max_bond, verbosity=0)[source]¶

Construct the fourth-order Trotter-Suzuki approximation as an MPO.

This function implements the standard symmetric fourth-order composition

\[U_4(dt) = U_2(s\,dt)\, U_2((1 - 2s)\,dt)\, U_2(s\,dt),\]

where \(U_2\) is the second-order Trotter approximation and

\[s = \frac{1}{2 - 2^{1/3}}\]

is the symmetry factor.

This approximation is accurate to fourth order in dt.

Parameters:

ham_terms (sequence) – Sequence of Hamiltonian terms. Each term must be compatible with exp_Pauli_string_as_MPO().
n_qubits (int) – Number of qubits (sites) in the system.
dt (float) – Time step used in the Trotter approximation.
cutoff (float) – Singular value truncation threshold used during MPO compression.
max_bond (int) – Maximum allowed bond dimension during MPO compression.
verbosity (int, optional) – If set to 1, prints progress information. Default is 0.

Returns:

MPO representation of the fourth-order Trotter approximation.

Return type:

MPO

Notes

The method constructs three second-order MPO approximants and combines them through compressed MPO multiplication. Intermediate bond dimensions may grow significantly depending on the system and truncation parameters.

qpe_toolbox.circuit.mpo_circuit_transpilation.trotter_approx_as_MPO(hamiltonian, *, dt, order, cutoff, max_bond, verbosity=0)[source]¶

Construct a Trotter-Suzuki approximation of a Hamiltonian evolution operator as an MPO.

This function dispatches to a specific Trotter-Suzuki decomposition according to the requested approximation order. The Hamiltonian is assumed to provide a decomposition into elementary terms through hamiltonian.terms.

Depending on order, the approximation is built using:

\[\begin{split}U(dt) \approx \begin{cases} \text{1st-order product formula}, & \text{if } order = 1, \\ \text{2nd-order symmetric formula}, & \text{if } order = 2, \\ \text{4th-order Suzuki formula}, & \text{if } order = 4. \end{cases}\end{split}\]

The resulting operator is returned as a compressed MPO.

Parameters:

hamiltonian (Hamiltonian) – Includes Pauli strings, positions and couplings.
dt (float) – Time step used in the Trotter approximation.
order ({1, 2, 4}) – Order of the Trotter-Suzuki decomposition.
cutoff (float) – Singular value truncation threshold used during MPO compression.
max_bond (int) – Maximum allowed MPO bond dimension during compression.
verbosity (int, optional) – Verbosity level forwarded to higher-order routines. Default is 0.

Returns:

MPO representation of the Trotterized time-evolution operator.

Return type:

MPO

Raises:

ValueError – If the requested order is not implemented.

Notes

Compression is performed during MPO manipulations, so the final accuracy depends on the chosen cutoff and max_bond values.

qpe_toolbox.circuit.mpo_circuit_transpilation.state_preparation_mpo(state_mps)[source]¶

Perform outer product between an MPS and the state 0.

Parameters:: state_mps (MatrixProductState) – Target MPS to be reproduced by some circuit Ansatz.
Returns:: Tensor network containing both the reference MPO for some variational procedure.
Return type:: TensorNetwork

qpe_toolbox.circuit.mpo_circuit_transpilation.init_cost_tn(ref_mpo, depth, *, param_scaling=0.1, closed=False, seed=42)[source]¶

Initialize the tensor network used for optimization.

It represents a cost function obtained from contracting:

A brickwall unitary circuit ansatz,
A reference target unitary (or state x zero) register represented as an MPO.

The ansatz is generated as a layered brickwall circuit of two-qubit SU4 gates initialized close to the identity. The resulting unitary tensor network is then combined with the target MPO into a single tensor network suitable for overlap evaluation.

Parameters:

ref_mpo (MatrixProductOperator) – Target MPO to be reproduced by the Ansatz.
depth (int) – Depth of the brickwall circuit ansatz (even and odd count as 1).
param_scaling (float, optional) – Scale of the random initialization parameters for the gates. Smaller values initialize the circuit closer to the identity. Default is 1e-1.
closed (bool, optional) – If False (default), the bra indices of the MPO remain open. If True, ket indices are contracted (trace contraction).
seed (int) – Guarantee reproducibility.

Returns:

Tensor network containing both the variational circuit ansatz and the target MPO.

Return type:

TensorNetwork

qpe_toolbox.circuit.mpo_circuit_transpilation.get_envs_tns(n_qubits, x, cost_tn)[source]¶

Extract the left and right environment TNs associated to a given site.

This function removes the tensors tagged with I{x} from the full cost tensor network and partitions the remaining network into left and/or right environments relative to site x.

Parameters:

n_qubits (int) – Number of qubits (sites) in the tensor network.
x (int) – Site index for which the environments are constructed.
cost_tn (TensorNetwork) – Full cost tensor network.

Returns:

List containing the environment tensor networks.

If x == 0, only the right environment is returned.
If x == n_qubits - 1, only the left environment is returned.
Otherwise, the list is ordered as [left_env, right_env].

Return type:

list of TensorNetwork

Notes

The environments are obtained by selecting tensors according to their I{i} tags:

left environment: tensors tagged with I0 through I{x-1},
right environment: tensors tagged with I{x+1} through I{n_qubits-1}.

qpe_toolbox.circuit.mpo_circuit_transpilation.find_transfer_structure(n_qubits, cost_tn)[source]¶

Determine the transfer structures connecting neighboring environments in a cost TN.

This function analyzes the left and right environment tensor networks associated with each site and identifies the tensor tags involved in transferring contractions between neighboring environments.

The resulting transfer structure is organized into dictionaries for left-to-right and right-to-left propagation.

Parameters:

n_qubits (int) – Number of qubits (sites) in the tensor network.
cost_tn (TensorNetwork) – Full cost tensor network.

Returns:

Nested dictionary containing the transfer structures.

The returned dictionary has the form:

{
    "L": {
        "L1_to_L2": [...],
        ...
        "L{n_qubits-1}_to_L{n_qubits}": [...]
    },
    "R": {
        "R{n_qubits-2}_to_R{n_qubits-1}": [...],
        ...
        "R1_to_R0": [...]
    }
}

where each value is a list of tensor tags participating in the corresponding transfer operation.

Return type:

dict

Notes

For each neighboring pair of environments, tensors are selected according to their I{i} tags, and only tags beginning with "G" or "U" are retained in the transfer description.

The transfer structures can be used to optimize sequential contraction strategies or environment updates in tensor-network algorithms.

qpe_toolbox.circuit.mpo_circuit_transpilation.build_first_sweep(n_qubits, cost_tn, dict_transf, *, drop_tags=True)[source]¶

Construct the initial set of contracted left and right environments for a sweeping TN optimization.

This function iteratively builds partially contracted environments by propagating contractions from the edges of the tensor network toward the center using the transfer structures generated by find_transfer_structure().

The resulting environments are stored as contracted tensors labeled L{i} and R{i}, corresponding to left and right effective environments at each site.

Parameters:

n_qubits (int) – Number of qubits (sites) in the tensor network.
cost_tn (TensorNetwork) – Full cost tensor network.
dict_transf (dict) – Transfer structure dictionary generated by find_transfer_structure().
drop_tags (bool, optional) – Whether to drop tensor tags during contractions. Passed to tensor_contract(). Default is True.

Returns:

Nested dictionary containing contracted environments:

{
    "L": {
        "L1": Tensor,
        ...
    },
    "R": {
        "R{n_qubits-2}": Tensor,
        ...
    }
}

Each entry corresponds to an effective contracted environment tensor.

Return type:

dict

Notes

The contraction procedure starts from the MPO edge tensors tagged "Uref0" and "Uref{n_qubits-1}" and recursively absorbs the transfer tensor networks specified in dict_transf.

These environments are typically reused during local optimization sweeps to avoid repeated large tensor contractions.

qpe_toolbox.circuit.mpo_circuit_transpilation.build_loc_cost_tn(n_qubits, x, dict_contr_envs, cost_tn)[source]¶

Construct the local cost tensor network associated with a given site.

This function combines the local gate tensors acting on site x with the corresponding contracted left and/or right environments to form an effective local tensor network suitable for optimization.

It also returns the ordered list of gate tags corresponding to the variational tensors to optimize.

Parameters:

n_qubits (int) – Number of qubits (sites) in the tensor network.
x (int) – Site index for which the local cost tensor network is constructed.
dict_contr_envs (dict) – Dictionary of contracted environments generated by build_first_sweep().
cost_tn (TensorNetwork) – Full cost tensor network.

Returns:

loc_cost_tn (TensorNetwork) – Local effective tensor network containing the relevant environments and gate tensors for site x.
gate_to_opt_tags (list of str) – Ordered list of gate tensor tags to optimize.

Notes

The local tensor network has the structure

\[\mathcal{S}_x = L_x \; \text{- gates -} \; R_x,\]

where:

L_x is the contracted left environment,
R_x is the contracted right environment,
gates are the tensors tagged with I{x}.

Only tags beginning with "G" are considered optimization gate tags.

Boundary sites are treated separately:

for x = 0, only the right environment is included,
for x = n_qubits - 1, only the left environment is included.

qpe_toolbox.circuit.mpo_circuit_transpilation.PRC_loc_cost_tn(loc_cost_tn, tags, hyperopt)[source]¶

Perform a Pop-Rehearse-Contract step on a local cost tensor network.

This function removes a set of tensors from a local cost tensor network and contracts the remaining network using a specified contraction strategy.

The procedure is intended to support efficient repeated contractions during sweeping optimization algorithms, where contraction paths may be rehearsed and reused across iterations.

Parameters:

loc_cost_tn (TensorNetwork) – Local cost tensor network.
tags (sequence of str) – Tags identifying the tensors to remove before contraction. Typically corresponds to the variational gates currently being optimized.
hyperopt (cotengra.ReusableHyperOptimizer) – Contraction optimization strategy passed to TensorNetwork.contract().

Returns:

Contracted tensor obtained after removing the specified tensors.

Return type:

Tensor

qpe_toolbox.circuit.mpo_circuit_transpilation.update_cost_tn(cost_tn, list_opt_gate_tens)[source]¶

Update a cost tensor network with newly optimized gate tensors.

This function replaces existing gate tensors in the cost tensor network with updated optimized tensors having the same gate tags.

Parameters:

cost_tn (TensorNetwork) – Full cost tensor network.
list_opt_gate_tens (sequence of Tensor) – Sequence of optimized gate tensors to insert into the network.

Returns:

Updated cost tensor network containing the optimized gate tensors.

Return type:

TensorNetwork

qpe_toolbox.circuit.mpo_circuit_transpilation.update_dict_contr_envs(mode, list_opt_gate_tens, cost_tn, dict_transf, dict_contr_envs)[source]¶

Update contracted environments after local gate optimization.

This function updates the cached contracted left or right environments affected by newly optimized gate tensors during a sweeping optimization procedure.

Depending on the sweep direction, only the environments influenced by the updated gates are recomputed.

Parameters:

mode ({"LR", "RL"}) –
Sweep direction.
- "LR" : left-to-right sweep,
- "RL" : right-to-left sweep.
list_opt_gate_tens (sequence of Tensor) – Sequence of optimized gate tensors.
cost_tn (TensorNetwork) – Full updated cost tensor network.
dict_transf (dict) – Transfer structure dictionary generated by find_transfer_structure().
dict_contr_envs (dict) – Updated dictionary of contracted environments initialized by build_first_sweep().

Returns:

Updated dictionary of contracted environments.

Return type:

dict

Notes

Each optimized gate acts on neighboring sites I{n} and I{n+1}. Consequently, only nearby environments need to be updated.

For a left-to-right sweep ("LR"):

\[L_{n+2} \leftarrow L_{n+1} \cdot T_{n+1 \to n+2},\]

while for a right-to-left sweep ("RL"):

\[R_{n-1} \leftarrow R_n \cdot T_{n \to n-1}.\]

This local update strategy avoids rebuilding all environments from scratch after each optimization step.

qpe_toolbox.circuit.mpo_circuit_transpilation.optimize_single_gate_update(n_qubits, cost_tn, rtol, n_sweeps_max, dict_transf, dict_contr_envs)[source]¶

Optimize a TN ansatz circuit using sequential single-gate updates.

This function performs alternating left-to-right and right-to-left sweeps over the variational gates of the cost tensor network. Each gate is optimized individually by contracting its effective environment, performing a singular value decomposition (SVD), and projecting the result back onto the unitary manifold.

The optimization iteratively updates both the tensor network and the cached contracted environments.

Parameters:

n_qubits (int) – Number of qubits (sites) in the tensor network.
cost_tn (TensorNetwork) – Full cost tensor network containing the variational circuit and target MPO.
rtol (float) – Relative tolerance condition for stopping.
n_sweeps_max (int) – Maximum number of optimization sweeps.
dict_transf (dict) – Transfer structure dictionary generated by find_transfer_structure().
dict_contr_envs (dict) – Dictionary of contracted environments generated by build_first_sweep().

Returns:

cost_tn (TensorNetwork) – Optimized cost tensor network.
dict_contr_envs (dict) – Updated dictionary of contracted environments.

Notes

The optimization proceeds as follows:

Construct a local effective tensor network around a gate,
Remove the gate tensor and contract the surrounding environment,
Perform an SVD of the resulting effective tensor,
Reconstruct the optimal unitary gate from the isometric factors,
Update the tensor network and cached environments.

The effective local contraction is computed using PRC_loc_cost_tn().

The gate update is obtained from an SVD decomposition.

The overlap displayed in the progress bar corresponds to the cost-function value and can be verified independently from the singular values of the effective environment tensor.

The sweeping schedule alternates between:

left-to-right ("LR"),
right-to-left ("RL"),

in order to iteratively improve all variational gates.