qpe_toolbox.circuit.mpo_circuit_transpilation¶

Functions¶

`init_cost_tn`(ref_mpo, depth, *[, param_scaling, ...])	Initialize the tensor network used for optimization.
`get_envs_tns`(n_qubits, site_index, 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, transfer_structure, *)	Construct the initial set of contracted left and right environments for a sweeping TN optimization.
`build_loc_cost_tn`(n_qubits, site_index, ...)	Construct the local cost tensor network associated with a given site.
`update_cost_tn`(cost_tn, gate_tens)	Update a cost tensor network with a newly optimized gate tensor.
`update_contracted_envs`(mode, gate_tens, cost_tn, ...)	Update contracted environments after a local gate optimization.
`optimize_one_gate`(tag, loc_cost_tn, cost_tn, mode, ...)	Update a single gate tensor via its SVD-optimal unitary approximation.
`sweep_direction`(mode, site_indices, cost_tn, ...[, ...])	Run one left-to-right or right-to-left sweep over all sites.
`optimize_single_gate_update`(n_qubits, cost_tn, rtol, ...)	Optimize a TN ansatz circuit using sequential single-gate updates.
`transpile_mpo_to_circuit`(ref_mpo, depth, rtol, ...[, ...])	Fit a brickwall circuit ansatz to a reference MPO by single-gate sweeps.

Module Contents¶

qpe_toolbox.circuit.mpo_circuit_transpilation.init_cost_tn(ref_mpo, depth, *, param_scaling=0.1, closed=False, rng=None)[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 SU4SWAP gates initialized close to the identity: unlike quimb’s SU4 (which tends to SWAP), SU4SWAP tends to the identity as its parameters go to zero. 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 each SU4SWAP gate 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).
rng (numpy.random.Generator, optional) – Random number generator to generate gate parameters. If None, a default generator is created.

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, site_index, cost_tn)[source]¶

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

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

Parameters:

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

Returns:

List containing the environment tensor networks.

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

Return type:

list of TensorNetwork

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.

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

