Improve_quality_fixes: missing docstrings, and raised exceptions missing from docstrings PART 1

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/io/variable_metadata.py

@@ -1,8 +1,12 @@
+"""Module containing variable metadata"""
+
 from dataclasses import dataclass
 
 
 @dataclass
 class VariableMetadata:
+    """Variable metadata"""
+
     latex: str
     description: str
     units: str

process/core/io/vary_run/__init__.py

@@ -1,3 +1,5 @@
+"""Module containing VaryRun routines"""
+
 from process.core.io.vary_run.config import RunProcessConfig
 from process.core.io.vary_run.tools import vary_iteration_variables
 

process/core/io/vary_run/config.py

@@ -54,6 +54,13 @@ class ProcessConfig:
 
     @classmethod
     def from_file(cls, filename: str | Path, solver: str = "vmcon"):
+        """Get the configuration parameters from the .conf file
+
+        Raises
+        ------
+        FileNotFoundError
+            If config file is not found
+        """
         if isinstance(filename, str):
             filename = Path(filename)
 
@@ -130,6 +137,14 @@ def get_comment(filename):
         return ""
 
     def __post_init__(self):
+        """Set the first iteration and check the IN.DAT specified in the
+        .conf file exists
+
+        Raises
+        ------
+        FileNotFoundError
+            If the original IN.DAT specified in the .conf file does not exist
+        """
         self._current_iteration = 0
         self._base_input = "{}_IN.DAT"
         self._base_output = "{}_MFILE.DAT"
@@ -141,9 +156,17 @@ def __post_init__(self):
             )
 
     def __iter__(self):
+        """Iterator for VaryRun"""
         return self
 
     def __next__(self):
+        """Perform an iteration of VaryRun
+
+        Raises
+        ------
+        StopIteration
+            If VaryRun reaches the maximum number of allowed iterations
+        """
         _neqns, itervars = get_neqns_itervars(in_dat=self.initial_infile, wdir=self.wdir)
 
         lbs, ubs = get_variable_range(
@@ -176,18 +199,22 @@ def __next__(self):
 
     @property
     def infile(self):
+        """Current iteration's IN.DAT"""
         return self._base_input.format(self._current_iteration)
 
     @property
     def outfile(self):
+        """Current iteration's MFILE.DAT"""
         return self._base_output.format(self._current_iteration)
 
     @property
     def prev_outfile(self):
+        """Previous iteration's IN.DAT"""
         return self._base_output.format(self._current_iteration - 1)
 
     @property
     def initial_infile(self):
+        """Initial IN.DAT"""
         return self._base_input.format(0)
 
     def echo(self):
@@ -304,6 +331,11 @@ def run_process(input_path: Path, solver: str = "vmcon"):
             the input file to run on
         solver :
             which solver to use, as specified in solver.py, defaults to "vmcon"
+
+        Raises
+        ------
+        KeyboardInterrupt
+            If run interrupted by user
         """
         # TODO should call SingleRun directly...at least this is not a subprocess!
         from process.main import process_cli  # noqa:PLC0415
@@ -356,6 +388,7 @@ class RunProcessConfig(ProcessConfig):
 
     @classmethod
     def from_file(cls, filename: str | Path = "run_process.conf", solver: str = "vmcon"):
+        """Setup the VaryRun config"""
         self = super().from_file(filename, solver)
 
         no_allowed_unfeasible = (
@@ -456,6 +489,13 @@ def get_dictvar(filename):
         return dictvar
 
     def __next__(self):
+        """Process the result from the iteration of VaryRun
+
+        Raises
+        ------
+        StopIteration
+            If feasible solution found
+        """
         indat, mfile, itervars, lbs, ubs = super().__next__()
 
         if not process_stopped(wdir=self.wdir, mfile=mfile):

process/core/io/vary_run/tools.py

@@ -26,6 +26,11 @@
 def get_neqns_itervars(in_dat, wdir="."):
     """Returns the number of equations and a list of variable
     names of all iteration variables
+
+    Raises
+    ------
+    ValueError
+        If the number of iteration variables is not consistent
     """
     in_dat = InDat(Path(wdir, in_dat))
 
@@ -133,6 +138,11 @@ def get_variable_range(itervars, factor, indat, data: DataStructure, wdir="."):
 def check_in_dat(filename):
     """Tests IN.DAT during setup:
     1)Are ixc bounds outside of allowed input ranges?
+
+    Raises
+    ------
+    RuntimeError
+        If an iteration variable does not have a corresponding input variable
     """
     # Load dicts from dicts JSON file
     dicts = get_dicts()

process/core/model.py

@@ -1,3 +1,5 @@
+"""Module containing routines to set up the data structure and models"""
+
 import abc
 from dataclasses import dataclass, fields
 
@@ -45,6 +47,8 @@
 
 @dataclass(kw_only=True)
 class DataStructure:
+    """Dataclass holding the data structure"""
+
     water_use: WaterUseData = initialise_later
     costs_2015: Cost2015Data = initialise_later
     cs_fatigue: CSFatigueData = initialise_later
@@ -83,12 +87,15 @@ class DataStructure:
     numerics: NumericsData = initialise_later
 
     def __post_init__(self):
+        """Set up the data structure"""
         for f in fields(self):
             if getattr(self, f.name) is initialise_later:
                 setattr(self, f.name, f.type())
 
 
 class Model(abc.ABC):
+    """Set up Model base class"""
+
     data: DataStructure
 
     @abc.abstractmethod

process/core/output.py

@@ -1,3 +1,5 @@
+"""Module containing routine to write the results to the main output file (OUT.DAT)"""
+
 from process.core.log import logging_model_handler
 from process.data_structure.blanket_variables import BlktModelTypes
 from process.models.tfcoil.base import TFConductorModel
@@ -18,6 +20,10 @@ def write(models, data, _outfile):
     _outfile : int
         Fortran output unit identifier
 
+    Raises
+    ------
+    ValueError
+        If unsupported superconducting TF turn type is used
     """
     # ensure we are capturing warnings that occur in the 'output' stage
     # as these are warnings that occur at our solution point.

process/core/process_output.py

@@ -229,4 +229,5 @@ def ovarrf(file, descr: str, varnam: str, value, output_flag: str = ""):
 
 
 def obuild(file, descr: str, thick: float, total: float, variable_name: str = ""):
+    """Write build variables to the output file via its identifier."""
     write(file, f"{descr:<50}{thick:.3e}{' ':<10}{total:.3e}  {variable_name}")

process/core/solver/__init__.py

@@ -0,0 +1 @@
+"""Module containing solver routines"""