guppyalgos.algorithms.time_evolution.trotter

Trotterization Algorithms for Quantum Simulation.

Functions

cntrl_trotter_first_order(hamiltonian[, ...])

Build a single controlled first-order Trotter step.

cntrl_trotter_from_sequence(ham_terms, ...)

Build a controlled Trotter step from term indices and time factors.

cntrl_trotter_higher_order(hamiltonian, ...)

Build a controlled even-order symmetric Suzuki--Trotter step.

ham_sim_trotter(trotter_step, n_steps, ...)

Build a full Hamiltonian simulation using Trotter steps.

scale_sequence(sequence, factor)

Scale the dimensionless weights stored in a product-formula sequence.

suzuki_sequence(n_terms, order)

Return Pauli-term indices and time factors for an even-order formula.

trotter_first_order(hamiltonian[, ...])

Build a single first-order Trotter step for Hamiltonian simulation.

trotter_from_sequence(ham_terms, sequence, ...)

Build a Trotter step from Pauli-term indices and time factors.

trotter_higher_order(hamiltonian, ...[, ...])

Build an even-order symmetric Suzuki--Trotter step.
guppyalgos.algorithms.time_evolution.trotter.cntrl_trotter_first_order(hamiltonian, n_state_qubits=None, cx_ladder=<class 'guppyalgos.primitives.subroutines.ladders.cx_ladder.CXLadderLog'>, controlled_rz_method=<function crz>, rz_method=<function rz>)

Build a single controlled first-order Trotter step.

This controlled variant mirrors trotter_first_order() while preserving identity terms as a measurable phase on the control qubit. Each Pauli term, including the identity, is compiled into a controlled Pauli exponential, with the all-identity case reducing to a control-only phase.

Parameters:

  • hamiltonian (zqp.RealTermSum) – The Hamiltonian to simulate, represented as a sum of Pauli operators.

  • n_state_qubits (int) – The number of qubits in the quantum state register.

  • cx_ladder (Ladder) – CX ladder, implements Ladder protocol. Defaults to CXLadderLog.

  • controlled_rz_method (Callable, optional) – Method to implement the terminal controlled RZ rotation. Defaults to crz.

  • rz_method (Callable, optional) – Method to implement the control-qubit phase used when a term is the identity. Defaults to rz.

Return type:

GuppyFunctionDefinition[(qubit, array[qubit, TypeVar(n_state_q, bound= nat)], float), None]

Returns:

A Guppy function implementing the controlled Trotter step.

guppyalgos.algorithms.time_evolution.trotter.cntrl_trotter_from_sequence(ham_terms, sequence, n_state_qubits, cx_ladder=<class 'guppyalgos.primitives.subroutines.ladders.cx_ladder.CXLadderLog'>, controlled_rz_method=<function crz>, rz_method=<function rz>)

Build a controlled Trotter step from term indices and time factors.

Sequencing matches trotter_from_sequence(): entries are executed from left to right, and each (term_index, time_factor) applies the selected term with angle coefficient * time_factor * time_step. Repeated and negative-weight entries therefore represent repeated and backward controlled evolutions, respectively.

Every scheduled Pauli exponential is conditioned on control. Whether identity terms appear in ham_terms is decided by the caller; retaining them preserves their observable phase relative to the inactive control branch. The schedule is embedded at compile time and time_step remains a runtime parameter.

Parameters:
Return type:

GuppyFunctionDefinition[(qubit, array[qubit, TypeVar(n_state_q, bound= nat)], float), None]

Returns:

A controlled Guppy function that applies the weighted sequence.

guppyalgos.algorithms.time_evolution.trotter.cntrl_trotter_higher_order(hamiltonian, n_state_qubits, order, cx_ladder=<class 'guppyalgos.primitives.subroutines.ladders.cx_ladder.CXLadderLog'>, controlled_rz_method=<function crz>, rz_method=<function rz>)

Build a controlled even-order symmetric Suzuki–Trotter step.

This applies the same recursive product formula as trotter_higher_order(), controlled by a single qubit. Unlike the uncontrolled variant, identity Hamiltonian terms are retained because their phase is observable relative to the inactive control branch.

