openfe

OpenFE

Use this repo skill when a task involves OpenFE, Open Free Energy, alchemical free energy calculations, RBFE/RHFE, ABFE/AHFE, SepTop, OpenMM-backed protocol setup, openfe CLI workflows, or post-run OpenFE result analysis.

OpenFE is a Python package and CLI for planning and executing alchemical free energy calculations. Keep future-agent work safe by separating planning, protocol configuration, execution commands, and result interpretation.

Start Here

1. Read Repository Provenance before deciding whether this skill matches a current checkout or should be refreshed.
2. Read Installation and Environment for public install routes, import checks, Python support, and OpenMM/GPU environment notes.
3. Run or adapt check_openfe_environment.py for a safe local diagnostic that does not run simulations.
4. Use Troubleshooting for cross-cutting install/import/OpenMM/CUDA/JAX/logging failures.
5. Route the actual task to one of the sub-skills below.

Route by Task

• Use network-planning for components, ligand/protein/solvent inputs, atom mapping, ligand networks, RBFE/RHFE planning, mapper/scorer choices, and pre-execution data validation.
• Use protocols for selecting RelativeHybridTopologyProtocol, AbsoluteBindingProtocol, AbsoluteSolvationProtocol, SepTopProtocol, or PlainMDProtocol; editing settings; understanding Transformation, ProtocolDAG, execute_DAG; and OpenMM backend settings.
• Use cli-workflows for openfe command routing, plan-rbfe-network, plan-rhfe-network, quickrun, charge-molecules, fetch, test, repeat-safe command generation, resume behavior, and command-line troubleshooting.
• Use results-analysis for result JSON decoding, estimate / uncertainty, ProtocolResult methods, gather, gather-abfe, gather-septop, repeat folders, TSV interpretation, storage metadata, and partial/failed result diagnosis.

Safe Defaults

• Prefer read-only inspection and command construction before execution. openfe quickrun, full planning commands, charge generation, fetch, and long tests can create files, download data, or run expensive simulation work.
• Use API-side planning for interactive or programmatic workflows; use CLI-side planning when the desired output is a directory of transformation JSONs for quickrun.
• Treat OpenFE components, ligand networks, protocols, transformations, and results as provenance-sensitive objects. Rebuild corrected objects rather than mutating existing ones in place.
• Keep repeat execution paths unique. Reusing the same quickrun output file or work directory across repeats risks overwrite or resume-cache confusion.
• Preserve physical units when reporting free energies and uncertainties.

Minimal Checks

After installing OpenFE in a user environment, start with:

python - <<'PY'
import openfe, openfecli
print(openfe.__version__)
print(openfecli.__version__)
PY
openfe --help

For deeper non-mutating checks, run:

python scripts/check_openfe_environment.py --json

Common Handoffs

• Planning produced transformation JSONs and the user wants to run them: go from network-planning to cli-workflows.
• Planning found charged transformations or protocol-repeat concerns: go from network-planning to protocols, then back to cli-workflows for commands.
• quickrun finished or failed and the user has result files: go from cli-workflows to results-analysis.
• Gather output looks incomplete: use results-analysis first, then route missing-input or failed-execution causes to cli-workflows or protocols.

What Not to Do

• Do not run simulations, submit scheduler jobs, download tutorial data, or execute long tests just to answer a planning or diagnostic question.
• Do not assume a GPU warning means OpenMM simulation is on CPU; distinguish OpenMM platform settings from JAX/PyMBAR analysis warnings.
• Do not tell users to inspect original repository docs or tests as part of this runtime skill; use the bundled references and scripts here.