### Setup REST2 with femto.md.rest.apply_rest

Source: https://context7.com/psivant/femto/llms.txt

Prepares a system for REST2 by injecting global context parameters. Must be applied after any FEP modifications.

```python
import femto.md.rest
import femto.md.config
import femto.md.constants

rest_config = femto.md.config.REST(
    scale_torsions=True,
    scale_nonbonded=True,
    scale_angles=False,
    scale_bonds=False,
)

solute_idxs = topology.select(
    f"resn {femto.md.constants.LIGAND_1_RESIDUE_NAME}"
)
# Modifies system in-place
femto.md.rest.apply_rest(system, solute_idxs, rest_config)

# REST2 context parameter names for manual control
print(femto.md.rest.REST_CTX_PARAM)       # "bm_b0"
print(femto.md.rest.REST_CTX_PARAM_SQRT)  # "bm_b0_sqrt"
```

--------------------------------

### Setup SepTop Solution System

Source: https://context7.com/psivant/femto/llms.txt

Builds the solution-phase system with ligands at a fixed separation and solvation. Uses distance restraints between specified reference atoms on each ligand.

```python
import femto.fe.septop

solution_topology, solution_system = femto.fe.septop.setup_solution(
    config.solution.setup,
    ligand_1,
    ligand_2,
    ligand_1_ref_query,
    ligand_2_ref_query,
)

```

--------------------------------

### Setup OpenMM System

Source: https://github.com/psivant/femto/blob/main/docs/guide-atm.md

Creates the complete OpenMM system, including topology and system objects, with center-of-mass and alignment restraints, and receptor position restraints.

```python
complex_topology, complex_system = femto.fe.atm.setup_system(
    config.setup,
    receptor,
    ligand_1,
    ligand_2,
    [],
    displacement,
    receptor_ref_query,
    ligand_1_ref_query,
    ligand_2_ref_query,
)
```

--------------------------------

### ATM System Setup - `femto.fe.atm.setup_system`

Source: https://context7.com/psivant/femto/llms.txt

The `setup_system` function constructs a complete OpenMM system for ATM calculations. This includes solvation, restraints (COM, alignment, optional position restraints on receptor alpha-carbons), and parameterization.

```APIDOC
## ATM System Setup — `femto.fe.atm.setup_system`

Builds a fully solvated, restrained, and parameterized OpenMM system for ATM calculations. Applies COM restraints on ligands, an alignment restraint between the two ligands, and optional position restraints on receptor alpha-carbons.

### Usage

```python
import femto.fe.atm

receptor_ref_query = [
    "resi 36+39+40+42+43+77+80+81 and name CA"
]  # or None for auto-selection
ligand_1_ref_query = ["idx. 7", "idx. 11", "idx. 23"]  # or None
ligand_2_ref_query = ["idx. 12", "idx. 7",  "idx. 21"]  # or None

extra_params = [
    eralpha_dir / "forcefield/2d/vacuum.parm7",
    eralpha_dir / "forcefield/2e/vacuum.parm7",
]

complex_topology, complex_system = femto.fe.atm.setup_system(
    config.setup,
    receptor,
    ligand_1,
    ligand_2,
    extra_params,        # [] to use auto-parameterization
    displacement,
    receptor_ref_query,
    ligand_1_ref_query,
    ligand_2_ref_query,
)

complex_topology.to_file("complex.pdb")  # save for inspection
```
```

--------------------------------

### SepTop Solution Setup — `femto.fe.septop.setup_solution`

Source: https://context7.com/psivant/femto/llms.txt

Builds the solution-phase system: both ligands placed at a fixed separation (distance restraint between their first reference atoms), solvated in a padded box.

```APIDOC
## `femto.fe.septop.setup_solution`

### Description
Builds the solution-phase system: both ligands placed at a fixed separation (distance restraint between their first reference atoms), solvated in a padded box.

### Parameters
- `setup_config`: Setup configuration object.
- `ligand_1`: The first ligand object.
- `ligand_2`: The second ligand object.
- `ligand_1_ref_query`: Query for reference atoms on ligand 1.
- `ligand_2_ref_query`: Query for reference atoms on ligand 2.

### Returns
A tuple containing:
- `solution_topology`: The topology object for the solution phase.
- `solution_system`: The system object for the solution phase.
```

--------------------------------

### ATM Configuration YAML Snippet

Source: https://context7.com/psivant/femto/llms.txt

An example snippet of an ATM configuration file in YAML format. It defines system setup parameters, lambda states, and sampling settings.

```yaml
# Example config-atm.yaml snippet (eralpha system)
type: atm
setup:
  displacement: [22.0 A, 22.0 A, -22.0 A]
  ionic_strength: 0.0 M
  default_ligand_ff: "openff-2.0.0.offxml"
  apply_hmr: true
  hydrogen_mass: 1.5 Da
states:
  lambda_1:  [0.00, 0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50,
              0.50, 0.45, 0.40, 0.35, 0.30, 0.25, 0.20, 0.15, 0.10, 0.05, 0.00]
  direction: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1]
sample:
  n_warmup_steps: 150000
  n_steps_per_cycle: 1000
  n_cycles: 2500
  analysis_interval: 100
```

--------------------------------

### Setup Solution Topology and System

Source: https://github.com/psivant/femto/blob/main/docs/guide-septop.md