Parameters:

  • hamiltonian (RealTermSum) – Real Pauli Hamiltonian to simulate.

  • n_state_qubits (int) – Number of qubits in the state register.

  • order (int) – Desired product-formula order. Must be an even integer at least 2.

  • cx_ladder (type[Ladder]) – CX ladder implementation used by each Pauli exponential.

  • controlled_rz_method (GuppyFunctionDefinition[(qubit, qubit, angle), None]) – Implementation used for controlled RZ rotations.

  • rz_method (GuppyFunctionDefinition[(qubit, angle), None]) – Implementation used for identity-term phases on the control.

Return type:

GuppyFunctionDefinition[(qubit, array[qubit, TypeVar(n_state_q, bound= nat)], float), None]

Returns:

A Guppy function implementing one controlled product-formula step.

Raises:

ValueError – If order is not an even integer of at least 2.

guppyalgos.algorithms.time_evolution.trotter.ham_sim_trotter(trotter_step, n_steps, time_step, n_state_qubits)

Build a full Hamiltonian simulation using Trotter steps.

This function constructs a Guppy function that simulates the time evolution of a quantum system under a given Hamiltonian by repeatedly applying a provided Trotter step function. The number of Trotter steps and the time step for each application are specified as inputs. The resulting function applies the Trotter step the specified number of times to approximate the overall time evolution. Any Trotter step function that matches the expected signature can be used, allowing for flexibility in the choice of Trotterization method.

Example:

from guppyalgos.algorithms.time_evolution.trotter import ham_sim_trotter
from guppyalgos.algorithms.time_evolution.trotter import trotter_first_order
import zixy.qubit.pauli as zqp

ham_op = zqp.RealTermSum.from_str(
"(-0.5, Z0 X1), (-0.1, X0 Z1), (-0.2, Y0 Y1), (-0.3, X0 X1)"
)
time_step = 0.1
n_steps = 3
n_state_qubits = len(ham_op.qubits)

ham_trotter_step = trotter_first_order(ham_op, n_state_qubits)
ham_sim = ham_sim_trotter(ham_trotter_step, n_steps, time_step, n_state_qubits)

@guppy
@no_type_check
def main(state_qreg: array[qubit, n_state_qubits]) -> None:
    ham_sim(state_qreg)
Parameters:

  • trotter_step (GuppyFunctionDefinition[(array[qubit, TypeVar(n_state_q, bound= nat)], float), None]) – A Guppy function implementing a single Trotter step.

  • n_steps (int) – The number of Trotter steps to apply.

  • time_step (float) – The time step for each Trotter step.

  • n_state_qubits (int) – The number of qubits in the quantum state register.

Return type:

GuppyFunctionDefinition[(array[qubit, TypeVar(n_state_q, bound= nat)], ), None]

Returns:

A Guppy function implementing the full Hamiltonian simulation.

guppyalgos.algorithms.time_evolution.trotter.scale_sequence(sequence, factor)

Scale the dimensionless weights stored in a product-formula sequence.

Each (term_index, time_factor) entry becomes (term_index, factor * time_factor). This builds a schedule for \(S(\mathrm{factor} \cdot t)\) without changing the runtime time_step; the sequence executor applies that time only when it calculates each Pauli-exponential angle.

Return type:

list[tuple[int, float]]

guppyalgos.algorithms.time_evolution.trotter.suzuki_sequence(n_terms, order)

Return Pauli-term indices and time factors for an even-order formula.

Return type:

list[tuple[int, float]]

guppyalgos.algorithms.time_evolution.trotter.trotter_first_order(hamiltonian, n_state_qubits=None, cx_ladder=<class 'guppyalgos.primitives.subroutines.ladders.cx_ladder.CXLadderLog'>, rz_method=<function rz>)

Build a single first-order Trotter step for Hamiltonian simulation.

This function constructs a Trotter step function that can be used to simulate the time evolution of a quantum system under a given Real Hamiltonian using first-order Trotterization. It is constructed by exponentiating each term in the Hamiltonian sequentially using the pauli_exp function to create the exponentiation circuits for each Pauli term. The defaults for cx_ladder_method and rz_method are set to use logarithmic CX ladders and standard RZ gates, respectively.

Currently, the implementation does not account for global phase factors and thus identity terms are stripped from the Hamiltonian. This is because guppy does not handle global phase yet. This is fine for Hamiltonian simulation as identity terms only contribute a global phase to the evolution, however when doing controlled Hamiltonian simulation this will need to be addressed.

