Ocean/pc doc201

bluemira/equilibria/flux_surfaces.py

@@ -449,7 +449,7 @@ def __init__(self, coords: Coordinates):
 
         self.alpha = None
 
-    def clip(self, first_wall: Coordinates):
+    def clip(self, first_wall: Coordinates) -> None:
         """
         Clip the PartialOpenFluxSurface to a first wall.
 

bluemira/radiation_transport/advective_transport.py

@@ -8,21 +8,25 @@
 A simplified 2-D solver for calculating charged particle heat loads.
 """
 
-from copy import deepcopy
 from dataclasses import dataclass, fields
 
 import matplotlib.pyplot as plt
 import numpy as np
 from matplotlib.axes import Axes
+from numpy import typing as npt
 
 import bluemira.radiation_transport.flux_surfaces_maker as fsm
 from bluemira.base.constants import EPS
 from bluemira.base.look_and_feel import bluemira_warn
 from bluemira.display.plotter import Zorder, plot_coordinates
+from bluemira.equilibria.flux_surfaces import PartialOpenFluxSurface
 from bluemira.geometry.coordinates import Coordinates
 from bluemira.geometry.plane import BluemiraPlane
 from bluemira.radiation_transport.error import AdvectionTransportError
-from bluemira.radiation_transport.flux_surfaces_maker import _clip_flux_surfaces
+from bluemira.radiation_transport.flux_surfaces_maker import (
+    _clip_flux_surfaces,
+    _process_first_wall,
+)
 
 __all__ = ["ChargedParticleSolver"]
 
@@ -72,15 +76,17 @@ def __init__(
         self._o_point = o_points[0]
         z = self._o_point.z
         self._yz_plane = BluemiraPlane.from_3_points([0, 0, z], [1, 0, z], [1, 1, z])
+        self._process_first_wall = staticmethod(_process_first_wall)
 
     @property
-    def flux_surfaces(self):
+    def flux_surfaces(self) -> list[PartialOpenFluxSurface]:
         """
         All flux surfaces in the ChargedParticleSolver.
 
         Returns
         -------
-        flux_surfaces: List[PartialOpenFluxSurface]
+        flux_surfaces:
+            The list of partially open flux surfaces.
         """
         flux_surfaces = []
         for group in [
@@ -127,27 +133,30 @@ def _check_params(self):
             )
 
     @staticmethod
-    def _process_first_wall(first_wall):
-        """
-        Force working first wall geometry to be closed and counter-clockwise.
-        """
-        first_wall = deepcopy(first_wall)
-
-        if not first_wall.check_ccw(axis=[0, 1, 0]):
-            bluemira_warn(
-                "First wall should be oriented counter-clockwise. Reversing it."
-            )
-            first_wall.reverse()
-
-        if not first_wall.closed:
-            bluemira_warn("First wall should be a closed geometry. Closing it.")
-            first_wall.close()
-        return first_wall
-
-    @staticmethod
-    def _get_arrays(flux_surfaces):
+    def _get_arrays(
+        flux_surfaces,
+    ) -> tuple[
+        npt.NDArray[float],
+        npt.NDArray[float],
+        npt.NDArray[float],
+        npt.NDArray[float],
+        npt.NDArray[float],
+    ]:
         """
         Get arrays of flux surface values.
+
+        Returns
+        -------
+        x_mp: npt.NDArray[float]
+            the array of mid-plane intersection point x-coordinate for each flux surface
+        z_mp: npt.NDArray[float]
+            the array of mid-plane intersection point z-coordinate for each flux surface
+        x_fw: npt.NDArray[float]
+            the array of first-wall intersection point x-coordinate for each flux surface
+        z_fw: npt.NDArray[float]
+            the array of first-wall intersection point z-coordinate for each flux surface
+        alpha: npt.NDArray[float]
+            the array of alpha angle for each flux surface
         """
         x_mp = np.array([fs.x_start for fs in flux_surfaces])
         z_mp = np.array([fs.z_start for fs in flux_surfaces])
@@ -156,7 +165,7 @@ def _get_arrays(flux_surfaces):
         alpha = np.array([fs.alpha for fs in flux_surfaces])
         return x_mp, z_mp, x_fw, z_fw, alpha
 
-    def _make_flux_surfaces_ob(self):
+    def _make_flux_surfaces_ob(self) -> None:
         """
         Make the flux surfaces on the outboard.
         """
@@ -249,6 +258,16 @@ def analyse(self, first_wall: Coordinates):
     def _analyse_SN(self):
         """
         Calculation for the case of single nulls.
+
+        Returns
+        -------
+        x: np.array
+            The x coordinates of the flux surface intersections
+        z: np.array
+            The z coordinates of the flux surface intersections
+        heat_flux: np.array
+            The perpendicular heat fluxes at the intersection points [MW/m^2]
+
         """
         self._make_flux_surfaces_ob()
 
@@ -296,6 +315,15 @@ def _analyse_SN(self):
     def _analyse_DN(self):
         """
         Calculation for the case of double nulls.
+
+        Returns
+        -------
+        x: np.array
+            The x coordinates of the flux surface intersections
+        z: np.array
+            The z coordinates of the flux surface intersections
+        heat_flux: np.array
+            The perpendicular heat fluxes at the intersection points [MW/m^2]
         """
         self._make_flux_surfaces_ob()
         self._make_flux_surfaces_ib()
@@ -411,6 +439,11 @@ def _analyse_DN(self):
     def _q_par(self, x, dx, B, Bp, *, outboard=True):
         """
         Calculate the parallel power at the midplane.
+
+        Returns
+        -------
+        :
+            parallel power at the midplane
         """
         p_sol_near = self.params.P_sep_particle * self.params.f_p_sol_near
         p_sol_far = self.params.P_sep_particle * (1 - self.params.f_p_sol_near)
@@ -432,6 +465,11 @@ def _q_par(self, x, dx, B, Bp, *, outboard=True):
     def plot(self, ax: Axes = None, *, show=False) -> Axes:
         """
         Plot the ChargedParticleSolver results.
+
+        Returns
+        -------
+        :
+            The axes object on which the ChargedParticleSolver is plotted.
         """
         if ax is None:
             _, ax = plt.subplots()
@@ -472,6 +510,11 @@ def _make_params(config):
             Unsupported config type
         ValueError
             Unknown configuration parameters
+
+        Returns
+        -------
+        :
+            a ChargedParticleSolverParams object
         """
         if isinstance(config, dict):
             try: