ket.base

Base quantum programming classes.

This module provides base classes for handling quantum programming in the Ket library. It includes for handle and store quantum states, measurements.

Classes ket.base

Measurement	Quantum measurement result.
Process	Quantum program process.
Quant	List of qubits.
Samples	Quantum state measurement samples.

class Measurement(qubits: Quant)

Quantum measurement result.

This class holds a reference for a measurement result. The result may not be available right after the measurement call, especially in batch execution.

To read the value, access the attribute value. If the value is not available, the measurement will return None; otherwise, it will return an unsigned integer.

You can instantiate this class by calling the measure function.

Example

from ket import *

p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])
result = measure(q)
print(result.value)  # 0 or 3

property value: int | None

Retrieve the measurement value if available.

get() → int

Retrieve the measurement value.

If the value is not available, the quantum process will execute to get the result.

class Process(configuration=None, num_qubits: int | None = None, simulator: Literal['sparse', 'dense', 'dense v2'] | None = None, execution: Literal['live', 'batch'] | None = None, coupling_graph: list[tuple[int, int]] | None = None)

Quantum program process.

A Process in Ket handles quantum circuit preparation and execution, serving as a direct interface to the Rust library. Its primary usage in quantum programming is to allocate qubits using the alloc method.

Example

from ket import Process

p = Process()
qubits = p.alloc(10) # Allocate 10 qubits

By default, quantum execution is performed by the KBW simulator using sparse mode with 32 qubits. The KBW simulator in sparse mode handles qubits in a representation equivalent to a sparse matrix. This simulator’s execution time is related to the amount of superposition in the quantum execution, making it suitable as a default when the number of qubits is unknown or the quantum state can be represented by a sparse matrix, such as in a GHZ state. The dense simulator mode has exponential time complexity with the number of qubits. While it can better explore CPU parallelism, the number of qubits must be carefully set. The default number of qubits for the dense simulator is 12. The choice of simulator mode depends on the quantum algorithm, as each mode has its pros and cons.

Another parameter for quantum execution on the KBW simulator is between “live” and “batch” execution. This configuration determines when quantum instructions will be executed. If set to “live”, quantum instructions execute immediately after the call. If set to “batch”, quantum instructions execute only at the end of the process. The default configuration is “live”, suitable for quantum simulation where the non-clone theorem of quantum mechanics does not need to be respected. Batch execution is closer to what is expected from a quantum computer and is recommended when preparing quantum code to execute on a QPU.

Example

Batch execution:

from ket import *

p = Process(execution="batch")
a, b = p.alloc(2)

CNOT(H(a), b) # Bell state preparation

d = dump(a + b)

p.execute()
# The value of `d` will only be available after executing the process

print(d.show())

CNOT(a, b)  # This instruction will raise an error since the process
            # has already executed.

Live execution:

from ket import *

p = Process(execution="batch")
a, b = p.alloc(2)

CNOT(H(a), b) # Bell state preparation

# The value of the dump is available right after
print(dump(a + b).show())

CNOT(a, b)  # This instruction can execute normally
H(a)

print(dump(a + b).show())

Parameters:

• configuration – Configuration definition for third-party quantum execution. Defaults to None.

• num_qubits – Number of qubits for the KBW simulator. If None and simulator=="sparse", defaults to 32; otherwise, defaults to 12.

• simulator – Simulation mode for the KBW simulator. If None, defaults to "sparse".

• execution – Execution mode for the KBW simulator. If None, defaults to "live".

alloc(num_qubits: int = 1) → Quant

Allocate a specified number of qubits and return a Quant object.

Parameters:

num_qubits – The number of qubits to allocate. Defaults to 1.

Returns:

A list like object representing the allocated qubits.

Example

>>> from ket import Process
>>> p = Process()
>>> qubits = p.alloc(3)
>>> print(qubits)
<Ket 'Quant' [0, 1, 2] pid=0x...>

The alloc method allocates the specified number of qubits and returns a Quant object. Each qubit is assigned a unique index, and the resulting Quant object encapsulates the allocated qubits along with a reference to the parent Process object.

get_instructions() → list[dict[str, Any]]

Retrieve quantum instructions from the quantum process.

Returns:

A list of dictionaries containing quantum instructions extracted from the process.

The get_instructions method retrieves the quantum instructions from the prepared quantum process. It internally calls the instructions_json method to obtain the instructions fom the Rust library in JSON format, converts the byte data into a list of dictionaries, and returns the result.

Note

Ensure that the quantum process has been appropriately prepared for execution using the prepare_for_execution method before calling this method. The returned instructions provide insights into the quantum circuit and can be useful for debugging or analysis purposes.

Example

>>> from ket import *
>>> p = Process()
>>> a, b = p.alloc(2)
>>> CNOT(H(a), b)
>>> # Get quantum instructions
>>> instructions = p.get_instructions()
>>> pprint(instructions)
[{'Alloc': {'target': 0}},
 {'Alloc': {'target': 1}},
 {'Gate': {'control': [], 'gate': 'Hadamard', 'target': 0}},
 {'Gate': {'control': [0], 'gate': 'PauliX', 'target': 1}}]