Example:

from guppyalgos.algorithms.time_evolution.trotter import trotter_first_order
import zixy.qubit.pauli as zqp
n_state_qubits = 4
hamiltonian = zqp.RealTermSum.from_str("(-0.5, Z0 X1), (-0.1, X0 Z1)")
trotter_step = trotter_first_order(hamiltonian, n_state_qubits)
Parameters:

  • hamiltonian (zqp.RealTermSum) – The Hamiltonian to simulate, represented as a

  • operators. (sum of Pauli)

  • n_state_qubits (int) – The number of qubits in the quantum state register.

  • cx_ladder (Ladder) – CX ladder implementing Ladder protocol.

  • rz_method (Callable, optional) – Method to implement RZ rotations. Default rz.

Return type:

GuppyFunctionDefinition[(array[qubit, TypeVar(n_state_q, bound= nat)], float), None]

Returns:

A Guppy function implementing the Trotter step.

guppyalgos.algorithms.time_evolution.trotter.trotter_from_sequence(ham_terms, sequence, n_state_qubits, cx_ladder=<class 'guppyalgos.primitives.subroutines.ladders.cx_ladder.CXLadderLog'>, rz_method=<function rz>)

Build a Trotter step from Pauli-term indices and time factors.

The sequence is evaluated from left to right. Each (term_index, time_factor) entry selects a term \(c_j P_j\) from ham_terms and applies its Pauli-exponential circuit with the runtime angle c_j * time_factor * time_step. Repeated indices repeat a term’s exponential, while negative factors implement a signed backward evolution.

One Pauli-exponential definition is generated per Hamiltonian term. The sequence indices, factors, and Hamiltonian coefficients are embedded into the returned Guppy function at compile time; only time_step is supplied when the generated function runs.

Parameters:

  • ham_terms (list[RealTerm]) – Ordered Pauli terms available to the sequence.

  • sequence (list[tuple[int, float]]) – Ordered (term_index, time_factor) execution schedule.

  • n_state_qubits (int) – Number of qubits in the state register.

  • cx_ladder (type[Ladder]) – CX ladder implementation used by each Pauli exponential.

  • rz_method (GuppyFunctionDefinition[(qubit, angle), None]) – Implementation used for the Pauli-exponential RZ rotations.

Return type:

GuppyFunctionDefinition[(array[qubit, TypeVar(n_state_q, bound= nat)], float), None]

Returns:

A Guppy function that applies the weighted sequence to a state register.

guppyalgos.algorithms.time_evolution.trotter.trotter_higher_order(hamiltonian, n_state_qubits, order, cx_ladder=<class 'guppyalgos.primitives.subroutines.ladders.cx_ladder.CXLadderLog'>, rz_method=<function rz>)

Build an even-order symmetric Suzuki–Trotter step.

The second-order formula is the symmetric (Strang) splitting

\[S_2(t) = \prod_{j=1}^{m} e^{-i H_j t / 2} \prod_{j=m}^{1} e^{-i H_j t / 2}.\]

Higher even orders are generated recursively using

\[S_{2k}(t) = S_{2k-2}(p_k t)^2 S_{2k-2}((1 - 4p_k)t) S_{2k-2}(p_k t)^2,\]

where \(p_k = 1 / (4 - 4^{1/(2k-1)})\). The returned Guppy function takes the state register and a runtime time_step. Identity terms are omitted because they contribute only a global phase to an uncontrolled simulation.

Parameters:

  • hamiltonian (RealTermSum) – Real Pauli Hamiltonian to simulate.

  • n_state_qubits (int) – Number of qubits in the state register.

  • order (int) – Desired product-formula order. Must be an even integer at least 2.

  • cx_ladder (type[Ladder]) – CX ladder implementation used by each Pauli exponential.

  • rz_method (GuppyFunctionDefinition[(qubit, angle), None]) – Implementation used for the Pauli-exponential RZ rotations.

Return type:

GuppyFunctionDefinition[(array[qubit, TypeVar(n_state_q, bound= nat)], float), None]

Returns:

A Guppy function implementing one product-formula step.

Raises:

ValueError – If order is not an even integer of at least 2.