Improve_quality_fixes: missing docstrings, and raised exceptions missing from docstrings

examples/introduction.ex.py

@@ -14,6 +14,8 @@
 #     name: python3
 # ---
 
+# %%
+"""An example to introduce running PROCESS"""
 # %% [markdown]
 # # Introduction to running PROCESS
 #

examples/optimum_solutions_comparison.ex.py

@@ -13,7 +13,8 @@
 #     language: python
 #     name: python3
 # ---
-
+# %%
+"""An example to compare optimum solutions from PROCESS"""
 # %% [markdown]
 # # Optimum solutions comparison notebook
 #

examples/scan.ex.py

@@ -14,6 +14,8 @@
 #     name: python3
 # ---
 
+# %%
+"""An example to run and visualise a PROCESS scan"""
 # %% [markdown] slideshow={"slide_type": "slide"}
 # # Running and visualising a PROCESS scan
 #

examples/single_model_evaluation.ex.py

@@ -14,6 +14,8 @@
 #     name: python3
 # ---
 
+# %%
+"""An example to evaluate a single PROCESS model"""
 # %% [markdown]
 # # Evaluating a single PROCESS model
 # When understanding or investigating an individual model within Process,
@@ -54,6 +56,7 @@
 # Doesn't crash after running a once-through
 # Print initial values of interest
 def print_values():