get_isa_instructions() → list[dict[str, Any]] | None

Retrieve transpiled quantum instructions from the quantum process.

Returns:

A list of dictionaries containing quantum instructions extracted from the process if the process has been transpiled, otherwise None.

get_metadata() → dict[str, Any]

Retrieve metadata from the quantum process.

Returns:

A dictionary containing metadata information extracted from the process.

The get_metadata method retrieves metadata from the prepared quantum process. It internally calls the metadata_json method to obtain the metadata in JSON format, converts the byte data into a dictionary, and returns the result.

Note

Ensure that the quantum process has been appropriately prepared for execution using the prepare_for_execution method before calling this method. The returned metadata provides information about the quantum circuit execution, including depth, gate count, qubit simultaneous operations, status, execution time, and timeout.

Example

>>> from ket import Process
>>> p = Process()
>>> a, b = p.alloc(2)
>>> CNOT(H(a), b)
>>> # Get metadata
>>> metadata = p.get_metadata()
>>> pprint(metadata)
{'depth': 2,
 'execution_time': None,
 'gate_count': {'1': 1, '2': 1},
 'qubit_simultaneous': 2,
 'status': 'Live',
 'timeout': None}

class Quant(*, qubits: list[int], process: Process)

List of qubits.

This class represents a list of qubit indices within a quantum process. Direct instantiation of this class is not recommended. Instead, it should be created by calling the alloc method.

A Quant serves as a fundamental quantum object where quantum operations should be applied.

Example

from ket import *
# Create a quantum process
p = Process()

# Allocate 2 qubits
q1 = p.alloc(2)

# Apply a Hadamard gates on the first qubit of `q1`
H(q1[0])

# Allocate more 2 qubits
q2 = p.alloc(2)

# Concatenate two Quant objects
result_quant = q1 + q2
print(result_quant)  # <Ket 'Quant' [0, 1, 2, 3] pid=0x...>

# Use the fist qubit to control the application of
# a Pauli X gate on the other qubits
ctrl(result_quant[0], X)(result_quant[1:])

# Select qubits at specific indexes
selected_quant = result_quant.at([0, 1])
print(selected_quant)  # <Ket 'Quant' [0, 1] pid=0x...>

Supported operations:

• Addition (+): Concatenates two Quant objects. The processes must be the same.

• Indexing ([index]): Returns a new Quant object with selected qubits based on the provided index.

• Iteration (for q in qubits): Allows iterating over qubits in a Quant object.

• Reversal (reversed(qubits)): Returns a new Quant object with reversed qubits.

• Length (len(qubits)): Returns the number of qubits in the Quant object.

at(index: list[int]) → Quant

Return a subset of qubits at specified indices.

Create a new Quant object with qubit references at the positions defined by the provided index list.

Example

from ket import *

# Create a quantum process
p = Process()

# Allocate 5 qubits
q = p.alloc(5)

# Select qubits at odd indices (1, 3)
odd_qubits = q.at([1, 3])

Parameters:

index – List of indices specifying the positions of qubits to be included in the new Quant.

Returns:

A new Quant object containing the selected qubits.

class Samples(qubits: Quant, shots: int = 2048)

Quantum state measurement samples.

This class holds a reference for a measurement sample result. The result may not be available right after the sample call, especially in batch execution.

To read the value, access the attribute value. If the value is not available, the measurement will return None; otherwise, it will return a dictionary mapping measurement outcomes to their respective counts.

You can instantiate this class by calling the sample function.

Example

from ket import *

p = Process()
q = p.alloc(2)
CNOT(H(q[0]), q[1])
results = sample(q)

print(results.value)
# {0: 1042, 3: 1006}

Parameters:

• qubits – Qubits for which the measurement samples are obtained.

• shots – Number of measurement shots (default is 2048).

property value: dict[int, int] | None

Retrieve the measurement samples if available.

get() → dict[int, int]

Retrieve the measurement samples.

If the value is not available, the quantum process will execute to get the result.

histogram(**kwargs) → Figure

Generate a histogram representing the sample.

This method creates a histogram visualizing the probability distribution of the sample.

Note

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

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

Returns:

Histogram of sample measurement.

Functions ket.base

set_default_process_configuration([...])

Set default process configurations.

set_default_process_configuration(configuration=None, num_qubits: int | None = None, simulator: Literal['sparse', 'dense', 'dense v2'] | None = None, execution: Literal['live', 'batch'] | None = None, coupling_graph: list[tuple[int, int]] | None = None, force_configuration: bool = False)

Set default process configurations.

Configures default parameters for quantum processes using the specified options.

Parameters:

• configuration – Configuration definition for third-party quantum execution. Defaults to None.

• num_qubits – Number of qubits for the KBW simulator. Defaults to None.

• simulator – Simulation mode for the KBW simulator. Defaults to None.

• execution – Execution mode for the KBW simulator. Defaults to None.

• decompose – Enable quantum gate decomposition (increase execution time). Defaults to None.

• force_configuration – If set to True, the parameters defined in the Process constructor will overwrite those that are not None. Defaults to False.