📝 Add docstrings to lossless

Docstrings generation was requested by @djps.

* #658 (comment)

The following files were modified:

* `kwave/kWaveSimulation.py`
* `kwave/kWaveSimulation_helper/create_absorption_variables.py`

Author: coderabbitai[bot]

kwave/kWaveSimulation.py

@@ -145,23 +145,29 @@ 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:
                 return "stokes"
             else:
                 return "absorbing"
         else:
-            return "loseless"
+            return "lossless"
 
     @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,10 +10,32 @@
 
 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":
         return create_stokes_medium_variables(medium)
+    elif equation_of_state == "lossless":
+        return None, None, None, None
     else:
         raise NotImplementedError
 
@@ -105,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