+    """Function to print values of some variables"""
     print(
         "W frac = "
         f"{single_run.data.impurity_radiation.f_nd_impurity_electron_array[13]:.3e}"

examples/vary_run_example.ex.py

@@ -14,6 +14,8 @@
 #     name: python3
 # ---
 
+# %%
+"""An example to demonstrate VaryRun"""
 # %% [markdown]
 # # Demonstration of VaryRun
 

process/core/caller.py

@@ -1,3 +1,5 @@
+"""Module to call physics and engineering models"""
+
 from __future__ import annotations
 
 import logging

process/core/constants.py

@@ -1,3 +1,5 @@
+"""Library of constants used in PROCESS."""
+
 IOTTY = 6
 """Standard output unit identifier"""
 

process/core/exceptions.py

@@ -1,3 +1,6 @@
+"""Base exceptions from which other PROCESS exceptions are derived"""
+
+
 class ProcessError(Exception):
     """A base Exception to derive other PROCESS exceptions from"""
 

process/core/init.py

@@ -1,3 +1,5 @@
+"""Routines for PROCESS initialisation."""
+
 from __future__ import annotations
 
 import datetime
@@ -238,6 +240,12 @@ def check_process(inputs, data):  # noqa: ARG001
 
     This routine performs a sanity check of the input variables
     and ensures other dependent variables are given suitable values.
+
+    Raises
+    ------
+    ProcessValidationError
+        If there is a problem with the contents of the input file.
+        See individual ProcessValidationError instances for more details.
     """
     # Check that there are sufficient iteration variables
     if data.numerics.nvar < data.numerics.neqns:

process/core/solver/iteration_variables.py

@@ -1,3 +1,5 @@
+"""Module containing iteration variable initialisation routines"""
+
 from __future__ import annotations
 
 import logging
@@ -17,6 +19,8 @@
 
 @dataclass
 class IterationVariable:
+    """Dataclass holding information about iteration variables"""
+
     name: str
     """The name of the variable"""
     module: str | Any
@@ -250,6 +254,12 @@ def check_iteration_variable(iteration_variable_value, name: str = ""):
 
     name: str :
          (Default value = "")
+
+    Raises
+    ------
+    ProcessValueError
+        If an iteration variable is 0 or very close, or if an iteration
+        variable is NaN or infinity
     """
     if abs(iteration_variable_value) <= 1e-12:
         error_msg = f"Iteration variable {name} is 0 (or very close)"
@@ -267,6 +277,11 @@ def check_iteration_variable(iteration_variable_value, name: str = ""):
 def load_iteration_variables(data):
     """
     Loads the physics and engineering variables into the optimisation variable array.
+
+    Raises
+    ------
+    ProcessValueError
+        If iteration variable is missing
     """
     for i in range(data.numerics.nvar):
         variable_index = data.numerics.ixc[i]

process/core/solver/objectives.py

@@ -33,6 +33,11 @@ def objective_function(minmax: int, data: DataStructure) -> float:
     data: DataStructure
         data structure object for providing data to the
         objective function
+
+    Raises
+    ------
+    ProcessValueError
+        If minmax=15 not used with i_plant_availability=1
     """
     try:
         figure_of_merit = FiguresOfMerit(abs(minmax))

process/core/solver/solver.py

@@ -359,6 +359,11 @@ def get_solver(data: DataStructure, solver_name: str = "vmcon") -> _Solver:
     -------
     _Solver
         solver to use for optimisation
+
+    Raises
+    ------
+    ProcessValueError
+        If solver name is not an inbuilt PROCESS solver or recognised package
     """
     solver: _Solver
 
@@ -390,6 +395,11 @@ def load_external_solver(package: str):
     ----------
     package: str :
 
+    Raises
+    ------
+    AttributeError
+        If module does not have a '__process_solver__' attribute
+
     """
     module = importlib.import_module(package)
 

process/core/solver/solver_handler.py

@@ -1,3 +1,5 @@
+"""Module containing solver handler routines"""
+
 from process.core.solver.evaluators import Evaluators
 from process.core.solver.iteration_variables import (
     load_iteration_variables,

process/data/__init__.py

@@ -0,0 +1 @@
+"""Module containing impurity data"""

process/data_structure/__init__.py

@@ -1,3 +1,5 @@
+"""Module containing data structure variables"""
+
 from process.data_structure import (
     blanket_variables,
     build_variables,

process/main.py

@@ -290,6 +290,7 @@ def __init__(
 
     @property
     def mfile_path(self):
+        """Mfile path"""
         return self.config.outfile
 
     def run(self):
@@ -383,7 +384,15 @@ def set_filenames(self, filepath_out):
         self.set_mfile()
 
     def set_input(self):
-        """Validate and set the input file path."""
+        """Validate and set the input file path.
+
+        Raises
+        ------
+        ValueError
+            If input filename doesn't end in 'IN.DAT'
+        FileNotFoundError
+            If input file not found
+        """
         # Check input file ends in "IN.DAT", then save prefix
         # (the part before the IN.DAT)
         if not self.input_file.name.endswith("IN.DAT"):
@@ -433,7 +442,13 @@ def initialise(self):
         self.data.numerics.ixc[:n].sort()
 
     def run_scan(self):
-        """Create scan object if required."""
+        """Create scan object if required.
+
+        Raises
+        ------
+        ValueError
+            If invalid ioptimiz value selected
+        """
         # TODO Move this solver logic up to init?
         # ioptimz == 1: optimisation
         if self.data.numerics.ioptimz == PROCESSRunMode.OPTIMISATION:
@@ -488,6 +503,11 @@ def validate_input(self, replace_obsolete: bool = False):
         If obsolete variables are found, and if `replace_obsolete` is set to True,
         they are either removed or replaced by their updated names as specified
         in the OBS_VARS dictionary.
+
+        Raises
+        ------
+        ValueError
+            If obsolete variables are present in the input file.
         """
         obsolete_variables = ov.OBS_VARS
         obsolete_vars_help_message = ov.OBS_VARS_HELP
@@ -600,6 +620,11 @@ def validate_user_model(self):
 
         Ensures that the corresponding model variable in Models is defined
         and that any relevant switches are set correctly.
+
+        Raises
+        ------
+        ValueError
+            If user-created model not injected correctly
         """
         # try and get costs model
         try:
@@ -719,6 +744,14 @@ def __init__(self, data: DataStructure):
 
     @property
     def costs(self) -> Model:
+        """Set up cost model parameters
+
+        Raises
+        ------
+        ValueError
+            If custom costs not initialised, or if costs model
+            is unknown
+        """
         if CostModels(self.data.costs.i_cost_model) == CostModels.PROCESS_1990:
             return self._costs_1990
         if CostModels(self.data.costs.i_cost_model) == CostModels.KOVARI_2014:
@@ -737,6 +770,7 @@ def costs(self, value: Model):
 
     @property
     def models(self) -> tuple[Model, ...]:
+        """Set up the models"""
         # At the moment, this property just returns models
         # that implement the Model interface.
         # Eventually every Model will comply and then
@@ -796,6 +830,7 @@ def models(self) -> tuple[Model, ...]:
         )
 
     def setup_data_structure(self):
+        """Set up the data structure"""
         # This Models class should be replaced with a dataclass so we can
         # iterate over the `fields`.
         # This can be a disgusting temporary measure :(

process/models/__init__.py

@@ -0,0 +1 @@
+"""Module containing physics and engineering models"""

process/models/availability.py

@@ -1,3 +1,5 @@
+"""Module containing plant availability routines"""
+
 import logging
 import math
 
@@ -40,6 +42,7 @@ def __init__(self):
         self.outfile = constants.NOUT  # output file unit
 
     def output(self):
+        """Output availability information"""
         self.run(output=True)
 
     def run(self, output: bool = False):
@@ -57,6 +60,12 @@ def run(self, output: bool = False):
         ----------
         output :
             indicate whether output should be written to the output file, or not
+
+        Raises
+        ------
+        ProcessValueError
+            If i_plant_availability == 3, as this is for a spherical tokamak and
+            so need to use itart=1 for that model
         """
         if self.data.costs.i_plant_availability == 3:
             if self.data.physics.itart != 1:

process/models/blankets/__init__.py

@@ -0,0 +1 @@
+"""Module containing blanket library routines"""