Sets up the solution phase calculation by combining ligands at a fixed distance, solvating, and creating the OpenMM system. This approach is based on the 'two ligands separated by a distance restraint' method.

```python
import femto.fe.septop

solution_topology, solution_system = femto.fe.septop.setup_solution(
    config.solution.setup,
    ligand_1,
    ligand_2,
    ligand_1_ref_query,
    ligand_2_ref_query,
)
```

--------------------------------

### SepTop Complex Setup — `femto.fe.septop.setup_complex`

Source: https://context7.com/psivant/femto/llms.txt

Builds a solvated complex system with Boresch-style orientation restraints on each ligand relative to the receptor.

```APIDOC
## `femto.fe.septop.setup_complex`

### Description
Builds a solvated complex system with Boresch-style orientation restraints on each ligand relative to the receptor.

### Parameters
- `setup_config`: Setup configuration object.
- `receptor`: The receptor object.
- `ligand_1`: The first ligand object.
- `ligand_2`: The second ligand object.
- `extra_params`: List of extra parameters for force field parameterization (or `[]` for auto).
- `receptor_ref_query`: Query for reference atoms on the receptor (or `None`).
- `ligand_1_ref_query`: Query for reference atoms on ligand 1 (or `None`).
- `ligand_2_ref_query`: Query for reference atoms on ligand 2 (or `None`).

### Returns
A tuple containing:
- `complex_topology`: The topology object for the complex.
- `complex_system`: The system object for the complex.
```

--------------------------------

### Install femto with Conda/Mamba

Source: https://context7.com/psivant/femto/llms.txt

Installs femto and its dependencies. For MPI on HPC clusters, ensure the OpenMPI version matches your cluster.

```shell
mamba install -c conda-forge femto

# For MPI on HPC clusters, pin the OpenMPI version to match your cluster:
mamba install -c conda-forge femto "openmpi=4.1.5=*external*"
```

--------------------------------

### Setup Complex Topology and System

Source: https://github.com/psivant/femto/blob/main/docs/guide-septop.md

Creates the full complex topology and OpenMM system by combining receptor and ligands, applying restraints, and parameterizing. Requires a configuration object and reference atom queries.

```python
import femto.fe.septop

complex_topology, complex_system = femto.fe.septop.setup_complex(
    config.complex.setup,
    receptor,
    ligand_1,
    ligand_2,
    [],
    receptor_ref_query,
    ligand_1_ref_query,
    ligand_2_ref_query,
    extra_parameters
)
```

--------------------------------

### REST2 Setup

Source: https://context7.com/psivant/femto/llms.txt

Prepares a system for Replica Exchange with Solute Tempering 2 (REST2) by injecting global context parameters (`bm_b0` and `bm_b0_sqrt`) that scale torsion and/or non-bonded interactions of the solute. Must be applied **after** any FEP modifications via `apply_fep`.

```APIDOC
## REST2 Setup — `femto.md.rest.apply_rest`

Prepares a system for Replica Exchange with Solute Tempering 2 (REST2) by injecting global context parameters (`bm_b0` and `bm_b0_sqrt`) that scale torsion and/or non-bonded interactions of the solute. Must be applied **after** any FEP modifications via `apply_fep`.

```python
import femto.md.rest
import femto.md.config
import femto.md.constants

rest_config = femto.md.config.REST(
    scale_torsions=True,
    scale_nonbonded=True,
    scale_angles=False,
    scale_bonds=False,
)

solute_idxs = topology.select(
    f"resn {femto.md.constants.LIGAND_1_RESIDUE_NAME}"
)
# Modifies system in-place
femto.md.rest.apply_rest(system, solute_idxs, rest_config)

# REST2 context parameter names for manual control
print(femto.md.rest.REST_CTX_PARAM)       # "bm_b0"
print(femto.md.rest.REST_CTX_PARAM_SQRT)  # "bm_b0_sqrt"
```
```

--------------------------------

### Install femto with Conda

Source: https://github.com/psivant/femto/blob/main/README.md

Install the femto package using conda or mamba. For HPC environments with MPI, ensure OpenMPI is correctly configured.

```shell
mamba install -c conda-forge femto
```

```shell
mamba install -c conda-forge femto "openmpi=4.1.5=*external*"
```

--------------------------------

### MPI Parallel HREMD Setup

Source: https://context7.com/psivant/femto/llms.txt

This snippet shows how to integrate Femto's MPI utilities into an HREMD script to enable parallel execution across multiple GPUs.

```APIDOC
## MPI Parallel HREMD

For running HREMD across multiple GPUs using MPI, save the HREMD script and run with `mpirun`/`srun`. The GPU assignment helper sets `CUDA_VISIBLE_DEVICES` per MPI rank.

### Usage

```python
# Add at the top of the HREMD script before any simulation code:
import femto.md.utils.mpi
femto.md.utils.mpi.divide_gpus()

# Then call run_hremd as normal...
```

### Execution Examples

```shell
# Run with MPI (SLURM):
srun --mpi=pmix -n 4 python my_hremd_script.py

# Or with mpirun:
mpirun -n 4 python my_hremd_script.py
```
```

--------------------------------

### Setup SepTop Complex System

Source: https://context7.com/psivant/femto/llms.txt

Builds a solvated complex system with Boresch-style orientation restraints. Requires receptor, ligands, and optional reference atom queries for restraint definition.

