RBFE Guide#

This page documents the current RBFE workflow in BATTER and the network-mapping options in the rbfe section of run.yaml.

Minimal RBFE configuration#

protocol: rbfe

run:
  output_folder: /path/to/output
  run_id: auto

create:
  system_name: my_system
  protein_input: /path/to/protein.pdb
  anchor_atoms:
    - "name CA and resid 113"
    - "name CA and resid 82"
    - "name CA and resid 316"
  ligand_paths:
    LIG1: /path/to/lig1.sdf
    LIG2: /path/to/lig2.sdf
    LIG3: /path/to/lig3.sdf

rbfe:
  mapping: default
  atom_mapper: kartograf

fe_sim:
  lambdas: [0.0, 0.5, 1.0]
  x_n_steps: 300000

If you omit rbfe.mapping (and do not provide files), BATTER uses default.

Default mapping algorithm#

The default mapping is a star network:

  • Ligands are taken in input order.

  • The first ligand is used as reference.

  • Pairs are built as (lig1, lig2), (lig1, lig3), …

This corresponds to RBFENetwork.default_mapping.

Mapping options and precedence#

RBFE mapping is controlled by rbfe in run.yaml:

  • rbfe.mapping_file

  • rbfe.mapping (default default)

If both are provided, BATTER uses mapping_file.

Supported rbfe.mapping values#

  • default (also star / first aliases)

  • konnektor

When using konnektor, you can optionally set rbfe.konnektor_layout.

rbfe:
  mapping: konnektor
  atom_mapper: kartograf
  konnektor_layout: star
  both_directions: false

Atom mapper backends#

RBFE atom mapping backend is controlled by rbfe.atom_mapper:

  • kartograf (default) – current BATTER Kartograf-based mapping behavior:

    # network planning mapper (rbfe.py)
KartografAtomMapper(
    atom_max_distance=0.95,
    map_hydrogens_on_hydrogens_only=True,
    atom_map_hydrogens=False,
    map_exact_ring_matches_only=True,
    allow_partial_fused_rings=True,
    allow_bond_breaks=False,
    additional_mapping_filter_functions=[filter_element_changes],
)

    During RBFE transformation setup (_internal/ops/simprep.py), BATTER uses the same Kartograf settings except atom_map_hydrogens=True unless rbfe.kartograf overrides it.

  • lomap – uses:

    LomapAtomMapper(
    time=20,
    threed=True,
    max3d=1.5,
    element_change=False,
    shift=True,
)

Example:

rbfe:
  mapping: konnektor
  atom_mapper: lomap
  lomap:
    time: 7
    max3d: 2.0
    shift: false
  kartograf:
    atom_max_distance: 1.1
    allow_bond_breaks: true
    filter_element_changes: false

Only the selected backend’s options are used for a run. The available Kartograf keys are atom_max_distance, map_exact_ring_matches_only, allow_partial_fused_rings, allow_bond_breaks, filter_element_changes, and filter_mismatched_attached_h_count. BATTER does not expose Kartograf’s hydrogen-mapping toggles in YAML because the AMBER setup path relies on the previous fixed behavior: network planning uses atom_map_hydrogens=False, RBFE transformation setup uses atom_map_hydrogens=True, and both use map_hydrogens_on_hydrogens_only=True. The available LoMap keys are time, threed, max3d, element_change, and shift.

Bidirectional RBFE edges#

Set rbfe.both_directions: true to run both directions for each mapped edge. For example, a mapped pair LIG1~LIG2 will generate both:

  • LIG1~LIG2

  • LIG2~LIG1

mapping_file formats#

rbfe.mapping_file supports:

  • JSON/YAML list of pairs, e.g. [["LIG1","LIG2"], ["LIG2","LIG3"]]

  • JSON/YAML dict with pairs or edges keys

  • JSON/YAML adjacency dict, e.g. {"LIG1": ["LIG2","LIG3"]}

  • text file with one pair per line (A~B, A,B, or A B)

Konnektor layouts: how to list all available options#

BATTER resolves Konnektor layouts dynamically from konnektor.network_planners by collecting class names ending with NetworkGenerator.

To list available layout names in your environment:

python - <<'PY'
from konnektor import network_planners as np
names = []
for name in dir(np):
    if name.endswith("NetworkGenerator"):
        names.append(name)
        names.append(name[:-len("NetworkGenerator")].lower())
print(sorted(set(names)))
PY

Note: Konnektor explicit layouts require explicit edges; in BATTER use rbfe.mapping_file for that case.

Where RBFE mapping is stored#

BATTER writes the resolved network to:

  • executions/<run_id>/artifacts/config/rbfe_network.json

Transformation systems are created under:

  • executions/<run_id>/simulations/transformations/<LIG1~LIG2>/

For each transformation pair, BATTER stores atom-mapping artifacts in:

  • executions/<run_id>/simulations/transformations/<LIG1~LIG2>/fe/x/x-1/mapping.json

  • executions/<run_id>/simulations/transformations/<LIG1~LIG2>/fe/x/x-1/mapping.pkl

  • executions/<run_id>/simulations/transformations/<LIG1~LIG2>/fe/x/x-1/mapping.png

These generic mapping.* filenames are used for both kartograf and lomap atom-mapper backends.

Pipeline notes#

In RBFE, BATTER runs ligand-level prep/equilibration first, then builds transformation pairs from the resolved network and runs component x FE on those pairs.