💡 added docstrings for raised errors (#405)

## Description

This PR adds docstring documentation for raised errors. This resolves
#143.


## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

Author: nquetschlich

CHANGELOG.md

@@ -9,6 +9,10 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ## [Unreleased]
 
+### Added
+
+- 📝 Added docstrings for raised errors for all methods ([#405]) ([**@nquetschlich**])
+
 ### Changed
 
 - ✨ Improved the ML part and its usability ([#403]) ([**@nquetschlich**])
@@ -27,6 +31,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 <!-- PR links -->
 
+[#405]: https://github.com/munich-quantum-toolkit/predictor/pull/405
 [#403]: https://github.com/munich-quantum-toolkit/predictor/pull/403
 [#401]: https://github.com/munich-quantum-toolkit/predictor/pull/401
 [#393]: https://github.com/munich-quantum-toolkit/predictor/pull/393

src/mqt/predictor/ml/predictor.py

@@ -163,6 +163,9 @@ def _compile_all_circuits_devicewise(
             path_uncompiled_circuits: The path to the directory containing the circuits to be compiled. Defaults to None.
             path_compiled_circuits: The path to the directory where the compiled circuits should be saved. Defaults to None.
             logger_level: The level of the logger. Defaults to logging.INFO.
+
+        Raises:
+            RuntimeError: If an error occurs during compilation.
         """
         logger.setLevel(logger_level)
 
@@ -306,6 +309,9 @@ def _generate_training_sample(
 
         Returns:
             Training_sample, circuit_name, scores
+
+        Raises:
+            RuntimeError: If the file is not a qasm file or if no compiled circuits are found for the given file.
         """
         logger.setLevel(logger_level)
 
@@ -370,6 +376,9 @@ def train_random_forest_model(
         Returns:
             Either a trained RandomForestRegressor to estimate the Hellinger distance for a single device,
             or a trained RandomForestClassifier to score multiple devices according to a specific figure of merit.
+
+        Raises:
+            ValueError: If the figure of merit is 'hellinger_distance' and more than one device is provided.
         """
         tree_param = [
             {
@@ -404,7 +413,11 @@ def train_random_forest_model(
         return mdl.best_estimator_
 
     def _get_prepared_training_data(self) -> TrainingData:
-        """Returns the training data for the given figure of merit."""
+        """Returns the training data for the given figure of merit.
+
+        Raises:
+            FileNotFoundError: If the training data files are not found.
+        """
         with resources.as_file(get_path_training_data() / "training_data_aggregated") as path:
             prefix = f"{self.figure_of_merit}.npy"
             file_data = path / f"training_data_{prefix}"
@@ -451,6 +464,10 @@ def predict_device_for_figure_of_merit(
 
     Returns:
         The probabilities for all supported quantum devices to be the most suitable one for the given quantum circuit.
+
+    Raises:
+        FileNotFoundError: If the ML model is not trained yet.
+        ValueError: If no suitable device is found for the given quantum circuit.
     """
     if isinstance(qc, Path) and qc.exists():
         qc = QuantumCircuit.from_qasm_file(qc)

src/mqt/predictor/reward.py

@@ -73,7 +73,19 @@ def expected_fidelity(qc: QuantumCircuit, device: Target, precision: int = 10) -
 
 
 def calc_qubit_index(qargs: list[Qubit], qregs: list[QuantumRegister], index: int) -> int:
-    """Calculates the global qubit index for a given quantum circuit and qubit index."""
+    """Calculates the global qubit index for a given quantum circuit and qubit index.
+
+    Arguments:
+        qargs: The qubits of the quantum circuit.
+        qregs: The quantum registers of the quantum circuit.
+        index: The index of the qubit in the qargs list.
+
+    Returns:
+        The global qubit index of the given qubit in the quantum circuit.
+
+    Raises:
+        ValueError: If the qubit index is not found in the quantum registers.
+    """
     offset = 0
     for reg in qregs:
         if qargs[index] not in reg:
@@ -188,7 +200,17 @@ def estimated_success_probability(qc: QuantumCircuit, device: Target, precision:
 
 
 def esp_data_available(device: Target) -> bool:
-    """Check if calibration data to calculate ESP is available for the device."""
+    """Check if calibration data to calculate ESP is available for the device.
+
+    Arguments:
+        device: The device to be checked for calibration data.
+
+    Returns:
+        True if all required calibration data is available, False otherwise.
+
+    Raises:
+        ValueError: If any required calibration data is missing or invalid.
+    """
     single_qubit_gates = set()
     two_qubit_gates = set()
 

src/mqt/predictor/rl/actions.py

@@ -151,7 +151,11 @@ class DeviceDependentAction(Action):
 
 
 def register_action(action: Action) -> Action:
-    """Registers a new action in the global actions registry."""
+    """Registers a new action in the global actions registry.
+
+    Raises:
+        ValueError: If an action with the same name is already registered.
+    """
     if action.name in _ACTIONS:
         msg = f"Action with name {action.name} already registered."
         raise ValueError(msg)
@@ -160,7 +164,11 @@ def register_action(action: Action) -> Action:
 
 
 def remove_action(name: str) -> None:
-    """Removes an action from the global actions registry by name."""
+    """Removes an action from the global actions registry by name.
+
+    Raises:
+        ValueError: If no action with the given name is registered.
+    """
     if name not in _ACTIONS:
         msg = f"No action with name {name} is registered."
         raise KeyError(msg)

src/mqt/predictor/rl/helper.py

@@ -39,6 +39,9 @@ def get_state_sample(max_qubits: int, path_training_circuits: Path, rng: Generat
 
     Returns:
         A tuple containing the random quantum circuit and the path to the file from which it was read.
+
+    Raises:
+        RuntimeError: If no quantum circuit could be read from the training circuits folder.
     """
     file_list = list(path_training_circuits.glob("*.qasm"))
 

src/mqt/predictor/rl/parsing.py

@@ -94,6 +94,9 @@ def get_bqskit_native_gates(device: Target) -> list[gates.Gate]:
 
     Returns:
         The native gates of the given device as BQSKit gates.
+
+    Raises:
+        ValueError: If a gate in the device is not supported in BQSKit.
     """
     gate_map = {
         # --- 1-qubit gates ---

src/mqt/predictor/rl/predictor.py

@@ -59,6 +59,9 @@ def compile_as_predicted(
 
         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.
         """
         trained_rl_model = load_model("model_" + self.figure_of_merit + "_" + self.device_name)
 
@@ -134,6 +137,9 @@ def load_model(model_name: str) -> MaskablePPO:
 
     Returns:
         The loaded model.
+
+    Raises:
+        FileNotFoundError: If the model file does not exist.
     """
     path = get_path_trained_model()
     if Path(path / (model_name + ".zip")).is_file():
@@ -160,6 +166,9 @@ def rl_compile(
 
     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.
     """
     if predictor_singleton is None:
         if figure_of_merit is None:

src/mqt/predictor/rl/predictorenv.py

@@ -73,7 +73,16 @@ def __init__(
         reward_function: figure_of_merit = "expected_fidelity",
         path_training_circuits: Path | None = None,
     ) -> None:
-        """Initializes the PredictorEnv object."""
+        """Initializes the PredictorEnv object.
+
+        Arguments:
+            device: The target device to be used for compilation.
+            reward_function: The figure of merit to be used for the reward function. Defaults to "expected_fidelity".
+            path_training_circuits: The path to the training circuits folder. Defaults to None, which uses the default path.
+
+        Raises:
+            ValueError: If the reward function is "estimated_success_probability" and no calibration data is available for the device or if the reward function is "estimated_hellinger_distance" and no trained model is available for the device.
+        """
         logger.info("Init env: " + reward_function)
 
         self.path_training_circuits = path_training_circuits or get_path_training_circuits()
@@ -156,7 +165,17 @@ def __init__(
         self.filename = ""
 
     def step(self, 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."""
+        """Executes the given action and returns the new state, the reward, whether the episode is done, whether the episode is truncated and additional information.
+
+        Arguments:
+            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.
+        """
         self.used_actions.append(str(self.action_set[action].name))
         altered_qc = self.apply_action(action)
         if not altered_qc:
@@ -271,7 +290,17 @@ def action_masks(self) -> list[bool]:
         return action_mask
 
     def apply_action(self, action_index: int) -> QuantumCircuit | None:
-        """Applies the given action to the current state and returns the altered state."""
+        """Applies the given action to the current state and returns the altered state.
+
+        Arguments:
+            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.
+        """
         if action_index not in self.action_set:
             msg = f"Action {action_index} not supported."
             raise ValueError(msg)
@@ -358,6 +387,18 @@ def _apply_tket_action(self, action: Action, action_index: int) -> QuantumCircui
         return altered_qc
 
     def _apply_bqskit_action(self, action: Action, action_index: int) -> QuantumCircuit:
+        """Applies the given BQSKit action to the current state and returns the altered state.
+
+        Arguments:
+            action: The BQSKit action to be applied.
+            action_index: The index of the action in the action set.
+
+        Returns:
+            The altered quantum circuit after applying the action.
+
+        Raises:
+            ValueError: If the action index is not in the action set or if the action origin is not supported.
+        """
         bqskit_qc = qiskit_to_bqskit(self.state)
         assert callable(action.transpile_pass)
         if action_index in self.actions_opt_indices:

src/mqt/predictor/utils.py

@@ -37,7 +37,20 @@ def timeout_watcher(
     args: list[QuantumCircuit | figure_of_merit | str | RL_Predictor],
     timeout: int,
 ) -> tuple[QuantumCircuit, list[str]] | bool:
-    """Method that stops a function call after a given timeout limit."""
+    """Method that stops a function call after a given timeout limit.
+
+    Arguments:
+        func: The function to be called.
+        args: The arguments to be passed to the function.
+        timeout: The timeout limit in seconds.
+
+    Returns:
+        The result of the function call if it finishes within the timeout limit, otherwise False.
+
+    Raises:
+        RuntimeWarning: If the timeout is not supported on the current platform (e.g., Windows).
+        TimeoutExceptionError: If the function call exceeds the timeout limit.
+    """
     if sys.platform == "win32":
         warn("Timeout is not supported on Windows.", category=RuntimeWarning, stacklevel=2)
         return func(*args) if isinstance(args, tuple | list) else func(args)