```python
import femto.fe.septop

receptor_ref_query = ["name CA", "name CB", "name CG"]  # or None
ligand_1_ref_query = ["name C1", "name C2", "name O4"]  # or None
ligand_2_ref_query = ["name C1", "name C3", "name O5"]  # or None

complex_topology, complex_system = femto.fe.septop.setup_complex(
    config.complex.setup,
    receptor,
    ligand_1,
    ligand_2,
    extra_params,         # [] for auto FF parameterization
    receptor_ref_query,
    ligand_1_ref_query,
    ligand_2_ref_query,
)
complex_topology.to_file("complex.pdb")
```

--------------------------------

### Create and Activate Development Environment

Source: https://github.com/psivant/femto/blob/main/docs/development.md

Use these commands to create a new conda development environment and activate it. Ensure mamba is installed first.

```shell
make env
conda activate femto
```

--------------------------------

### Example edges-atm.yaml Configuration

Source: https://context7.com/psivant/femto/llms.txt

Defines the edges for free energy calculations, specifying receptor details and ligand pairs with optional reference atom selections. Minimal form allows auto-selection of reference atoms.

```yaml
# edges-atm.yaml
receptor: eralpha
receptor_ref_query: ":36,39,40,42,43,77,80,81 & @CA"

edges:
  - {ligand_1: 2d, ligand_2: 2e, ligand_1_ref_atoms: ["@7", "@11", "@23"], ligand_2_ref_atoms: ["@12", "@7", "@21"]}
  - {ligand_1: 2d, ligand_2: 3a, ligand_1_ref_atoms: ["@7", "@11", "@23"], ligand_2_ref_atoms: ["@15", "@10", "@5"]}
  # Minimal form (reference atoms auto-selected):
  - {ligand_1: 3a, ligand_2: 3b}

```

--------------------------------

### Submit SepTop Replicas on SLURM

Source: https://github.com/psivant/femto/blob/main/docs/guide-fe.md

This command submits replicas for the SepTop method on a SLURM cluster. Adjust SLURM parameters and paths according to your setup.

```shell
femto septop      --config              "eralpha/config-septop.yaml"  \
                                                                          \
      submit-replicas  --slurm-nodes         5                            \
                       --slurm-tasks         19                           \
                       --slurm-gpus-per-task 1                            \
                       --slurm-cpus-per-task 4                            \
                       --slurm-partition     "project-gpu"                \
                       --slurm-walltime      "48:00:00"                   \
                                                                          \
                       --root-dir            "eralpha"                    \
                       --output-dir          "eralpha/outputs-septop"     \
                       --edges               "eralpha/edges-septop.yaml"  \
                       --n-replicas          5
```

--------------------------------

### Generate Default SepTop Configuration

Source: https://github.com/psivant/femto/blob/main/docs/guide-fe.md

Use the 'config' command to generate the default configuration file for the SepTop method. This is useful for understanding default settings or as a starting point for custom configurations.

```shell
femto septop config > default-septop-config.yaml
```

--------------------------------

### ATM Configuration - `femto.fe.atm.ATMConfig`

Source: https://context7.com/psivant/femto/llms.txt

The `ATMConfig` class serves as the primary configuration object for ATM calculations, allowing programmatic construction or loading from YAML files. It manages setup, lambda states, equilibration, and sampling parameters.

```APIDOC
## ATM Configuration — `femto.fe.atm.ATMConfig`

The top-level Pydantic configuration object for ATM calculations. Can be constructed programmatically or loaded from YAML. Covers setup, lambda states, equilibration, and HREMD sampling.

### Construction and Loading

```python
import femto.fe.atm
import pathlib

# Default configuration
config = femto.fe.atm.ATMConfig()

# Load from YAML (see examples/eralpha/config-atm.yaml)
config = femto.fe.atm.load_config(pathlib.Path("eralpha/config-atm.yaml"))
```

### Inspecting and Overriding Parameters

```python
import openmm.unit

# Inspect key parameters
print(config.states.lambda_1)     # 22-window default schedule
print(config.setup.displacement)  # 38.0 Å default displacement

# Override parameters
config.sample.analysis_interval = 100   # estimate ΔΔG every 100 cycles
config.setup.apply_hmr = True
config.setup.hydrogen_mass = 1.5 * openmm.unit.amu
```

### Dumping Default Configuration

```shell
# Dump default config to YAML:
# femto atm config > default-atm-config.yaml
```

### Example YAML Configuration Snippet

```yaml
# Example config-atm.yaml snippet (eralpha system)
type: atm
setup:
  displacement: [22.0 A, 22.0 A, -22.0 A]
  ionic_strength: 0.0 M
  default_ligand_ff: "openff-2.0.0.offxml"
  apply_hmr: true
  hydrogen_mass: 1.5 Da
states:
  lambda_1:  [0.00, 0.05, 0.10, 0.15, 0.20, 0.25, 0.30, 0.35, 0.40, 0.45, 0.50,
              0.50, 0.45, 0.40, 0.35, 0.30, 0.25, 0.20, 0.15, 0.10, 0.05, 0.00]
  direction: [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1, -1]
sample:
  n_warmup_steps: 150000
  n_steps_per_cycle: 1000
  n_cycles: 2500
  analysis_interval: 100
```
```

--------------------------------

