Merge pull request #659 from waltsims/coderabbitai/docstrings/6ec3d6d

📝 Add docstrings to `lossless`

Author: waltsims

kwave/kWaveSimulation.py

@@ -145,8 +145,13 @@ def __init__(
     @property
     def equation_of_state(self):
         """
+        Select the active equation-of-state label based on the medium's absorption and Stokes settings.
+        
         Returns:
-            Set equation of state variable
+            equation (str): One of:
+                - 'stokes' when the medium is absorbing and uses the Stokes model.
+                - 'absorbing' when the medium is absorbing and not using the Stokes model.
+                - 'lossless' when the medium is not absorbing.
         """
         if self.medium.absorbing:
             if self.medium.stokes:
@@ -159,9 +164,10 @@ def equation_of_state(self):
     @property
     def use_sensor(self):
         """
+        Indicates whether a sensor is defined for the simulation.
+        
         Returns:
-            False if no output of any kind is required
-
+            True if a sensor object is present, False otherwise.
         """
         return self.sensor is not None
 
@@ -1549,4 +1555,4 @@ def _is_cuboid_corners_mask(self, kgrid_dim: int) -> bool:
             return self.sensor.mask.shape[0] == 4  # [x1, y1, x2, y2]
         elif kgrid_dim == 3:
             return self.sensor.mask.shape[0] == 6  # [x1, y1, z1, x2, y2, z2]
-        return False  # Not valid for 1D or other dimensions
+        return False  # Not valid for 1D or other dimensions

kwave/kWaveSimulation_helper/create_absorption_variables.py

@@ -10,6 +10,26 @@
 
 def create_absorption_variables(kgrid: kWaveGrid, medium: kWaveMedium, equation_of_state):
     # define the lossy derivative operators and proportionality coefficients
+    """
+    Selects and returns absorption and dispersion operators and coefficients for the given medium based on the equation of state.
+    
+    Parameters:
+        kgrid (kWaveGrid): Grid object providing wavenumber array via `kgrid.k`.
+        medium (kWaveMedium): Medium properties used to compute absorption/dispersion coefficients.
+        equation_of_state (str): One of `"absorbing"`, `"stokes"`, or `"lossless"` determining which variables to produce.
+    
+    Returns:
+        tuple: (nabla1, nabla2, tau, eta)
+            - nabla1: First-order absorption operator or `None` when not applicable.
+            - nabla2: Dispersion operator or `None` when not applicable.
+            - tau: Absorbing coefficient or `None` when not applicable.
+            - eta: Dispersive coefficient or `None` when not applicable.
+    
+    Behavior:
+        - "absorbing": returns (nabla1, nabla2, tau, eta) computed for an absorbing medium.
+        - "stokes": returns (None, None, tau, None) where `tau` is the Stokes absorbing coefficient.
+        - "lossless": returns (None, None, None, None).
+    """
     if equation_of_state == "absorbing":
         return create_absorbing_medium_variables(kgrid.k, medium)
     elif equation_of_state == "stokes":
@@ -107,4 +127,4 @@ def apply_alpha_filter(medium, nabla1, nabla2):
     # shift the parameters back
     nabla1 = np.fft.ifftshift(nabla1)
     nabla2 = np.fft.ifftshift(nabla2)
-    return nabla1, nabla2
+    return nabla1, nabla2