Fix some linter warnings

Author: felsenhower

cython/main.py

@@ -1,3 +1,8 @@
+"""
+partdiff-py is a Python port of partdiff.
+This is the "cython" variant. It uses Cython to translate the calculate method to C.
+"""
+
 from calculate import calculate
 from partdiff_common import (
     check_float_info,
@@ -14,7 +19,7 @@ def main() -> None:
     arguments = init_arguments(options)
     results = calculate(arguments, options)
     display_statistics(arguments, options, results)
-    display_matrix(arguments, options, results)
+    display_matrix(options, results)
 
 
 if __name__ == "__main__":

np_vectorize/main.py

@@ -1,3 +1,8 @@
+"""
+partdiff-py is a Python port of partdiff.
+This is the "np_vectorize" variant. It uses numpy's vectorized math for the Jacobi variant.
+"""
+
 from itertools import count
 from time import time
 
@@ -21,6 +26,15 @@
 def calculate_jacobi(
     arguments: CalculationArguments, options: Options
 ) -> CalculationResults:
+    """Solve the Poisson equation iteratively using the Jacobi method.
+
+    Args:
+        arguments (CalculationArguments): The internal representation of the problem.
+        options (Options): The program options.
+
+    Returns:
+        CalculationResults: The results of the calculation.
+    """
     start_time = time()
     n = arguments.n
     tensor = arguments.tensor
@@ -60,6 +74,15 @@ def calculate_jacobi(
 def calculate_gauss_seidel(
     arguments: CalculationArguments, options: Options
 ) -> CalculationResults:
+    """Solve the Poisson equation iteratively using the Gauß-Seidel method.
+
+    Args:
+        arguments (CalculationArguments): The internal representation of the problem.
+        options (Options): The program options.
+
+    Returns:
+        CalculationResults: The results of the calculation.
+    """
     start_time = time()
     n = arguments.n
     tensor = arguments.tensor
@@ -99,6 +122,15 @@ def calculate_gauss_seidel(
 
 
 def calculate(arguments: CalculationArguments, options: Options) -> CalculationResults:
+    """Solve the Poisson equation iteratively using the Jacobi or Gauß-Seidel method.
+
+    Args:
+        arguments (CalculationArguments): The internal representation of the problem.
+        options (Options): The program options.
+
+    Returns:
+        CalculationResults: The results of the calculation.
+    """
     match options.method:
         case CalculationMethod.JACOBI:
             return calculate_jacobi(arguments, options)
@@ -112,7 +144,7 @@ def main() -> None:
     arguments = init_arguments(options)
     results = calculate(arguments, options)
     display_statistics(arguments, options, results)
-    display_matrix(arguments, options, results)
+    display_matrix(options, results)
 
 
 if __name__ == "__main__":

numba/main.py

@@ -1,3 +1,8 @@
+"""
+partdiff-py is a Python port of partdiff.
+This is the "numba" variant. It uses numba to just-in-time compile the calculation.
+"""
+
 from time import time
 
 import numpy as np
@@ -30,6 +35,22 @@ def calculate_iterate(
     tensor: np.ndarray,
     perturbation_matrix: np.ndarray,
 ) -> tuple[np.ndarray, int, float]:
+    """The inner calculation part of the calculate method which is just-in-time compiled
+    with numba here.
+
+    Args:
+        method (CalculationMethod): The method (Gauß-Seidel or Jacobi).
+        termination (TerminationCondition): Termination (Iterations or Accuracy).
+        term_iteration (TermIterations): Max iterations.
+        term_accuracy (TermAccuracy): Min accuracy.
+        n (int): Problem size (matrix is (n+1)*(n+1)).
+        tensor (np.ndarray): The problem matrices.
+        perturbation_matrix (np.ndarray): Precomputed perturbation function values.
+
+    Returns:
+        tuple[np.ndarray, int, float]: A tuple containing the final matrix,
+            actual iterations performed, and residuum reached.
+    """
     stat_iteration = 0
     stat_accuracy = 0.0
     matrix_out = tensor[0, :, :]
@@ -68,6 +89,15 @@ def calculate_iterate(
 
 
 def calculate(arguments: CalculationArguments, options: Options) -> CalculationResults:
+    """Solve the Poisson equation iteratively using the Jacobi or Gauß-Seidel method.
+
+    Args:
+        arguments (CalculationArguments): The internal representation of the problem.
+        options (Options): The program options.
+
+    Returns:
+        CalculationResults: The results of the calculation.
+    """
     start_time = time()
     final_matrix, stat_iteration, stat_accuracy = calculate_iterate(
         options.method,
@@ -89,7 +119,7 @@ def main() -> None:
     arguments = init_arguments(options)
     results = calculate(arguments, options)
     display_statistics(arguments, options, results)
-    display_matrix(arguments, options, results)
+    display_matrix(options, results)
 
 
 if __name__ == "__main__":

partdiff_common/src/partdiff_common/__init__.py

@@ -1,34 +1,54 @@
-from partdiff_common.parse_args import (
-    Options,
-    CalculationMethod,
-    PerturbationFunction,
-    TerminationCondition,
-)
-from dataclasses import dataclass
-import numpy as np
+"""
+This module contains the shared parts of partdiff, e.g. all the stuff for
+initializing matrices or displaying statistics.
+"""
+
 import sys
+from dataclasses import dataclass
 from math import sin
 
+import numpy as np
 from pympler import asizeof
 
+from partdiff_common.parse_args import (
+    CalculationMethod,
+    Options,
+    PerturbationFunction,
+)
+
 
 @dataclass(frozen=True)
 class CalculationArguments:
+    """This class contains the internal representation of the problem, i.e. the
+    initialized matrices. All matrices have the size (n+1)*(n+1).
+    The tensor may be 1*(n+1)*(n+1) or 2*(n+1)*(n+1), depending on the method.
+    The perturbation matrix contains the precomputed values of the perturbation function.
+    """
+
     n: int
-    h: float
     tensor: np.ndarray
     perturbation_matrix: np.ndarray
 
 
 @dataclass(frozen=True)
 class CalculationResults:
+    """This class contains the final results of the calculation."""
+
     final_matrix: np.ndarray
     stat_iteration: int
     stat_accuracy: float
     duration: float
 
 
 def init_arguments(options: Options) -> CalculationArguments:
+    """Init the CalculationArguments.
+
+    Args:
+        options (Options): The program options.
+
+    Returns:
+        CalculationArguments: The initialized problem representation.
+    """
     n = (options.interlines * 8) + 9 - 1
     num_matrices = 2 if options.method == CalculationMethod.JACOBI else 1
     h = 1.0 / n
@@ -55,12 +75,22 @@ def init_arguments(options: Options) -> CalculationArguments:
             fpisin_i = fpisin * sin(pih * i)
             for j in range(1, n):
                 perturbation_matrix[i, j] = fpisin_i * sin(pih * j)
-    return CalculationArguments(n, h, tensor, perturbation_matrix)
+    return CalculationArguments(n, tensor, perturbation_matrix)
 
 
 def calculate_memory_usage(
     arguments: CalculationArguments, options: Options, results: CalculationResults
 ) -> float:
+    """Calculate the total memory usage.
+
+    Args:
+        arguments (CalculationArguments): The calculation arguments.
+        options (Options): The program options.
+        results (CalculationResults): The calculation results.
+
+    Returns:
+        float: The memory usage in MiB.
+    """
     memory_usage = 0
     for o in (arguments, options, results):
         memory_usage += asizeof.asizeof(o)
@@ -71,6 +101,13 @@ def calculate_memory_usage(
 def display_statistics(
     arguments: CalculationArguments, options: Options, results: CalculationResults
 ) -> None:
+    """Display statistics about the calculation.
+
+    Args:
+        arguments (CalculationArguments): The calculation arguments.
+        options (Options): The program options.
+        results (CalculationResults): The calculation results.
+    """
     memory_usage = calculate_memory_usage(arguments, options, results)
     print(f"Calculation time:       {results.duration:0.6f} s")
     print(f"Memory usage:           {memory_usage:0.6f} MiB")
@@ -83,9 +120,13 @@ def display_statistics(
     print("")
 
 
-def display_matrix(
-    arguments: CalculationArguments, options: Options, results: CalculationResults
-) -> None:
+def display_matrix(options: Options, results: CalculationResults) -> None:
+    """Display the final matrix in a 9x9 format.
+
+    Args:
+        options (Options): The program options.
+        results (CalculationResults): The calculation results.
+    """
     interlines = options.interlines
     final_matrix = results.final_matrix
     print("Matrix:")
@@ -97,6 +138,7 @@ def display_matrix(
 
 
 def check_float_info() -> None:
+    """Check that we're running a platform where Python's builtin float is double."""
     float_info = sys.float_info
     assert (float_info.max_exp, float_info.mant_dig) == (1024, 53), (
         "This application does only work on platforms where built-in float is IEEE 754 binary64, e.g. CPython.",

partdiff_common/src/partdiff_common/parse_args.py

@@ -1,11 +1,15 @@
+"""
+Partdiff argument parser.
+"""
+
 import argparse
 import inspect
 import typing
 from enum import Enum
 from typing import Annotated
 
 from annotated_types import Ge, Le
-from pydantic import TypeAdapter, ValidationError, Field
+from pydantic import Field, TypeAdapter, ValidationError
 from pydantic.dataclasses import dataclass
 
 

simple/main.py

@@ -1,3 +1,8 @@
+"""
+partdiff-py is a Python port of partdiff.
+This is the "simple" variant.
+"""
+
 from itertools import count
 from time import time
 
@@ -18,6 +23,15 @@
 
 
 def calculate(arguments: CalculationArguments, options: Options) -> CalculationResults:
+    """Solve the Poisson equation iteratively using the Jacobi or Gauß-Seidel method.
+
+    Args:
+        arguments (CalculationArguments): The internal representation of the problem.
+        options (Options): The program options.
+
+    Returns:
+        CalculationResults: The results of the calculation.
+    """
     start_time = time()
     n = arguments.n
     tensor = arguments.tensor
@@ -66,7 +80,7 @@ def main() -> None:
     arguments = init_arguments(options)
     results = calculate(arguments, options)
     display_statistics(arguments, options, results)
-    display_matrix(arguments, options, results)
+    display_matrix(options, results)
 
 
 if __name__ == "__main__":