ket.qulib.ham

Hamiltonian library.

Functions ket.qulib.ham

falqon_a(hp, hd)

FALQON A operator.

falqon_b(hp, hd)

FALQON B operator.

falqon_c(hp, hd)

FALQON C operator.

falqon_get_beta_fo(hp, hd)

Get FALQON first-order beta parameter.

falqon_get_beta_so(delta_t, hp, hd)

Get FALQON second-order beta parameter.

knapsack(weights, values, capacity, qubits)

Knapsack Hamiltonian.

maxcut(edges, qubits)

Max-Cut Hamiltonian.

qubo(model, qubits)

Convert a QUBO model to a Hamiltonian.

tsp(cities, n, qubits[, penalty])

Traveling Salesman Problem (TSP) Hamiltonian.

x_mixer(qubits)

X-Mixer Hamiltonian.

xy_mixer(qubits[, edges])

XY-Mixer Hamiltonian.
falqon_a(hp: Hamiltonian, hd: Hamiltonian) → Hamiltonian

FALQON A operator.

\[A = i[H_d, H_p]\]

See https://arxiv.org/abs/2103.08619.

Parameters:

  • hp – Problem Hamiltonian.

  • hd – Driver Hamiltonian.

falqon_b(hp: Hamiltonian, hd: Hamiltonian) → Hamiltonian

FALQON B operator.

\[B = [ [H_d, H_p], H_d ]\]

See https://arxiv.org/abs/2407.17810.

Parameters:

  • hp – Problem Hamiltonian.

  • hd – Driver Hamiltonian.

falqon_c(hp: Hamiltonian, hd: Hamiltonian) → Hamiltonian

FALQON C operator.

\[C = [ [H_d, H_p], H_p ]\]

See https://arxiv.org/abs/2407.17810.

Parameters:

  • hp – Problem Hamiltonian.

  • hd – Driver Hamiltonian.

falqon_get_beta_fo(hp: Hamiltonian, hd: Hamiltonian) → float

Get FALQON first-order beta parameter.

See https://arxiv.org/abs/2103.08619.

This function computes the expectation value, triggering the circuit execution.

Parameters:

  • hp – Problem Hamiltonian.

  • hd – Driver Hamiltonian.

falqon_get_beta_so(delta_t, hp: Hamiltonian, hd: Hamiltonian) → float

Get FALQON second-order beta parameter.

See https://arxiv.org/abs/2407.17810.

This function computes the expectation values, triggering the circuit execution.

Parameters:

  • delta_t – Time step.

  • hp – Problem Hamiltonian.

  • hd – Driver Hamiltonian.

knapsack(weights: list[float], values: list[float], capacity: float, qubits: Quant, penalty: None | float = None) → Hamiltonian

Knapsack Hamiltonian.

Implements the QUBO formulation of the 0/1 Knapsack problem using a quadratic penalty to enforce the capacity constraint.

The Hamiltonian minimized is:

\[-\sum_i v_i x_i + A \left(\sum_i w_i x_i - C\right)^2\]

where \(x_i = \frac{1 - Z_i}{2}\) and \(A\) is the penalty coefficient.

If penalty is not provided, it defaults to max(values), which is typically sufficient to discourage capacity violations in practical QAOA runs.

Parameters:

  • weights – List of item weights \(w_i\).

  • values – List of item values \(v_i\).

  • capacity – Maximum allowed total weight \(C\).

  • qubits – Qubits representing the binary decision variables.

  • penalty – Penalty coefficient \(A\). If None, defaults to max(values).

Returns:

Hamiltonian representing the knapsack objective.

maxcut(edges: list[tuple[int, int]], qubits: Quant) → Hamiltonian

Max-Cut Hamiltonian.

\[\sum_{a, b\,\in\, \mathcal{E}}\frac{1}{2}(1-Z_a Z_b)\]
Parameters:

  • edges – List of edges in the graph.

  • qubits – Qubits representing the graph nodes.

qubo(model, qubits: Quant) → Hamiltonian

Convert a QUBO model to a Hamiltonian.

Converts a QUBO model from the pyQUBO library to a Hamiltonian observable.

Parameters:

  • model – QUBO model.

  • qubits – Qubits representing the variables in the model.

tsp(cities: dict[tuple[int, int], float], n: int, qubits: list, penalty: float | None = None) → Hamiltonian

Traveling Salesman Problem (TSP) Hamiltonian.

Implements the QUBO formulation of the TSP using a quadratic penalty to enforce permutation constraints.

The Hamiltonian minimized is:

\[\sum_{t=0}^{n-1} \sum_{i,j} d_{ij} x_{i,t} x_{j,t+1} + A \sum_i \left(\sum_t x_{i,t} - 1\right)^2 + A \sum_t \left(\sum_i x_{i,t} - 1\right)^2\]

where:

  • \(d_{ij}\) is the directed distance from city \(i\) to city \(j\),

  • \(x_{i,t} \in \{0,1\}\) indicates whether city \(i\) is visited at tour position \(t\),

  • \(x_{i,t} = \frac{1 - Z_{i,t}}{2}\),

  • \(A\) is the penalty coefficient.

The first term minimizes the total tour length. The second term enforces that each city is visited exactly once. The third term enforces that exactly one city is assigned to each tour position.

If penalty is not provided, it defaults to 2 * max(cities.values()), which is typically sufficient to discourage constraint violations.

Parameters:

  • cities – Dictionary mapping directed edges (i, j) to distances \(d_{ij}\).

  • n – Number of cities.

  • qubits – Flat list of \(n^2\) qubits representing the binary variables \(x_{i,t}\).

  • penalty – Penalty coefficient \(A\). If None, defaults to 2 * max(cities.values()).

Returns:

Hamiltonian representing the directed TSP cost function with quadratic constraint penalties.

x_mixer(qubits: Quant) → Hamiltonian

X-Mixer Hamiltonian.

\[\sum_j X_j\]
Parameters:

qubits – Qubits to apply the mixer.

xy_mixer(qubits, edges: list[tuple[int, int]] | None = None) → Hamiltonian

XY-Mixer Hamiltonian.

\[\frac{1}{2}\sum_{a, b\,\in\, \mathcal{E}} X_a X_b + Y_a Y_b\]

If edges is None, a ring topology is assumed.

Parameters:

  • qubits – Qubits to apply the mixer.

  • edges – List of edges in the graph.