From e3af90a1219f5baeaa189ee14d4f89dca305939b Mon Sep 17 00:00:00 2001 From: Rudolf Weeber Date: Mon, 15 Jun 2026 11:46:27 +0200 Subject: [PATCH] electrostatics: fix ELC delta_mid_bot docstring typo (bug-sweep #54) The ELC parameter-list docstring documented 'delta_mid_bottom', but the accepted parameter name (used by default_params(), the script-interface AutoParameters/constructor, the docstring's own prose, the Sphinx docs, the tutorials, and every testsuite usage) is 'delta_mid_bot'. A user following the documented name hit a RuntimeError "Parameter 'delta_mid_bottom' is not a valid parameter". Fix the docstring to the established public name 'delta_mid_bot' (the checkpoint-serialized name). Add a docstring-consistency test in coulomb_interface.py that parses the ELC "Parameters" block and asserts every documented field is an accepted parameter (a key of default_params() or a member of required_keys()). Co-Authored-By: Claude Opus 4.8 --- src/python/espressomd/electrostatics.py | 2 +- testsuite/python/coulomb_interface.py | 25 +++++++++++++++++++++++++ 2 files changed, 26 insertions(+), 1 deletion(-) diff --git a/src/python/espressomd/electrostatics.py b/src/python/espressomd/electrostatics.py index 70fcac2876..7d63ee53da 100644 --- a/src/python/espressomd/electrostatics.py +++ b/src/python/espressomd/electrostatics.py @@ -266,7 +266,7 @@ class ELC(ElectrostaticInteraction): delta_mid_top : :obj:`float`, optional Dielectric contrast :math:`\\Delta_t` between the upper boundary and the simulation box. Value between -1 and +1 (inclusive). - delta_mid_bottom : :obj:`float`, optional + delta_mid_bot : :obj:`float`, optional Dielectric contrast :math:`\\Delta_b` between the lower boundary and the simulation box. Value between -1 and +1 (inclusive). const_pot : :obj:`bool`, optional diff --git a/testsuite/python/coulomb_interface.py b/testsuite/python/coulomb_interface.py index dc2c0bc6ff..07c2f927dd 100644 --- a/testsuite/python/coulomb_interface.py +++ b/testsuite/python/coulomb_interface.py @@ -17,6 +17,7 @@ # along with this program. If not, see . # +import re import unittest as ut import unittest_decorators as utx import tests_common @@ -168,6 +169,30 @@ def test_mmm1d_cpu_tuning(self): self.assertTrue(actor.is_tuned) self.assertAlmostEqual(actor.far_switch_radius**2, 0.8 * h_z**2) + @utx.skipIfMissingFeatures(["P3M"]) + def test_elc_docstring_parameter_names(self): + # every parameter documented in the ELC docstring must be an accepted + # parameter, i.e. a key of default_params() or a member of + # required_keys(); otherwise a user following the documentation hits + # "Parameter '' is not a valid parameter" (bug-sweep #54). + ELC = espressomd.electrostatics.ELC + # default_params() and required_keys() do not touch system state, so + # they can be queried on a bare instance without running __init__. + instance = ELC.__new__(ELC) + accepted = set(instance.default_params().keys()) | set( + instance.required_keys()) + # extract the "Parameters" block from the docstring + doc = ELC.__doc__ + params_block = doc.split("Parameters\n", 1)[1] + # collect each documented field name (lines like "name : :obj:`...`") + documented = re.findall(r"^\s*(\w+)\s*:\s*:obj:", params_block, re.M) + self.assertIn("delta_mid_bot", documented + list(accepted)) + for name in documented: + self.assertIn( + name, accepted, + f"ELC docstring documents '{name}' but it is not an accepted " + f"parameter (accepted: {sorted(accepted)})") + @utx.skipIfMissingFeatures(["P3M"]) def test_elc_p3m_exceptions(self): P3M = espressomd.electrostatics.P3M