### Define Edges in YAML Configuration

Source: https://github.com/psivant/femto/blob/main/docs/guide-septop.md

Example of a YAML configuration file specifying edges for computation. Each edge is defined by a pair of ligand names, which should correspond to subdirectory names in the 'forcefield' directory.

```yaml
edges:
  - {ligand_1: 2d, ligand_2: 2e}
  - {ligand_1: 2d, ligand_2: 3a}
  - ...
```

--------------------------------

### Generate Default ATM Configuration

Source: https://github.com/psivant/femto/blob/main/docs/guide-fe.md

Use the 'config' command to generate the default configuration file for the ATM method. This is useful for understanding default settings or as a starting point for custom configurations.

```shell
femto atm    config > default-atm-config.yaml
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/psivant/femto/blob/main/docs/development.md

Use this command to serve the project's documentation locally for previewing changes.

```shell
mkdocs serve
```

--------------------------------

### Prepare System with Configuration

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Prepares the system by solvating, parameterizing ligands, neutralizing with ions, and optionally adding salt. Uses a Prepare configuration object for detailed settings.

```python
import openmm.unit

import femto.md.config
import femto.md.prepare

prep_config = femto.md.config.Prepare(
    ionic_strength=0.15 * openmm.unit.molar,
    neutralize=True,
    cation="Na+",
    anion="Cl-",
    water_model="tip3p",
    box_padding=10.0 * openmm.unit.angstrom,
)

topology, system = femto.md.prepare.prepare_system(
    receptor=receptor,  # or None if no receptor
    ligand_1=ligand_1,
    ligand_2=None,      # or `ligand_2` if setting up FEP for example
    config=prep_config,
)
```

--------------------------------

### Save Complex Topology

Source: https://github.com/psivant/femto/blob/main/docs/guide-septop.md

Saves the generated complex topology to a PDB file for inspection or checkpointing. This is useful for verifying the system setup.

```python
complex_topology.to_file("system.pdb")
```

--------------------------------

### Load Ligands and Receptors with femto.md.prepare

Source: https://context7.com/psivant/femto/llms.txt

Utilities for loading ligand (MOL2/SDF) and receptor (PDB/MOL2/SDF) structures. Ligands must be pre-processed.

```python
import pathlib
import femto.md.prepare
import femto.md.constants

eralpha_dir = pathlib.Path("eralpha")

# Load a single ligand (assigns LIGAND_1_RESIDUE_NAME)
ligand = femto.md.prepare.load_ligand(
    eralpha_dir / "forcefield/2d/vacuum.mol2",
    residue_name=femto.md.constants.LIGAND_1_RESIDUE_NAME,
)

# Load a pair of ligands for RBFE (assigns LIG_1 and LIG_2 residue names)
ligand_1, ligand_2 = femto.md.prepare.load_ligands(
    eralpha_dir / "forcefield/2d/vacuum.mol2",
    eralpha_dir / "forcefield/2e/vacuum.mol2",
)

# Load a receptor (protein + crystal waters)
receptor = femto.md.prepare.load_receptor(
    eralpha_dir / "proteins/eralpha/protein.pdb"
)
```

--------------------------------

### ATM Full Workflow CLI Commands

Source: https://context7.com/psivant/femto/llms.txt

Demonstrates how to use the `femto atm` command-line interface to manage and execute complete ATM RBFE calculations. Includes commands for configuration, submitting replicas to SLURM, and running workflows with MPI.

```shell
# Print default ATM configuration
femto atm config > default-atm-config.yaml

# Submit all edges from edges.yaml in parallel on SLURM
femto atm --config "eralpha/config-atm.yaml" \
  submit-replicas \
    --slurm-nodes         2 \
    --slurm-tasks         8 \
    --slurm-gpus-per-task 1 \
    --slurm-cpus-per-task 4 \
    --slurm-partition     "gpu-partition" \
    --slurm-walltime      "48:00:00" \
    --root-dir            "eralpha" \
    --output-dir          "eralpha/outputs-atm" \
    --edges               "eralpha/edges-atm.yaml" \
    --n-replicas          5

# Run a single edge using MPI directly
srun --mpi=pmix -n 22 \
  femto atm --config "eralpha/config-atm.yaml" \
    run-workflow \
      --ligand-1   "2d" \
      --ligand-2   "2e" \
      --root-dir   "eralpha" \
      --output-dir "eralpha/outputs-atm" \
      --edges      "eralpha/edges-atm.yaml"
```

--------------------------------

### Prepare System with Extra Parameters

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Prepares the system, allowing specification of extra parameter files (e.g., FFXML or AMBER prmtop) for ligands or receptors that are already parameterized.

```python
extra_params = [
    eralpha_dir / "forcefield/2d/vacuum.parm7",
    eralpha_dir / "forcefield/2e/vacuum.parm7",
]

topology, system = femto.md.prepare.prepare_system(
    receptor=receptor,  # or None if no receptor
    ligand_1=ligand_1,
    ligand_2=None,      # or `ligand_2` if setting up FEP for example
    config=prep_config,
    extra_params=extra_params
)
```

--------------------------------

### Format Codebase

Source: https://github.com/psivant/femto/blob/main/docs/development.md

Run this command to format the project's codebase according to the defined style guidelines.

```shell
make format
```

--------------------------------

### Initialize HREMD Simulation Output Directory

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Set up the output directory for Hamiltonian replica exchange molecular dynamics (HREMD) simulations. This is a prerequisite for running HREMD.

```python
import pathlib

