ket.qulib

Quantum library.

Utilities for preparing quantum states and building quantum algorithms.

Modules ket.qulib

gates

Quantum gate construction.

ham

Hamiltonian library.

oracle

Quantum oracles.

prepare

Quantum state preparation.

Functions ket.qulib

draw(gate[, num_qubits, args, qubits, ...])

Draw a quantum gate using Qiskit.

dump_matrix(gate[, num_qubits, args, process])

Get the matrix representation of a quantum gate.

energy(hamiltonian, state[, num_qubits])

Calculates the energy of a Hamiltonian.

exact_solver(hamiltonian, num_qubits)

Finds the exact ground state of a Hamiltonian.

pauli_string(hamiltonian, num_qubits[, ...])

Extracts the Pauli strings from a Hamiltonian.

simulated_annealing(hamiltonian, num_qubits)

Find the ground state of a Hamiltonian.
draw(gate: Callable, num_qubits: int | list[int] | None = None, args: tuple = (), *, qubits: int | list[int] | None = None, qpu_size: int | None = None, u4_gate: Literal['CX', 'CZ'] | None = None, u2_gates: Literal['ZYZ', 'RzSx'] | None = None, coupling_graph: list[tuple[int, int]] | None = None, title: str | None = None, keep_order: bool = True, **kwargs)

Draw a quantum gate using Qiskit.

Note

This method requires additional dependencies from ket-lang[plot].

Install with: pip install ket-lang[plot].

Parameters:

  • gate – Quantum gate function.

  • num_qubits – Number of qubits.

  • args – Classical arguments to pass to the gate function.

  • qpu_size – Size of the quantum processing unit (QPU). If specified, the number of qubits will be adjusted to fit the QPU size.

  • u4_gate – Type of U4 gate to use, either “CX” or “CZ”.

  • u2_gates – Type of U2 gates to use, either “ZYZ” or “RzSx”.

  • coupling_graph – Coupling graph of the QPU, specified as a list of tuples representing connected qubits.

  • title – Title for the circuit diagram.

  • keep_order – Maintain the gate call order.

  • **kwargs – Keyword arguments to pass to the Qiskit drawer.

Returns:

Qiskit circuit diagram of the quantum gate.

dump_matrix(gate: Callable, num_qubits: int | list[int] = 1, args=(), process: Process | None = None) → list[list[complex]]

Get the matrix representation of a quantum gate.

This function calculates the matrix representation of a quantum gate.

Parameters:

  • gate – Quantum gate operation to obtain the matrix for.

  • num_qubits – Number of qubits.

  • args – Classical arguments to pass to the gate function.

  • process – Quantum process used to generate the matrix.

Returns:

Matrix representation of the quantum gate.

energy(hamiltonian: Callable[[Quant], Hamiltonian], state: int | list[int] | str, num_qubits: int | None = None) → float

Calculates the energy of a Hamiltonian.

If the Hamiltonian is diagonal in the computational basis, the computation time is linear with respect to the number of qubits.

Parameters:

  • hamiltonian – A function that takes qubits and returns the Hamiltonian to be evaluated.

  • state – The initial computational basis state. Can be an integer, a list of integers (e.g., [1, 0, 1]), or a binary string (e.g., 101).

  • num_qubits – The total number of qubits in the system. If not specified (None), it will be inferred from the length of state.

Returns:

The expected value (energy) measured for the Hamiltonian in the given state.

exact_solver(hamiltonian: Callable[[Quant], Hamiltonian], num_qubits: int) → tuple[int, float]

Finds the exact ground state of a Hamiltonian.

Note

This function evaluates \(2^\texttt{num_qubits}\) states. Because the search space grows exponentially, this solver should only be used for small quantum systems (typically < 10 qubits). For larger systems, use heuristic methods like simulated_annealing.

Parameters:

  • hamiltonian – A function that takes qubits and returns the Hamiltonian to be evaluated.

  • num_qubits – The total number of qubits in the quantum system.

Returns:

A tuple containing the optimal state (as an integer) and its corresponding lowest energy.

pauli_string(hamiltonian: Callable[[Quant], Hamiltonian], num_qubits: int, reversed_qubits: bool = False) → list[tuple[str, float]]

Extracts the Pauli strings from a Hamiltonian.

This function evaluates a given Hamiltonian over a dynamically allocated quantum process and parses its terms into a list of string representations (e.g., "IXYI") alongside their scalar coefficients. Any qubit not explicitly acted upon by a Pauli operator in a term defaults to the Identity operator ("I").

Parameters:

  • hamiltonian – A callable that takes a collection of qubits (Quant) and returns a Hamiltonian object.

  • num_qubits – The total number of qubits the Hamiltonian acts on.

  • reversed_qubits – If True, the order of the allocated qubits is reversed before being passed to the hamiltonian function. Defaults to False.

Returns:

  • String represents a Pauli product (e.g., "ZIZX") across all num_qubits.

  • Float representing the coefficients.

Return type:

A list of tuple

simulated_annealing(hamiltonian: Callable[[Quant], Hamiltonian], num_qubits: int, initial_temp: float = 1000.0, final_temp: float = 0.01, cooling_rate: float = 0.99, num_evaluations: int = 16, multiprocessing: bool = True) → tuple[int, float]

Find the ground state of a Hamiltonian.

This function runs multiple independent simulated annealing searches concurrently using multiprocessing. It explores the solution space and returns the result from the run that achieved the lowest energy.

Note

When multiprocessing is enabled (the default), this method requires the multiprocess library.

Install with: pip install multiprocess.

Parameters:

  • hamiltonian – A function that takes qubits and returns the Hamiltonian to be minimized.

  • num_qubits – The number of qubits in the quantum system.

  • initial_temp – The starting temperature for the annealing schedule. Higher values allow more exploration. Defaults to 1000.0.

  • final_temp – The temperature at which the annealing process terminates. Defaults to 0.01.

  • cooling_rate – The decay factor applied to the temperature at each step (0 < cooling_rate < 1). Defaults to 0.99.

  • num_evaluations – The number of independent annealing runs to execute. Defaults to 16.

  • multiprocessing – Whether to run the evaluations concurrently using the multiprocess library. Defaults to True.

Raises:

  • ValueError – If any of the numerical parameters (num_qubits, initial_temp, final_temp, cooling_rate, num_evaluations) are out of their valid ranges.

  • RuntimeError – If multiprocessing=True but the multiprocess library is not installed.

Returns:

The result of the simulated annealing run that yielded the lowest energy. Typically returns a tuple containing the optimal state and its corresponding energy.