From 9fd51989e588cda4548d2b61baa18c51c2e861a3 Mon Sep 17 00:00:00 2001
From: njzjz-bot <njzjz.bot@gmail.com>
Date: Mon, 24 Aug 2026 04:00:45 +0800
Subject: [PATCH] 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.1
Model: gpt-5.6-sol
Reasoning-Effort: xhigh
---
 docs/input.md                                 | 15 ++++++++++
 .../exploration/test_report_adaptive_lower.py | 29 +++++++++++++++++++
 2 files changed, 44 insertions(+)

diff --git a/docs/input.md b/docs/input.md
index 6fc03bd1..f667a986 100644
--- a/docs/input.md
+++ b/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
 
diff --git a/tests/exploration/test_report_adaptive_lower.py b/tests/exploration/test_report_adaptive_lower.py
index b5f123ca..f0d5d01b 100644
--- a/tests/exploration/test_report_adaptive_lower.py
+++ b/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(