import openmm.unit

import femto.md.config
import femto.md.constants
import femto.md.hremd
import femto.md.utils.openmm
import femto.md.rest

output_dir = pathlib.Path("hremd-outputs")

```

--------------------------------

### Prepare and Solvate System with femto.md.prepare.prepare_system

Source: https://context7.com/psivant/femto/llms.txt

Combines ligands and receptor into a solvated, neutralized OpenMM system. Accepts optional pre-computed force field parameters; defaults to OpenFF.

```python
import openmm.unit
import femto.md.config
import femto.md.prepare

prep_config = femto.md.config.Prepare(
    ionic_strength=0.15 * openmm.unit.molar,
    neutralize=True,
    cation="Na+",
    anion="Cl-",
    water_model="tip3p",
    box_padding=10.0 * openmm.unit.angstrom,
    default_ligand_ff="openff-2.0.0.offxml",
)

# Optional: provide pre-computed AMBER parameters
extra_params = [
    eralpha_dir / "forcefield/2d/vacuum.parm7",
    eralpha_dir / "forcefield/2e/vacuum.parm7",
]

topology, system = femto.md.prepare.prepare_system(
    receptor=receptor,
    ligand_1=ligand_1,
    ligand_2=None,          # set ligand_2 for FEP/RBFE calculations
    config=prep_config,
    extra_params=extra_params,
)

# Save for checkpointing
import openmm, pathlib
topology.to_file("system.pdb")
pathlib.Path("system.xml").write_text(openmm.XmlSerializer.serialize(system))
```

--------------------------------

### Equilibrate and Sample Solution Phase with HREMD

Source: https://context7.com/psivant/femto/llms.txt

Sets up and runs HREMD simulations for the solution phase. Requires system, topology, state configurations, and platform selection.

```python
solution_coords = femto.fe.septop.equilibrate_states(
    solution_system,
    solution_topology,
    config.solution.states,
    config.solution.equilibrate,
    femto.md.constants.OpenMMPlatform.CUDA,
)
femto.fe.septop.run_hremd(
    solution_system,
    solution_topology,
    solution_coords,
    config.solution.states,
    config.solution.sample,
    femto.md.constants.OpenMMPlatform.CUDA,
    output_dir / "solution",
)
```

--------------------------------

### Setup MPI for GPU Assignment in HREMD

Source: https://context7.com/psivant/femto/llms.txt

Add this import at the beginning of your HREMD script to enable GPU assignment across MPI ranks. This ensures each MPI process uses a distinct GPU.

```python
import femto.md.utils.mpi
femto.md.utils.mpi.divide_gpus()
```

--------------------------------

### Initialize ATMConfig

Source: https://github.com/psivant/femto/blob/main/docs/guide-atm.md

Use the ATMConfig class to configure the full ATM procedure. This involves setting up the complex in solvation, running equilibration simulations, performing HREMD, and computing the final free energy.

```python
import femto.fe.atm

config = femto.fe.atm.ATMConfig()
```

--------------------------------

### Standard Directory Structure for CLI Inputs

Source: https://context7.com/psivant/femto/llms.txt

Illustrates the expected directory structure for Femto CLI inputs. This includes directories for ligands, proteins, and configuration files like `config-atm.yaml` and `edges-atm.yaml`.

```text
<system>/
├── forcefield/
│   ├── <ligand-1>/
│   │   ├── vacuum.mol2       # docked ligand coordinates (required)
│   │   └── vacuum.parm7      # AMBER parameters (optional, auto-generated if absent)
│   └── <ligand-2>/
│       ├── vacuum.mol2
│       └── vacuum.parm7
├── proteins/
│   └── <receptor-name>/
│       ├── protein.pdb       # receptor + crystal waters (required)
│       └── protein.xml       # OpenMM FFXML parameters (optional)
├── config-atm.yaml           # method-specific config (optional, defaults used if absent)
└── edges-atm.yaml            # edge definitions (required)

```

--------------------------------

### Initialize SepTop Configuration

Source: https://github.com/psivant/femto/blob/main/docs/guide-septop.md

Instantiate the SepTopConfig class to begin configuring SepTop calculations. This object partitions options for both complex and solution phases.

```python
import femto.fe.septop

config = femto.fe.septop.SepTopConfig()
```

--------------------------------

### Set up ATM System with OpenMM

Source: https://context7.com/psivant/femto/llms.txt

Constructs a fully prepared OpenMM system for ATM calculations. This includes solvation, restraints (COM, alignment, optional alpha-carbon), and parameterization. Extra parameters can be provided.

```python
import femto.fe.atm

receptor_ref_query = [
    "resi 36+39+40+42+43+77+80+81 and name CA"
]  # or None for auto-selection
ligand_1_ref_query = ["idx. 7", "idx. 11", "idx. 23"]  # or None
ligand_2_ref_query = ["idx. 12", "idx. 7",  "idx. 21"]  # or None

extra_params = [
    eralpha_dir / "forcefield/2d/vacuum.parm7",
    eralpha_dir / "forcefield/2e/vacuum.parm7",
]

