From 67ce7767bea45f50c51f8cf146a7de7d6e205719 Mon Sep 17 00:00:00 2001
From: "coderabbitai[bot]"
 <136622811+coderabbitai[bot]@users.noreply.github.com>
Date: Sun, 25 Jan 2026 20:39:18 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Add=20docstrings=20to=20`lossles?=
 =?UTF-8?q?s`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Docstrings generation was requested by @djps.

* https://github.com/waltsims/k-wave-python/pull/658#issuecomment-3797202045

The following files were modified:

* `kwave/kWaveSimulation.py`
* `kwave/kWaveSimulation_helper/create_absorption_variables.py`
---
 kwave/kWaveSimulation.py                      | 16 +++++++++----
 .../create_absorption_variables.py            | 24 ++++++++++++++++++-
 2 files changed, 34 insertions(+), 6 deletions(-)

diff --git a/kwave/kWaveSimulation.py b/kwave/kWaveSimulation.py
index 8cd31e03e..9f08e6add 100644
--- a/kwave/kWaveSimulation.py
+++ b/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:
@@ -154,14 +159,15 @@ def equation_of_state(self):
             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
\ No newline at end of file
diff --git a/kwave/kWaveSimulation_helper/create_absorption_variables.py b/kwave/kWaveSimulation_helper/create_absorption_variables.py
index 56ae2d380..087aa09d5 100644
--- a/kwave/kWaveSimulation_helper/create_absorption_variables.py
+++ b/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
\ No newline at end of file