From 1ce3b9a39ecb7e06c5f7a1ee31f0fbfbe4df2405 Mon Sep 17 00:00:00 2001
From: Sylwester Arabas <sylwester.arabas@agh.edu.pl>
Date: Fri, 11 Sep 2026 13:56:09 +0200
Subject: [PATCH 1/2] Improve `moments` and `spectrum_moments` docstrings in
 particulator.py

Updated docstrings for clarity and corrected typos in the comments.
---
 PySDM/particulator.py | 26 ++++++++++++++++++++++++--
 1 file changed, 24 insertions(+), 2 deletions(-)

diff --git a/PySDM/particulator.py b/PySDM/particulator.py
index 6924cbc91..424c62828 100644
--- a/PySDM/particulator.py
+++ b/PySDM/particulator.py
@@ -333,10 +333,26 @@ def moments(
         weighting_rank=0,
         skip_division_by_m0=False,
     ):
-        """
-        Writes to `moment_0` and `moment` the zero-th and the k-th statistical moments
+        r"""
+        Writes to `moment_0` and `moments` the zero-th and the k-th statistical moments
         of particle attributes computed filtering by value of the attribute `attr_name`
         to fall within `attr_range`. The moment ranks are defined by `specs`.
+        By default, the moments are multiplicity-weighted, and any other weighting
+        (e.g., mass-weighting) can be specified using `weighting_attribute` and
+        `weighting_rank` parameters. All calculations are done per-cell, hence the
+        dimensionality of `moment_0` and `moments` matches the environment grid.
+
+        Mathematically, the computations correspond to:
+        $$
+        M_k = \frac{
+            \left.\sum_i\right|_{\text{attr_range[0]} < a_i < \text{attr_range[1]} a_i^k m_i w_i^l
+        }{
+            \left.\sum_i\right|_{\text{attr_range[0]} < a_i < \text{attr_range[1]} m_i w_i^l
+        }
+        $$
+        where $k$ is the rank (e.g., 1 for an ordinary mean), $a$ is the attribute (e.g., water mass),
+        $m$ is the multiplicity, $w$ is the weighting attribute (e.g., mass) and $l$ is the weighting 
+        rank (by default 0 translating to plain multiplicity weighting).
 
         Parameters:
             specs: e.g., `specs={'volume': (1,2,3), 'kappa': (1)}` computes three moments
@@ -389,6 +405,12 @@ def spectrum_moments(
         weighting_rank=0,
         skip_division_by_m0=False,
     ):
+        """
+        Performns calculation of statistical moments as in `moments()`, but with the attribute-value
+        filtering applied to a series of ranges (bins), instead of just a single range. Typical usage
+        is to create a binned spectrum representation in one call, rather than executing `moments()`
+        separately for each spectrum bin.
+        """
         attr_data = self.attributes[attr]
         self.backend.spectrum_moments(
             moment_0=moment_0,

From 72917a31d688f1f08b8f83799f9901b709135295 Mon Sep 17 00:00:00 2001
From: Sylwester Arabas <sylwester.arabas@agh.edu.pl>
Date: Fri, 11 Sep 2026 16:26:37 +0200
Subject: [PATCH 2/2] clarify the difference between filering attribute and the
 attribute for which moments are computed

---
 PySDM/particulator.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/PySDM/particulator.py b/PySDM/particulator.py
index 424c62828..a1d3ce162 100644
--- a/PySDM/particulator.py
+++ b/PySDM/particulator.py
@@ -345,14 +345,15 @@ def moments(
         Mathematically, the computations correspond to:
         $$
         M_k = \frac{
-            \left.\sum_i\right|_{\text{attr_range[0]} < a_i < \text{attr_range[1]} a_i^k m_i w_i^l
+            \left.\sum_i\right|_{\text{attr_range[0]} < x_i < \text{attr_range[1]} a_i^k m_i w_i^l
         }{
-            \left.\sum_i\right|_{\text{attr_range[0]} < a_i < \text{attr_range[1]} m_i w_i^l
+            \left.\sum_i\right|_{\text{attr_range[0]} < x_i < \text{attr_range[1]} m_i w_i^l
         }
         $$
-        where $k$ is the rank (e.g., 1 for an ordinary mean), $a$ is the attribute (e.g., water mass),
-        $m$ is the multiplicity, $w$ is the weighting attribute (e.g., mass) and $l$ is the weighting 
-        rank (by default 0 translating to plain multiplicity weighting).
+        where $k$ is the rank (e.g., 1 for an ordinary mean), $x$ is the attribute used for filtering
+        (e.g., radius), $a$ is the attribute of which the moment is calculated (specified via the `specs`
+        parameter), $m$ is the multiplicity, $w$ is the weighting attribute (e.g., mass) and $l$ is the 
+        weighting rank (by default 0 translating to plain multiplicity weighting).
 
         Parameters:
             specs: e.g., `specs={'volume': (1,2,3), 'kappa': (1)}` computes three moments