complex_topology, complex_system = femto.fe.atm.setup_system(
    config.setup,
    receptor,
    ligand_1,
    ligand_2,
    extra_params,        # [] to use auto-parameterization
    displacement,
    receptor_ref_query,
    ligand_1_ref_query,
    ligand_2_ref_query,
)

complex_topology.to_file("complex.pdb")  # save for inspection
```

--------------------------------

### Loading Ligands and Receptors

Source: https://context7.com/psivant/femto/llms.txt

Utilities for loading pre-docked ligand structures (MOL2/SDF) and receptor structures (PDB/MOL2/SDF). Ligands must already be in the correct protonation state and docked pose before loading.

```APIDOC
## Loading Ligands and Receptors — `femto.md.prepare`

Utilities for loading pre-docked ligand structures (MOL2/SDF) and receptor structures (PDB/MOL2/SDF). Ligands must already be in the correct protonation state and docked pose before loading.

```python
import pathlib
import femto.md.prepare
import femto.md.constants

eralpha_dir = pathlib.Path("eralpha")

# Load a single ligand (assigns LIGAND_1_RESIDUE_NAME)
ligand = femto.md.prepare.load_ligand(
    eralpha_dir / "forcefield/2d/vacuum.mol2",
    residue_name=femto.md.constants.LIGAND_1_RESIDUE_NAME,
)

# Load a pair of ligands for RBFE (assigns LIG_1 and LIG_2 residue names)
ligand_1, ligand_2 = femto.md.prepare.load_ligands(
    eralpha_dir / "forcefield/2d/vacuum.mol2",
    eralpha_dir / "forcefield/2e/vacuum.mol2",
)

# Load a receptor (protein + crystal waters)
receptor = femto.md.prepare.load_receptor(
    eralpha_dir / "proteins/eralpha/protein.pdb"
)
```
```

--------------------------------

### Run Unit Tests

Source: https://github.com/psivant/femto/blob/main/docs/development.md

Execute this command to run all unit tests for the project.

```shell
make test
```

--------------------------------

### Equilibrate States for Solution System

Source: https://github.com/psivant/femto/blob/main/docs/guide-septop.md

Runs the equilibration procedure for a solution system. Requires system, topology, state configurations, equilibration settings, and an OpenMM platform. The results are a list of OpenMM State objects.

```python
import femto.md.constants

coords = femto.fe.septop.equilibrate_states(
    solution_system,
    solution_topology,
    config.solution.states,
    config.solution.equilibrate,
    femto.md.constants.OpenMMPlatform.CUDA,
    reporter=None
)
```

--------------------------------

### Run HREMD Simulation with Tensorboard Reporter

Source: https://github.com/psivant/femto/blob/main/docs/guide-atm.md

Performs HREMD simulation with a specified warmup phase and replica exchange period. Accepts system, topology, coordinates, state configurations, sampling settings, displacement, OpenMM platform, output directory, and an optional reporter. Statistics are logged to TensorBoard and saved as an Arrow parquet file.

```python
import femto.md.reporting

output_dir = pathlib.Path("eralpha/outputs-atm")

reporter = femto.md.reporting.TensorboardReporter(output_dir)  # OR None
config.sample.analysis_interval = 10

femto.fe.atm.run_hremd(
    complex_system,
    complex_topology,
    coords,
    config.states,
    config.sample,
    displacement,
    femto.md.constants.OpenMMPlatform.CUDA,
    output_dir,
    reporter
)
```

--------------------------------

### Configure and Run HREMD Simulation

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Defines REST2 temperatures, prepares simulation states, creates an OpenMM simulation object, and runs the HREMD simulation. Ensure 'system', 'topology', 'final_coords', and 'output_dir' are defined before execution.

```python
import openmm.unit
import femto

# define the REST2 temperatures to sample at
rest_temperatures = [300.0, 310.0, 320.0] * openmm.unit.kelvin
rest_betas = [
    1.0 / (openmm.unit.MOLAR_GAS_CONSTANT_R * rest_temperature)
    for rest_temperature in rest_temperatures
]

states = [
    {femto.md.rest.REST_CTX_PARAM: rest_beta / rest_betas[0]}
    for rest_beta in rest_betas
]
# REST requires both beta_m / beta_0 and sqrt(beta_m / beta_0) to be defined
# we can use a helper to compute the later from the former for each state
states = [
    femto.md.utils.openmm.evaluate_ctx_parameters(state, system)
    for state in states
]

# create the OpenMM simulation object
intergrator_config = femto.md.config.LangevinIntegrator(
    timestep=2.0 * openmm.unit.femtosecond,
)
integrator = femto.md.utils.openmm.create_integrator(
    intergrator_config, rest_temperatures[0]
)

simulation = femto.md.utils.openmm.create_simulation(
    system,
    topology,
    final_coords,  # or None to use the coordinates / box in topology
    integrator=integrator,
    state=states[0],
    platform=femto.md.constants.OpenMMPlatform.CUDA,
)

