update docs

Author: yuxuanzhuang

batter/orchestrate/run.py

@@ -265,7 +265,7 @@ def _require_rbfe_network_has_pairs(config_dir: Path) -> None:
     if not payload.get("pairs"):
         raise RuntimeError(
             "Prepared RBFE network contains no ligand pairs after removing identical "
-            "ligands and full-atom-map edges."
+            "duplicate ligands."
         )
 
 
@@ -530,8 +530,8 @@ def _build_rbfe_network_plan(
     Resolve and persist the RBFE ligand network before equilibration.
 
     This phase deduplicates identical ligands, resolves explicit or generated
-    transformation pairs, prepares per-edge atom-mapping artifacts, filters
-    full-coverage mappings, and writes ``rbfe_network.json`` plus the
+    transformation pairs, prepares per-edge atom-mapping artifacts, records
+    mapping coverage metadata, and writes ``rbfe_network.json`` plus the
     interactive ``rbfe_network.html`` review page under ``config_dir``.
     """
     from batter.rbfe import (

docs/cli.rst

@@ -88,6 +88,10 @@ Key options:
    Maximum total submissions for the script (including the first run; default: 4).
 ``--current-submission-time``
    Internal counter for auto-resubmit; increments on each resubmission (default: 0).
+``--force-job-attempt N``
+   Use ``N`` as the job-attempt value for every queued component instead of
+   reading each component's ``job_attempt.txt``. This is useful when rerunning a
+   batch with the reduced-timestep retry settings.
 
 Inspect Free-Energy Results
 ===========================
@@ -130,13 +134,18 @@ way as ``batter run --slurm-submit``. Use ``--partition`` or
 To generate a per-ligand (or per-RBFE-pair) SLURM array script without submitting
 it immediately, use ``--job-array``::
 
-   batter fe analyze work/adrb2 run-20240101 --job-array --workers 2
+   batter fe analyze work/adrb2 run-20240101 --job-array --array-limit 128 --workers 2
 
 This writes ``*_array.sbatch`` and a matching ``*.tasks.tsv`` task file in the
 current directory. Submit the generated script with ``sbatch`` after inspection.
 Use ``--array-limit`` to control concurrent array tasks, ``--array-output`` to
 choose the script path, and ``--partition`` to set the generated script's
-partition.
+partition. For RBFE and ``rbfe_septop`` runs, each array task analyzes one
+transformation pair; ``--ligand`` may be a pair id such as ``LIG1~LIG2`` or an
+endpoint ligand name to include all pairs touching that ligand. If you omit
+``run_id``, BATTER writes array tasks for every execution under
+``work/adrb2/executions``. ``--job-array`` cannot be combined with
+``--slurm-submit`` because it generates the array script for separate submission.
 
 For RBFE runs, ``batter fe analyze`` also writes a per-run Cinnabar bundle under
 ``work/adrb2/results/cinnabar/<run_id>/`` by default. When the work directory
@@ -180,6 +189,7 @@ is omitted, BATTER writes to ``./cinnabar``. Common files include:
 
 * ``edge_summary.csv`` – combined edge-level DDG estimates and uncertainties
 * ``raw_signed.csv`` – signed per-measurement table after BATTER canonicalizes edge direction
+* ``x_convergence_filter.csv`` – edge filter decisions when x-component convergence filtering is enabled
 * ``cinnabar_relative.csv`` – relative measurements exported from the FEMap
 * ``cinnabar_absolute.csv`` – MLE-derived absolute values when the network is connected
 * ``cinnabar_absolute_sorted.png`` – BATTER-rendered absolute ΔG ranking plot, sorted by energy
@@ -208,6 +218,15 @@ each run before combining runs. Switch to ``--pool-all-measurements`` if you wan
 weight every stored edge measurement directly. ``--uncertainty-mode`` controls the
 repeat-combination rule (``ivw``, ``sample``, or ``max``).
 
+By default, RBFE Cinnabar export skips edge measurements whose x-component
+forward/backward convergence has not reached 1 kcal/mol by 80% of the production
+data. It can restore edges needed for network connectivity with the fallback
+0.5/2 kcal/mol threshold. Tune these with ``--x-convergence-filter`` and
+``--x-convergence-fallback-filter``, or disable them with
+``--no-x-convergence-filter`` / ``--no-x-convergence-fallback-filter``. When the
+main filter is active, BATTER also writes an ``unskipped/`` bundle beside the
+filtered output.
+
 By default BATTER also merges opposite-direction rows such as ``LIGA~LIGB`` and
 ``LIGB~LIGA`` into one canonical edge before constructing the FEMap. Use
 ``--split-directions`` if you want those two stored transformations to remain

docs/cookbook/configuration.rst

@@ -19,21 +19,23 @@ The run YAML file is divided into three sections grouped inside
     notification preferences, and artifact destination. ``run.output_folder`` is
     required and becomes the base path for ``<run.output_folder>/executions/<run_id>/``.
     ``run.system_type`` optionally overrides the builder selection inferred from the
-    protocol (``MABFE`` for ABFE/MD, ``MASFE`` for ASFE). This section is validated
-    by :class:`batter.config.run.RunSection`. Set ``run.clean_failures: true`` to
-    remove ``FAILED`` sentinels, ``job_attempt.txt`` retry counters, and progress
-    caches before rerunning an existing execution.
+    protocol (``MABFE`` for ABFE/RBFE/MD-family runs, ``MASFE`` for ASFE). This
+    section is validated by :class:`batter.config.run.RunSection`. Set
+    ``run.clean_failures: true`` to remove ``FAILED`` sentinels,
+    ``job_attempt.txt`` retry counters, and progress caches before rerunning an
+    existing execution. Set ``run.store_debug_files: true`` to preserve
+    intermediate scratch files that are otherwise pruned after successful stages.
 ``create``
     Inputs required for system staging (protein/topology paths, ligands, force fields,
     optional anchors/restraints). The structure maps directly to
     :class:`batter.config.run.CreateArgs`.
 ``fe_sim``
-    Overrides and controls for free-energy simulation stages. For ABFE/ASFE runs
-    these map to :class:`batter.config.run.FESimArgs`. MD-only runs automatically
-    coerce this section into :class:`batter.config.run.MDSimArgs`, so fields like
-    ``lambdas`` or SDR restraints are no longer required. Equilibration controls
-    are expressed via ``eq_steps`` which now represents the **total** equilibration
-    steps. The value is written into ``mdin-template`` as ``! total_steps=<total>``,
+    Overrides and controls for simulation stages. FE protocols map this section to
+    :class:`batter.config.run.FESimArgs`. MD-only runs automatically coerce it into
+    :class:`batter.config.run.MDSimArgs`, so fields like ``lambdas`` or SDR
+    restraints are no longer required. Equilibration controls are expressed via
+    ``eq_steps`` which now represents the **total** equilibration steps. The value
+    is written into ``mdin-template`` as ``! total_steps=<total>``,
     letting runtime scripts determine the target length without regenerating inputs.
     Legacy production extend knobs (``num_fe_extends``) are rejected; set
     ``n_steps`` to total steps instead. ``analysis_range`` is likewise
@@ -52,9 +54,10 @@ Per-component steps and lambdas
 
 Component steps are supplied via ``fe_sim.n_steps`` as dicts keyed by the
 single-letter component (e.g. ``z: 100000``). Keys like ``y_n_steps`` are also
-accepted and folded into this map automatically. Each protocol enforces the
-required components: ABFE fills ``z`` defaults if omitted, and ASFE fills
-``y``/``m`` defaults.
+accepted and folded into this map automatically. Each FE protocol enforces the
+components it needs: ABFE requires ``z``, standard and SEPTOP RBFE require ``x``,
+and ASFE requires ``y``/``m``. Set the corresponding ``<comp>_n_steps`` or
+``fe_sim.n_steps`` entry explicitly in production YAMLs.
 
 Lambda schedules can be customized per component using ``fe_sim.component_lambdas``
 (or ``<comp>_lambdas`` keys). When a component is missing from that map, it
@@ -64,12 +67,23 @@ or comma/space separated strings; validation ensures ascending order.
 RBFE mapping options
 --------------------
 
-For ``protocol: rbfe``, the ``rbfe`` block controls network planning and atom mapping.
+For ``protocol: rbfe`` or ``protocol: rbfe_septop``, the ``rbfe`` block controls
+network planning and atom mapping/scoring.
 
 * ``rbfe.mapping`` – mapping strategy (for example ``default`` or ``konnektor``).
 * ``rbfe.mapping_file`` – explicit pair list file; takes precedence over ``mapping``.
 * ``rbfe.atom_mapping_file`` – optional JSON/YAML atom mapping overrides for
   selected pairs; uncovered pairs use ``rbfe.atom_mapper``.
+* ``rbfe.network_scorer`` – edge scorer for Konnektor planning. ``auto`` uses the
+  LoMap scorer for standard RBFE and pocket-shape scoring for ``rbfe_septop``.
+  Other accepted values include ``lomap``, ``shape_difference`` and
+  ``pocket_shape``.
+* ``rbfe.direction_policy`` – ``larger_volume`` (default) or ``preserve``. Generated
+  networks are oriented with the larger grid-volume ligand as reference unless a
+  mapping file explicitly fixes the direction.
+* ``rbfe.minimal_mapping_atom`` – minimum mapped-atom count required for standard
+  RBFE edges. This check is not used to reject ``rbfe_septop`` edges because SEPTOP
+  uses full-ligand softcore setup.
 * ``rbfe.add_atom_mapping_edges`` – default ``false``; append valid
   atom-mapping override pairs when neither direction was selected by network
   planning.
@@ -101,18 +115,22 @@ See :doc:`rbfe` for RBFE-specific examples.
 Anchor selection
 ----------------
 
-``create.anchor_atoms`` is optional. If it is omitted, BATTER resolves the
-anchor triplet during ``system_prep`` and records the selections in
-``executions/<run_id>/all-ligands/manifest.json``:
+``create.anchor_atoms`` is optional. If it is omitted, BATTER resolves the anchor
+triplet during ``system_prep`` and stores the resolved global selections in
+``executions/<run_id>/all-ligands/manifest.json``. Prepared-system anchor masks
+used by later equilibration/FE setup are also written per ligand to
+``equil/anchors.json``.
 
 * For runs with real ligands, the first available real ligand pose drives a
   ligand-guided receptor-anchor heuristic.
 * For apo-only MD, BATTER switches to a protein-only heuristic so dummy ligand
   coordinates do not determine the anchor geometry.
 
-Use explicit ``create.anchor_atoms`` only when you need to pin a known
-binding-site geometry or override the heuristic. The value must contain exactly
-three MDAnalysis selection strings, ordered as P1, P2, and P3.
+If you know the receptor interaction that should define the Boresch reference,
+provide one selection. BATTER treats that atom as P1 and chooses P2/P3
+automatically. Prefer the binding-site Cα of a residue associated with a
+conserved ligand interaction, such as the residue forming a salt bridge. Provide
+three selections only when you need fully manual P1/P2/P3 geometry.
 
 Component-Specific Inputs
 -------------------------
@@ -153,8 +171,9 @@ feed into the low-level ops documented in :doc:`../developer_guide/internal_buil
      - JSON specification for conformational restraints.
    * - ``anchor_atoms``
      - ``system_prep`` / restraint ops
-     - Optional P1/P2/P3 receptor-anchor override. Empty means BATTER selects
-       anchors heuristically and stores the resolved selections in the manifest.
+     - Optional receptor-anchor override. Empty means BATTER selects anchors
+       heuristically; one selection pins P1 and auto-selects P2/P3; three
+       selections provide explicit P1/P2/P3 geometry.
    * - ``lipid_mol``
      - Build/ops helpers
      - Identifies membrane residues when trimming waters.

docs/cookbook/rbfe.rst

@@ -22,7 +22,7 @@ Minimal RBFE configuration
        LIG1: /path/to/lig1.sdf
        LIG2: /path/to/lig2.sdf
        LIG3: /path/to/lig3.sdf
-     # Optional: provide explicit receptor anchors to override auto-selection.
+     # Optional: omit anchors, provide one P1 anchor, or provide explicit P1/P2/P3.
      # anchor_atoms:
      #   - "name CA and resid 113"
      #   - "name CA and resid 82"
@@ -42,8 +42,8 @@ If you omit ``rbfe.mapping`` (and do not provide files), BATTER uses
 Anchor selection
 ----------------
 
-``create.anchor_atoms`` is optional. When it is omitted, BATTER chooses the
-three receptor anchors heuristically during system preparation:
+``create.anchor_atoms`` is optional. When it is omitted, BATTER chooses the three
+receptor anchors heuristically during system preparation:
 
 * For ABFE/RBFE and MD runs with at least one real ligand, BATTER uses the first
   real ligand pose as the binding-site reference. It prefers stable receptor
@@ -54,22 +54,44 @@ three receptor anchors heuristically during system preparation:
   stable, non-degenerate receptor-anchor triplet without relying on dummy
   ligand coordinates.
 
-Provide ``create.anchor_atoms`` manually when you want fixed anchors for a
-known binding site, when the first ligand pose is not representative, or when
-the heuristic reports that no suitable triplet was found. Resolved anchors are
-stored in ``executions/<run_id>/all-ligands/manifest.json`` under
-``anchors`` and ``anchor_atom_selections``.
+If you know the receptor interaction that should define the Boresch reference,
+provide one selection. BATTER treats that atom as P1 and chooses P2/P3
+automatically; prefer the binding-site Cα of a residue associated with a
+conserved ligand interaction, such as the residue forming a salt bridge. Provide
+three selections only when you need fully manual P1/P2/P3 geometry. Resolved
+global anchors are stored in ``executions/<run_id>/all-ligands/manifest.json``
+under ``anchors`` and ``anchor_atom_selections``. Prepared-system anchor masks
+used later by equilibration and FE setup are written to each ligand's
+``equil/anchors.json``.
+
+Standard RBFE and rbfe_septop
+-----------------------------
+
+Use ``protocol: rbfe`` when ligand pairs have a chemically meaningful common
+core. BATTER prepares reusable atom-mapping artifacts and the transformation
+setup uses those mappings for the standard RBFE softcore construction.
+
+Use ``protocol: rbfe_septop`` for scaffold hops, protonation-state comparisons,
+or pairs where a common-core mapping would be misleading. The same RBFE network
+planner is used, but SEPTOP FE setup treats each full ligand as softcore and
+uses opposite lambda-dependent Boresch restraints for the two bound ligands.
+Mapping artifacts are still generated for network scoring and review, and
+``rbfe.network_scorer: auto`` switches to receptor-frame pocket-shape scoring by
+default.
 
 Default mapping algorithm
 -------------------------
 
-The default mapping is a star network:
+The default mapping starts as a star network:
 
 * Ligands are taken in input order.
-* The first ligand is used as reference.
+* The first ligand is used as the initial reference.
 * Pairs are built as ``(lig1, lig2)``, ``(lig1, lig3)``, ...
 
-This corresponds to ``RBFENetwork.default_mapping``.
+This corresponds to ``RBFENetwork.default_mapping``. Unless you set
+``rbfe.direction_policy: preserve`` or provide ``rbfe.mapping_file``, BATTER then
+orients generated edges with ``rbfe.direction_policy``; the default
+``larger_volume`` policy uses the larger grid-volume ligand as the reference.
 
 Mapping options and precedence
 ------------------------------
@@ -79,6 +101,9 @@ RBFE mapping is controlled by ``rbfe`` in ``run.yaml``:
 * ``rbfe.mapping_file``
 * ``rbfe.mapping`` (default ``default``)
 * ``rbfe.atom_mapping_file`` for optional per-pair atom mapping overrides
+* ``rbfe.network_scorer`` (default ``auto``)
+* ``rbfe.direction_policy`` (default ``larger_volume``)
+* ``rbfe.minimal_mapping_atom`` (default ``3``)
 * ``rbfe.add_atom_mapping_edges`` (default ``false``)
 
 If both are provided, BATTER uses ``mapping_file``.
@@ -90,13 +115,19 @@ Supported ``rbfe.mapping`` values
 * ``konnektor``
 
 When using ``konnektor``, you can optionally set ``rbfe.konnektor_layout``.
+``rbfe.network_scorer`` controls how Konnektor scores candidate edges:
+``auto`` resolves to LoMap scoring for standard RBFE and pocket-shape scoring
+for ``rbfe_septop``; explicit values include ``lomap``, ``shape_difference`` and
+``pocket_shape``.
 
 .. code-block:: yaml
 
    rbfe:
      mapping: konnektor
      atom_mapper: kartograf
      konnektor_layout: star
+     network_scorer: auto
+     direction_policy: larger_volume
      both_directions: false
 
 .. _rbfe_atom_mapper_options:
@@ -290,10 +321,10 @@ The HTML view is the primary network-review artifact:
   score, mapped-atom ratio, volume ratio, shape mismatch, and shape overlap.
   Missing optional metrics are simply absent from the selector.
 
-During planning, BATTER omits duplicate ligands with identical molecular identity
-and removes edges whose prepared atom mapping has full atom or heavy-atom
-coverage. The skipped
-ligands and edges are recorded in ``rbfe_network.json`` as skip metadata.
+During planning, BATTER omits duplicate ligands with identical molecular
+identity. Full atom or full heavy-atom mappings are retained as normal edges and
+recorded as coverage metadata in the per-edge mapping status and network JSON.
+Skipped identical ligands are recorded in ``rbfe_network.json`` as skip metadata.
 
 Transformation systems are created under:
 

docs/cookbook/results_folder.rst

@@ -151,30 +151,40 @@ RBFE-Specific Additions
 
 RBFE records use the same top-level pattern, but the payload is slightly different::
 
+   results/<run_id>/
+   ├── rbfe_network.json
+   ├── rbfe_network.png
+   ├── rbfe_network.html
+   └── <ligand_ref~ligand_alt>/
+       ├── record.json
+       ├── Results/
+       │   ├── Results.dat
+       │   ├── mapping.json
+       │   ├── mapping.pkl
+       │   └── mapping.png
+       ├── Equil_ref/
+       └── Equil_alt/
+
+``results/<run_id>/rbfe_network.*``
+   Run-level copies of the resolved RBFE network artifacts from
+   ``executions/<run_id>/artifacts/config/``. The HTML dashboard is generated
+   during ``prepare_rbfe`` and includes pan/zoom controls, clickable ligand and
+   edge notes, collapsed reverse-direction edges, prepared atom-mapping or
+   pocket-shape images when drawing succeeds, and selectable edge coloring by
+   graph redundancy or available mapping metrics.
+
+Per-pair RBFE result records live under::
+
    results/<run_id>/<ligand_ref~ligand_alt>/
    ├── record.json
    ├── Results/
    │   ├── Results.dat
-   │   ├── rbfe_network.png
-   │   ├── rbfe_network.html
    │   ├── mapping.json
    │   ├── mapping.pkl
    │   └── mapping.png
    ├── Equil_ref/
    └── Equil_alt/
 
-``Results/rbfe_network.png``
-   Copy of the resolved RBFE network plot from
-   ``executions/<run_id>/artifacts/config/rbfe_network.png``.
-
-``Results/rbfe_network.html``
-   Copy of the planned RBFE network dashboard from
-   ``executions/<run_id>/artifacts/config/rbfe_network.html``. The dashboard is
-   generated during ``prepare_rbfe`` and includes pan/zoom controls, clickable
-   ligand and edge notes, collapsed reverse-direction edges, prepared
-   atom-mapping images when drawing succeeds, and selectable edge coloring by
-   graph redundancy or available mapping metrics.
-
 ``Results/mapping.*``
    Atom-mapping artifacts copied into the transformation setup directory from
    ``executions/<run_id>/artifacts/config/rbfe_mappings/<ligand_ref~ligand_alt>/``.

docs/developer_guide.rst

@@ -211,7 +211,9 @@ Orchestration
 :func:`~batter.orchestrate.run.run_from_yaml` wires every layer together:
 
 1. Load the run YAML and apply optional overrides.
-2. Instantiate a system builder inferred from the selected protocol (``abfe``/``rbfe``/``md`` → ``MABFE``, ``asfe`` → ``MASFE``; overrides via ``run.system_type`` remain for backward compatibility).
+2. Instantiate a system builder inferred from the selected protocol
+   (MABFE-family protocols use ``MABFE``; ``asfe`` uses ``MASFE``; overrides via
+   ``run.system_type`` remain for backward compatibility).
 3. Resolve staged ligands (supporting resume) and regenerate the system if required.
 4. Construct the ABFE/ASFE pipeline using :func:`select_pipeline
    <batter.orchestrate.pipeline_utils.select_pipeline>`.