qpe_toolbox.circuit.mpo_circuit_transpilation.build_first_sweep(n_qubits, cost_tn, transfer_structure, *, 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().

Parameters:

n_qubits (int) – Number of qubits (sites) in the tensor network.
cost_tn (TensorNetwork) – Full cost tensor network.
transfer_structure (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

qpe_toolbox.circuit.mpo_circuit_transpilation.build_loc_cost_tn(n_qubits, site_index, contracted_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 site_index 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.
site_index (int) – Site index for which the local cost tensor network is constructed.
contracted_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 site_index.
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{site_index}.

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

Boundary sites are treated separately:

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

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

Update a cost tensor network with a newly optimized gate tensor.

This function replaces the existing gate tensor in the cost tensor network with the updated optimized tensor, keeping the same gate tag.

Parameters:

cost_tn (TensorNetwork) – Full cost tensor network.
gate_tens (Tensor) – Optimized gate tensor to insert into the network.

Returns:

Updated cost tensor network containing the optimized gate tensor.

Return type:

TensorNetwork

qpe_toolbox.circuit.mpo_circuit_transpilation.update_contracted_envs(mode, gate_tens, cost_tn, transfer_structure, contracted_envs)[source]¶

Update contracted environments after a local gate optimization.

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

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

Parameters:

mode ({"LR", "RL"}) –
Sweep direction.
- "LR" : left-to-right sweep,
- "RL" : right-to-left sweep.
gate_tens (Tensor) – Optimized gate tensor.
cost_tn (TensorNetwork) – Full updated cost tensor network.
transfer_structure (dict) – Transfer structure dictionary generated by find_transfer_structure().
contracted_envs (dict) – Updated dictionary of contracted environments initialized by build_first_sweep().

Returns:

Updated dictionary of contracted environments.

Return type:

dict

Notes

The 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_one_gate(tag, loc_cost_tn, cost_tn, mode, transfer_structure, contracted_envs, *, optimize='auto-hq')[source]¶

Update a single gate tensor via its SVD-optimal unitary approximation.

Parameters:

tag (str) – Tag identifying the gate tensor to update.
loc_cost_tn (TensorNetwork) – Local cost tensor network for the site the gate belongs to.
cost_tn (TensorNetwork) – Full cost tensor network.
mode ({"LR", "RL"}) – Sweep direction, forwarded to update_contracted_envs().
transfer_structure (dict) – Transfer structure dictionary generated by find_transfer_structure().
contracted_envs (dict) – Dictionary of contracted environments generated by build_first_sweep().
optimize (str or cotengra.HyperOptimizer, optional) – Contraction optimization strategy passed to TensorNetwork.contract(). Default is "auto-hq".

Returns:

cost_tn (TensorNetwork) – Updated full cost tensor network.
loc_cost_tn (TensorNetwork) – Updated local cost tensor network.
contracted_envs (dict) – Updated dictionary of contracted environments.
overlap (float) – Cost-function value reached after this gate update.

qpe_toolbox.circuit.mpo_circuit_transpilation.sweep_direction(mode, site_indices, cost_tn, transfer_structure, contracted_envs, *, optimize='auto-hq')[source]¶

Run one left-to-right or right-to-left sweep over all sites.

Parameters:

mode ({"LR", "RL"}) – Sweep direction, forwarded to optimize_one_gate().
site_indices (sequence of int) – Site indices to sweep over, in order. Its length must be n_qubits - 2 (true of both the “LR” and “RL” ranges built by optimize_single_gate_update()), since n_qubits is recovered from it as len(site_indices) + 2.
cost_tn (TensorNetwork) – Full cost tensor network.
transfer_structure (dict) – Transfer structure dictionary generated by find_transfer_structure().
contracted_envs (dict) – Dictionary of contracted environments generated by build_first_sweep().
optimize (str or cotengra.HyperOptimizer, optional) – Contraction optimization strategy forwarded to optimize_one_gate(). Default is "auto-hq".

Returns:

cost_tn (TensorNetwork) – Updated full cost tensor network.
contracted_envs (dict) – Updated dictionary of contracted environments.
overlap (float) – Cost-function value reached after the last gate update of the sweep.

qpe_toolbox.circuit.mpo_circuit_transpilation.optimize_single_gate_update(n_qubits, cost_tn, rtol, n_sweeps_max, transfer_structure, contracted_envs, *, optimize='auto-hq')[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.
transfer_structure (dict) – Transfer structure dictionary generated by find_transfer_structure().
contracted_envs (dict) – Dictionary of contracted environments generated by build_first_sweep().
optimize (str or cotengra.HyperOptimizer, optional) – Contraction optimization strategy passed to TensorNetwork.contract() when contracting each gate’s local environment. Default is "auto-hq"; pass e.g. "greedy" for a cheaper, deterministic strategy, or a cotengra.ReusableHyperOptimizer instance for finer control.

Returns:

cost_tn (TensorNetwork) – Optimized cost tensor network.
contracted_envs (dict) – Updated dictionary of contracted environments.
overlap (float) – Overlap with the reference MPO after the last sweep, normalized by 2**n_qubits.

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.

qpe_toolbox.circuit.mpo_circuit_transpilation.transpile_mpo_to_circuit(ref_mpo, depth, rtol, n_sweeps_max, *, param_scaling=0.1, closed=False, rng=None, optimize='auto-hq')[source]¶

Fit a brickwall circuit ansatz to a reference MPO by single-gate sweeps.

This is a convenience wrapper chaining init_cost_tn(), find_transfer_structure(), build_first_sweep() and optimize_single_gate_update().

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).
rtol (float) – Relative tolerance condition for stopping.
n_sweeps_max (int) – Maximum number of optimization sweeps.
param_scaling (float, optional) – Scale of the random initialization parameters for the gates. Smaller values initialize each SU4SWAP 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).
rng (numpy.random.Generator, optional) – Random number generator to generate gate parameters. If None, a default generator is created.
optimize (str or cotengra.HyperOptimizer, optional) – Contraction optimization strategy forwarded to optimize_single_gate_update(). Default is "auto-hq"; pass e.g. "greedy" for a cheaper, deterministic strategy.

Returns:

cost_tn (TensorNetwork) – Optimized cost tensor network.
contracted_envs (dict) – Updated dictionary of contracted environments.
overlap (float) – Overlap with the reference MPO after the last sweep, normalized by 2**n_qubits.