mqt.predictor.rl

MQT Predictor.

This file is part of the MQT Predictor library released under the MIT license. See README.md or go to https://github.com/munich-quantum-toolkit/predictor for more information.

Submodules

• mqt.predictor.rl.actions
• mqt.predictor.rl.helper
• mqt.predictor.rl.parsing
• mqt.predictor.rl.predictor
• mqt.predictor.rl.predictorenv

Package Contents

class Predictor(figure_of_merit: Predictor.__init__.figure_of_merit, device: Target, path_training_circuits: Path | None = None, logger_level: int = logging.INFO)

The Predictor class is used to train a reinforcement learning model for a given figure of merit and device such that it acts as a compiler.

env

device_name

figure_of_merit

compile_as_predicted(qc: qiskit.QuantumCircuit | str) → tuple[qiskit.QuantumCircuit, list[str]]

Compiles a given quantum circuit such that the given figure of merit is maximized by using the respectively trained optimized compiler.

Parameters:

qc – The quantum circuit to be compiled or the path to a qasm file containing the quantum circuit.

Returns:

A tuple containing the compiled quantum circuit and the compilation information. If compilation fails, False is returned.

Raises:

RuntimeError – If an error occurs during compilation.

train_model(timesteps: int = 1000, verbose: int = 2, test: bool = False, seed: int | None = None) → None

Trains all models for the given reward functions and device.

Parameters:

• timesteps – The number of timesteps to train the model. Defaults to 1000.

• verbose – The verbosity level. Defaults to 2.

• test – Whether to train the model for testing purposes. Defaults to False.

• seed – The random seed to use for reproducible training. Set to None to use true randomness. Defaults to None.

rl_compile(qc: qiskit.QuantumCircuit | str, device: Target | None, figure_of_merit: rl_compile.figure_of_merit | None = 'expected_fidelity', predictor_singleton: Predictor | None = None) → tuple[qiskit.QuantumCircuit, list[str]]

Compiles a given quantum circuit to a device optimizing for the given figure of merit.

Parameters:

• qc – The quantum circuit to be compiled. If a string is given, it is assumed to be a path to a qasm file.

• device – The device to compile to.

• figure_of_merit – The figure of merit to be used for compilation. Defaults to “expected_fidelity”.

• predictor_singleton – A predictor object that is used for compilation to reduce compilation time when compiling multiple quantum circuits. If None, a new predictor object is created. Defaults to None.

Returns:

A tuple containing the compiled quantum circuit and the compilation information. If compilation fails, False is returned.

Raises:

ValueError – If figure_of_merit or device is None and predictor_singleton is also None.

class PredictorEnv(device: Target, reward_function: figure_of_merit = 'expected_fidelity', path_training_circuits: Path | None = None)

Bases: gymnasium.Env

Predictor environment for reinforcement learning.

path_training_circuits

action_set

actions_synthesis_indices = []

actions_layout_indices = []

actions_routing_indices = []

actions_mapping_indices = []

actions_opt_indices = []

actions_final_optimization_indices = []

used_actions: list[str] = []

device

action_terminate_index = 0

reward_function = 'expected_fidelity'

action_space

num_steps = 0

num_qubits_uncompiled_circuit = 0

layout: TranspileLayout | None = None

has_parameterized_gates = False

rng

observation_space

filename = ''

step(action: int) → tuple[dict[str, Any], float, bool, bool, dict[Any, Any]]

Executes the given action and returns the new state, the reward, whether the episode is done, whether the episode is truncated and additional information.

Parameters:

action – The action to be executed, represented by its index in the action set.

Returns:

A tuple containing the new state as a feature dictionary, the reward value, whether the episode is done, whether the episode is truncated, and additional information.

Raises:

RuntimeError – If no valid actions are left.

calculate_reward() → float

Calculates and returns the reward for the current state.

render() → None

Renders the current state.

reset(qc: Path | str | qiskit.QuantumCircuit | None = None, seed: int | None = None, options: dict[str, Any] | None = None) → tuple[dict[str, Any], dict[str, Any]]

Resets the environment to the given state or a random state.

Parameters:

• qc – The quantum circuit to be compiled or the path to a qasm file containing the quantum circuit. Defaults to None.

• seed – The seed to be used for the random number generator. Defaults to None.

• options – Additional options. Defaults to None.

Returns:

The initial state and additional information.

action_masks() → list[bool]

Returns a list of valid actions for the current state.

apply_action(action_index: int) → qiskit.QuantumCircuit | None

Applies the given action to the current state and returns the altered state.

Parameters:

action_index – The index of the action to be applied, which must be in the action set.

Returns:

The altered quantum circuit after applying the action, or None if the action is to terminate the compilation.

Raises:

ValueError – If the action index is not in the action set or if the action origin is not supported.

is_circuit_laid_out(circuit: qiskit.QuantumCircuit, layout: TranspileLayout | Layout) → bool

True if every logical qubit in the circuit has a physical assignment.

is_circuit_synthesized(circuit: qiskit.QuantumCircuit) → bool

Check if the circuit uses only native gates of the device.

Verifies that every gate name in the circuit is present in device.operation_names, equivalent to the GatesInBasis pass.

Parameters:

circuit – QuantumCircuit to check.

Returns:

True if all gates are native to the device.

is_circuit_routed(circuit: qiskit.QuantumCircuit, coupling_map: CouplingMap) → bool

Check if a circuit is fully routed to the device, including directionality.

A circuit is considered routed if all two-qubit gates are on qubit pairs that exist as directed edges in the device coupling map.

After a layout pass the circuit’s qubits are already physical qubits, so circuit.find_bit(q).index gives the physical index directly — consistent with how reward.py looks up gate calibrations.

Parameters:

• circuit – QuantumCircuit to check.

• coupling_map – CouplingMap of the target device.

Returns:

True if fully routed, False otherwise.

determine_valid_actions_for_state() → list[int]

Determine valid actions based on circuit state: synthesized, mapped, routed.