# define how the HREMD should be run
hremd_config = femto.md.config.HREMD(
    # the number of steps to run each replica for before starting to
    # propose swaps
    n_warmup_steps=150000,
    # the number of steps to run before proposing swaps
    n_steps_per_cycle=500,
    # the number of 'swaps' to propose - the total simulation length
    # will be n_warmup_steps + n_steps * n_cycles
    n_cycles=2000,
    # the frequency with which to store trajectories of each replica.
    # set to None to not store trajectories
    trajectory_interval=10  # store every 10 * 500 steps.
)
femto.md.hremd.run_hremd(
    simulation,
    states,
    hremd_config,
    # the directory to store sampled reduced potentials and trajectories to
    output_dir=output_dir
)
```

--------------------------------

### Run MD Simulation Protocol with Stages

Source: https://context7.com/psivant/femto/llms.txt

Executes a sequence of MD simulation stages including minimization, annealing, NVT, and NPT. Use this to run a complete simulation protocol on a prepared system.

```python
import openmm.unit
import femto.md.config
import femto.md.simulate
import femto.md.constants
import femto.md.rest

temperature = 298.15 * openmm.unit.kelvin
kcal = openmm.unit.kilocalorie_per_mole
ang = openmm.unit.angstrom

ligand_mask = f"resn {femto.md.constants.LIGAND_1_RESIDUE_NAME}"
restraints = {
    ligand_mask: femto.md.config.FlatBottomRestraint(
        k=25.0 * kcal / ang**2, radius=1.5 * ang
    ),
    "protein and name CA": femto.md.config.FlatBottomRestraint(
        k=50.0 * kcal / ang**2, radius=1.5 * ang
    ),
}

stages = [
    femto.md.config.Minimization(restraints=restraints),
    femto.md.config.Anneal(
        integrator=femto.md.config.LangevinIntegrator(
            timestep=1.0 * openmm.unit.femtosecond,
            friction=1.0 / openmm.unit.picosecond,
        ),
        restraints=restraints,
        temperature_initial=50.0 * openmm.unit.kelvin,
        temperature_final=temperature,
        n_steps=50000,
        frequency=5000,
    ),
    femto.md.config.Simulation(
        integrator=femto.md.config.LangevinIntegrator(
            timestep=2.0 * openmm.unit.femtosecond,
        ),
        restraints=restraints,
        temperature=temperature,
        pressure=None,
        n_steps=150000,
    ),
    femto.md.config.Simulation(
        integrator=femto.md.config.LangevinIntegrator(
            timestep=4.0 * openmm.unit.femtosecond,
        ),
        temperature=temperature,
        pressure=1.0 * openmm.unit.bar,
        n_steps=250000,
    ),
]

# state dict sets OpenMM global context parameters (e.g. REST2 scaling = 1.0 = no scaling)
state = {femto.md.rest.REST_CTX_PARAM: 1.0}

final_coords = femto.md.simulate.simulate_state(
    system, topology, state, stages,
    femto.md.constants.OpenMMPlatform.CUDA,
)
```

--------------------------------

### Initialize and Load ATM Configuration

Source: https://context7.com/psivant/femto/llms.txt

Construct a default ATM configuration object or load one from a YAML file. Key parameters can then be inspected or modified.

```python
import femto.fe.atm

# Default configuration
config = femto.fe.atm.ATMConfig()

# Load from YAML (see examples/eralpha/config-atm.yaml)
config = femto.fe.atm.load_config(pathlib.Path("eralpha/config-atm.yaml"))

# Inspect / override key parameters
print(config.states.lambda_1)     # 22-window default schedule
print(config.setup.displacement)  # 38.0 Å default displacement
config.sample.analysis_interval = 100   # estimate ΔΔG every 100 cycles
config.setup.apply_hmr = True
config.setup.hydrogen_mass = 1.5 * openmm.unit.amu

# Dump default config to YAML:
# femto atm config > default-atm-config.yaml
```

--------------------------------

### Run Equilibration for Multiple States

Source: https://github.com/psivant/femto/blob/main/docs/guide-atm.md

Executes the equilibration procedure sequentially for each state. Requires system, topology, state configurations, equilibration settings, displacement, and an OpenMM platform. Results are returned as a list of OpenMM State objects.

```python
import femto.md.constants

coords = femto.fe.atm.equilibrate_states(
    complex_system,
    complex_topology,
    config.states,
    config.equilibrate,
    displacement,
    femto.md.constants.OpenMMPlatform.CUDA,
    reporter=None
)
```

--------------------------------

### Run Molecular Dynamics Simulation Stages

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Execute a sequence of simulation stages using the `simulate_state` function. Pass an empty dictionary for `state` if no global context parameters need to be set.

```python
import femto.md.simulate

state = {femto.md.rest.REST_CTX_PARAM: 1.0}

final_coords = femto.md.simulate.simulate_state(
    system, topology, state, stages, femto.md.constants.OpenMMPlatform.CUDA
)
```

--------------------------------

### MD Simulation Protocol — `femto.md.simulate.simulate_state`

Source: https://context7.com/psivant/femto/llms.txt

Executes a series of simulation stages including minimization, annealing, NVT, and NPT, returning the final system state.

```APIDOC
## `femto.md.simulate.simulate_state`

### Description
Runs a sequence of simulation stages (minimization → annealing → NVT → NPT) on a prepared system. Returns final coordinates as an OpenMM `State`.

### Parameters
- **system**: The OpenMM system object.
- **topology**: The OpenMM topology object.
- **state**: A dictionary of OpenMM global context parameters.
- **stages**: A list of simulation stage configurations (e.g., Minimization, Anneal, Simulation).
- **platform**: The OpenMM platform to use (e.g., `femto.md.constants.OpenMMPlatform.CUDA`).

