docs: demonstrate adaptive trust scheduling

Document the adaptive-lower candidate cutoff and convergence rule and cover the requested sorting behavior with a focused regression.

Coding-Agent: Codex
Codex-Version: codex-cli 0.149.0
Model: gpt-5.6-sol
Reasoning-Effort: xhigh

Author: njzjz-bot

docs/input.md

@@ -131,6 +131,21 @@ The {dargs:argument}`"stages"<explore[lmp]/stages>` defines the exploration stag
 
 The {dargs:argument}`"n_sample"<task_group[lmp-md]/n_sample>` tells the number of confgiruations randomly sampled from the set picked by {dargs:argument}`"conf_idx"<task_group[lmp-md]/conf_idx>` from {dargs:argument}`"configurations"<explore[lmp]/configurations>` for each exploration task. All configurations has the equal possibility to be sampled. The default value of `"n_sample"` is `null`, in this case all picked configurations are sampled. In the example, we have 3 samples for stage 0 task group 0 and 2 thermodynamic states (NVT, T=50 and 100K), then the task group has 3x2=6 NVT DPMD tasks.
 
+To adapt the lower force trust level automatically, use the `adaptive-lower` convergence report:
+
+```json
+"convergence": {
+    "type": "adaptive-lower",
+    "level_f_hi": 0.5,
+    "numb_candi_f": 200,
+    "rate_candi_f": 0.01,
+    "n_checked_steps": 3,
+    "conv_tolerance": 0.005
+}
+```
+
+For each iteration, DPGEN2 sorts all force model deviations not exceeding `level_f_hi`. It marks the highest-deviation `max(numb_candi_f, rate_candi_f * nframes)` configurations as candidates and records the candidate cutoff as `level_f_lo`. The stage converges when the lower trust level changes by less than `conv_tolerance` across the last `n_checked_steps`. Virial thresholds can be adapted independently with the corresponding `_v` options.
+
 
 ### FP
 

tests/exploration/test_report_adaptive_lower.py

@@ -4,6 +4,9 @@
 from collections import (
     Counter,
 )
+from types import (
+    SimpleNamespace,
+)
 
 import mock
 import numpy as np
@@ -27,6 +30,32 @@
 
 
 class TestTrajsExplorationReport(unittest.TestCase):
+    def test_adaptive_cutoff_and_convergence(self):
+        model_devi = DeviManagerStd()
+        model_devi.add(
+            DeviManager.MAX_DEVI_F,
+            np.array([0.10, 0.20, 0.30, 0.40, 0.90]),
+        )
+        report = ExplorationReportAdaptiveLower(
+            level_f_hi=0.80,
+            numb_candi_f=2,
+            rate_candi_f=0.0,
+            n_checked_steps=3,
+            conv_tolerance=0.05,
+        )
+
+        report.record(model_devi)
+
+        self.assertEqual(report.candi, {(0, 2), (0, 3)})
+        self.assertEqual(report.accur, {(0, 0), (0, 1)})
+        self.assertEqual(report.failed, [(0, 4)])
+        self.assertAlmostEqual(report.level_f_lo, 0.30)
+        history = [
+            SimpleNamespace(level_f_lo=0.36),
+            SimpleNamespace(level_f_lo=0.34),
+        ]
+        self.assertTrue(report.converged(history))
+
     def test_fv(self):
         model_devi = DeviManagerStd()
         model_devi.add(
@@ -88,7 +117,7 @@ class MockedReport:
         self.assertFalse(ter.converged([mr, mr1, mr]))
         self.assertTrue(ter.converged([mr1, mr, mr]))
 
-        picked = ter.get_candidate_ids(2)
+        picked = ter.get_candidate_ids(2, clear=False)
         npicked = 0
         self.assertEqual(len(picked), 2)
         for ii in range(2):
@@ -198,32 +227,34 @@ def test_f_inv_pop(self):
         )
 
         def faked_choices(
-            candi,
-            weights=None,
-            k=0,
+            a,  # numb_candi
+            size=None,  # numb_select
+            replace=False,  # non-repeative sampling
+            p=None,  # normalized prob
         ):
             # hist: 2bins, 0.1-0.4 5candi, 0.4-0.7 7candi
             # only return those with mdf 0.1-0.4
-            self.assertEqual(len(weights), 12)
-            self.assertEqual(len(candi), 12)
-            ret = []
-            for ii in range(len(candi)):
+            candi = ter.candi_picked
+            self.assertEqual(a, 12)
+            self.assertEqual(len(p), 12)
+            ret_indices = []
+            for ii in range(a):
                 tidx, fidx = candi[ii]
                 this_mdf = md_f[tidx][fidx]
                 if this_mdf < 0.4:
-                    self.assertAlmostEqual(weights[ii], 1.0 / 5.0)
-                    ret.append(candi[ii])
+                    self.assertAlmostEqual(p[ii], 0.1)  # 1/5 / 2.0
+                    ret_indices.append(ii)
                 else:
-                    self.assertAlmostEqual(weights[ii], 1.0 / 7.0)
-            return ret
+                    self.assertAlmostEqual(p[ii], 1.0 / 14.0)  # 1/7 / 2.0
+            return ret_indices
 
         ter.record(model_devi)
-        with mock.patch("random.choices", faked_choices):
-            picked = ter.get_candidate_ids(11)
-        self.assertFalse(ter.converged([]))
         self.assertEqual(ter.candi, expected_cand)
         self.assertEqual(ter.accur, expected_accu)
         self.assertEqual(set(ter.failed), expected_fail)
+        with mock.patch("numpy.random.choice", faked_choices):
+            picked = ter.get_candidate_ids(11)
+        self.assertFalse(ter.converged([]))
         self.assertEqual(len(picked), 2)
         self.assertEqual(sorted(picked[0]), [1, 3])
         self.assertEqual(sorted(picked[1]), [1, 5, 7])