### Returns
- An OpenMM `State` object representing the final state of the simulation.

### Example
```python
import openmm.unit
import femto.md.config
import femto.md.simulate
import femto.md.constants
import femto.md.rest

temperature = 298.15 * openmm.unit.kelvin
kcal = openmm.unit.kilocalorie_per_mole
ang = openmm.unit.angstrom

ligand_mask = f"resn {femto.md.constants.LIGAND_1_RESIDUE_NAME}"
restraints = {
    ligand_mask: femto.md.config.FlatBottomRestraint(
        k=25.0 * kcal / ang**2, radius=1.5 * ang
    ),
    "protein and name CA": femto.md.config.FlatBottomRestraint(
        k=50.0 * kcal / ang**2, radius=1.5 * ang
    ),
}

stages = [
    femto.md.config.Minimization(restraints=restraints),
    femto.md.config.Anneal(
        integrator=femto.md.config.LangevinIntegrator(
            timestep=1.0 * openmm.unit.femtosecond,
            friction=1.0 / openmm.unit.picosecond,
        ),
        restraints=restraints,
        temperature_initial=50.0 * openmm.unit.kelvin,
        temperature_final=temperature,
        n_steps=50000,
        frequency=5000,
    ),
    femto.md.config.Simulation(
        integrator=femto.md.config.LangevinIntegrator(
            timestep=2.0 * openmm.unit.femtosecond,
        ),
        restraints=restraints,
        temperature=temperature,
        pressure=None,
        n_steps=150000,
    ),
    femto.md.config.Simulation(
        integrator=femto.md.config.LangevinIntegrator(
            timestep=4.0 * openmm.unit.femtosecond,
        ),
        temperature=temperature,
        pressure=1.0 * openmm.unit.bar,
        n_steps=250000,
    ),
]

state = {femto.md.rest.REST_CTX_PARAM: 1.0}

final_coords = femto.md.simulate.simulate_state(
    system, topology, state, stages,
    femto.md.constants.OpenMMPlatform.CUDA,
)
```
```

--------------------------------

### ATM Full Workflow CLI

Source: https://context7.com/psivant/femto/llms.txt

Command-line interface for running complete ATM RBFE calculations on SLURM or locally with MPI.

```APIDOC
## `femto atm` CLI

### Description
The `femto atm` CLI provides commands to run complete ATM RBFE calculations on SLURM clusters or locally with MPI.

### Commands

#### `config`
Prints the default ATM configuration.

```shell
femto atm config > default-atm-config.yaml
```

#### `submit-replicas`
Submits replicas for calculation on SLURM.

##### Parameters
- `--slurm-nodes` (int): Number of SLURM nodes.
- `--slurm-tasks` (int): Number of tasks per node.
- `--slurm-gpus-per-task` (int): Number of GPUs per task.
- `--slurm-cpus-per-task` (int): Number of CPUs per task.
- `--slurm-partition` (str): SLURM partition name.
- `--slurm-walltime` (str): SLURM walltime.
- `--root-dir` (str): Root directory for the calculation.
- `--output-dir` (str): Output directory.
- `--edges` (str): Path to the edges configuration file.
- `--n-replicas` (int): Number of replicas to run.

```shell
femto atm --config "eralpha/config-atm.yaml" \
  submit-replicas \
    --slurm-nodes         2 \
    --slurm-tasks         8 \
    --slurm-gpus-per-task 1 \
    --slurm-cpus-per-task 4 \
    --slurm-partition     "gpu-partition" \
    --slurm-walltime      "48:00:00" \
    --root-dir            "eralpha" \
    --output-dir          "eralpha/outputs-atm" \
    --edges               "eralpha/edges-atm.yaml" \
    --n-replicas          5
```

#### `run-workflow`
Runs a single edge workflow using MPI.

##### Parameters
- `--ligand-1` (str): Identifier for ligand 1.
- `--ligand-2` (str): Identifier for ligand 2.
- `--root-dir` (str): Root directory for the calculation.
- `--output-dir` (str): Output directory.
- `--edges` (str): Path to the edges configuration file.

```shell
srun --mpi=pmix -n 22 \
  femto atm --config "eralpha/config-atm.yaml" \
    run-workflow \
      --ligand-1   "2d" \
      --ligand-2   "2e" \
      --root-dir   "eralpha" \
      --output-dir "eralpha/outputs-atm" \
      --edges      "eralpha/edges-atm.yaml"
```
```

--------------------------------

### Prepare System for REST2 Sampling

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Prepares the system for Hamiltonian replica exchange (REST2) sampling by scaling torsions and non-bonded interactions. This modifies the system in-place. Alchemical modifications should be applied before REST2.

```python
import femto.md.rest

rest_config = femto.md.config.REST(scale_torsions=True, scale_nonbonded=True)

solute_idxs = topology.select(f"resn {femto.md.constants.LIGAND_1_RESIDUE_NAME}")
femto.md.rest.apply_rest(system, solute_idxs, rest_config)
```

--------------------------------

### Save System Inputs

Source: https://github.com/psivant/femto/blob/main/docs/guide-md.md

Saves the prepared OpenMM Topology to a PDB file and the System object to an XML file for later use in simulations.

```python
import openmm

topology.to_file("system.pdb")
pathlib.Path("system.xml").write_text(openmm.XmlSerializer.serialize(system))
```