### Make Installer Executable and Run

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Make the OpenFEforge installer script executable and then run it to begin the installation process.

```bash
$ chmod +x ./OpenFEforge-Linux-x86_64.sh
$ ./OpenFEforge-Linux-x86_64.sh
```

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

### Install Conda-Lock and Create Environment

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Install conda-lock in a separate environment, then use it to install OpenFE from a conda-lock file, and finally activate the OpenFE environment.

```bash
$ # Install conda lock into a virtual environment
$ micromamba create -n conda-lock conda-lock
$ # Activate the environment to use the conda-lock command
$ micromamba activate conda-lock
$ conda-lock install -n openfe openfe-conda-lock.yml
$ micromamba activate openfe
```

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

### Miniforge Installation Command Generation

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

This JavaScript code dynamically generates Miniforge installation commands based on user selections for OS, architecture, and shell. It constructs a curl command to download the installer, a shell command to run it, a command to initialize mamba, and a command to clean up the installer file.

```javascript
function setArchitectureOptions(os) {
          let options = {
              "MacOSX": [
                  ["x86_64", ""],
                  ["arm64", " (Apple Silicon)"]
              ],
              "Linux": [
                  ["x86_64", " (amd64)"],
                  ["aarch64", " (arm64)"],
                  ["ppc64le", " (POWER8/9)"]
              ]
          };
          choices = options[os];
          let htmlString = ""
          for (const [val, extra] of choices) {
              htmlString += `<option value="${val}">${val}${extra}</option>`;
          }
          let arch = document.getElementById("miniforge-architecture");
          arch.innerHTML = htmlString
          updateInstructions()
      }

      function updateInstructions() {
          let cmd = document.getElementById("miniforge-curl-install");
          let osElem = document.getElementById("miniforge-os");
          let archElem = document.getElementById("miniforge-architecture");
          let shellElem = document.getElementById("miniforge-shell");
          let os = osElem[osElem.selectedIndex].value;
          let arch = archElem[archElem.selectedIndex].value;
          let shell = shellElem[shellElem.selectedIndex].value;
          let filename = "Miniforge3-" + os + "-" + arch + ".sh"
          let cmdArr = [
              (
                  "curl -OL https://github.com/conda-forge/miniforge/"
                  + "releases/latest/download/" + filename
              ),
              "sh " + filename + " -b",
              "~/miniforge3/bin/mamba init " + shell,
              "rm -f " + filename,
          ]
          cmd.innerHTML = cmdArr.join("\n")
      }

      setArchitectureOptions("Linux");  // default
```

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

### Install Development Version

Source: https://github.com/openfreeenergy/openfe/blob/main/README.md

Install the openfe library from the main branch after setting up dependencies. This command installs the package without its dependencies, assuming they are already managed.

```bash
python -m pip install --no-deps .
```

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

### Verify Python Installation Path

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Check if the Python installation path is set up correctly after installation. The output should indicate the OpenFE forge bin directory.

```bash
(base) $ which python
/home/mmh/openfeforge/bin/python
```

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

### Installer License Agreement Prompt

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

This snippet shows the interactive prompt during the OpenFEforge installation where the user must review and accept the MIT license terms.

```text
Welcome to OpenFEforge 0.7.4

In order to continue the installation process, please review the license
agreement.
Please, press ENTER to continue
>>>
MIT License

Copyright (c) 2022 OpenFreeEnergy

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.


Do you accept the license terms? [yes|no]
[no] >>> yes
```

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

### PlainMDSetupUnit

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_md.rst

Handles the setup phase of the plain MD simulation.

```APIDOC
## PlainMDSetupUnit

### Description
This unit is responsible for all the necessary setup steps before the Molecular Dynamics simulation begins, such as system preparation and initial configuration.

### Class Signature
openfe.protocols.openmm_md.PlainMDSetupUnit
```

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

### Get Help for `openfe quickrun`

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/cli/cli_basics.rst

Obtain detailed help for the `quickrun` subcommand, including its usage, options, and how to prepare input files.

```none
Usage: openfe quickrun [OPTIONS] TRANSFORMATION

  Run the transformation (edge) in the given JSON file.

  Simulation JSON files can be created with the :ref:`cli_plan-rbfe-network`
  or from Python a :class:`.Transformation` can be saved using its to_json
  method::

      transformation.to_json("filename.json")

  That will save a JSON file suitable to be input for this command.

  Running this command will execute the simulation defined in the JSON file,
  creating a directory for each individual task (``Unit``) in the workflow.
  For example, when running the OpenMM HREX Protocol a directory will be
  created for each repeat of the sampling process (by default 3).

Options:
  -d, --work-dir DIRECTORY  Directory in which to store files in (defaults to
                            current directory). If the directory does not
                            exist, it will be created at runtime.
  -o PATH                   Filepath at which to create and write the JSON-
                            formatted results.
  --resume                  Attempt to resume this transformation's execution
                            using the cache.
  -h, --help                Show this message and exit.
```

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

### Perform Editable Installation of OpenFE

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Install OpenFE in editable mode from the current directory, without installing dependencies.

```bash
$ python -m pip install -e . --no-deps
```

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

### Download Linux Single File Installer

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Download the single file installer for OpenFE on x86_64 Linux using curl.

```bash
$ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/OpenFEforge-Linux-x86_64.sh
```

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

### Install Experimental openfe with Membrane Support

Source: https://github.com/openfreeenergy/openfe/wiki/openfe-dev-version-installs

Installs an experimental release of openfe with membrane support. This version is for testing membrane loading interfaces and should not be relied upon for accuracy. It is primarily for API usage.

```bash
micromamba install -c conda-forge/label/openfe_dev -c conda-forge/label/gufe_rc -c conda-forge "openfe=1.9.1.dev0"
```

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

### Installer Location Confirmation

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

This output shows the prompt for confirming the installation directory. The user can press Enter to accept the default or specify a new location.

```text
OpenFEforge will now be installed into this location:
/home/mmh/openfeforge

- Press ENTER to confirm the location
- Press CTRL-C to abort the installation
- Or specify a different location below

[/home/mmh/openfeforge] >>>
PREFIX=/home/mmh/openfeforge
Unpacking payload ...

Installing base environment...


Downloading and Extracting Packages


Downloading and Extracting Packages

Preparing transaction: done
Executing transaction: 
 By downloading and using the CUDA Toolkit conda packages, you accept the terms and conditions of the CUDA End User License Agreement (EULA): https://docs.nvidia.com/cuda/eula/index.html

| Enabling notebook extension jupyter-js-widgets/extension...
      - Validating: OK

done
installation finished.
Do you wish the installer to initialize OpenFEforge
by running conda init? [yes|no]
[no] >>> yes
```

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

### Download MacOS Single File Installer

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Download the single file installer for OpenFE on arm64 macOS using curl.

```bash
$ curl -LOJ https://github.com/OpenFreeEnergy/openfe/releases/latest/download/OpenFEforge-MacOSX-arm64.sh
```

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

### Standard Installation with Micromamba

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Install OpenFE from conda-forge using micromamba, specifying the version, and activate the environment.

```bash
micromamba create -c conda-forge -n openfe openfe=\|version|
micromamba activate openfe
```

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

### Create a new RBFE project

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/tutorials/rbfe_cli_tutorial.rst

Use the 'openfe init' command to create a new project directory with the necessary structure for an RBFE calculation. This sets up configuration files and example scripts.

```bash
openfe init --template rbfe my_rbfe_project
```

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

### Install OpenEye Toolkits

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Install the openeye-toolkits package using mamba, required for functionalities that depend on OpenEye tools. Ensure you have a valid OpenEye license.

```bash
$ mamba install -c openeye openeye-toolkits
```

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

### Verify OpenFE CLI Installation

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Confirm that the OpenFE command-line interface (CLI) is installed and accessible. This command should display the usage information for the OpenFE tool.

```bash
(base) $ openfe --help
Usage: openfe [OPTIONS] COMMAND [ARGS]...

  This is the command line tool to provide easy access to functionality from
  the OpenFE Python library.

Options:
  --version   Show the version and exit.
  --log PATH  logging configuration file
  -h, --help  Show this message and exit.

Network Planning Commands:
  plan-rhfe-network    Plan a relative hydration free energy network, saved as
                       JSON files for the quickrun command.
  plan-rbfe-network    Plan a relative binding free energy network, saved as
                       JSON files for the quickrun command.
  view-ligand-network  Visualize a ligand network

Quickrun Executor Commands:
  gather    Gather result jsons for network of RFE results into a TSV file
  quickrun  Run a given transformation, saved as a JSON file

Miscellaenous Commands:
  fetch             Fetch tutorial or other resource.
  charge-molecules  Generate partial charges for a set of molecules.
  test              Run the OpenFE test suite
```

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

### Install Development Version Dependencies

Source: https://github.com/openfreeenergy/openfe/blob/main/README.md

Install package dependencies using mamba for the development version of openfe. Ensure you have mamba installed.

```bash
mamba env create -f environment.yml
mamba activate openfe_env
```

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

### Download and Run Debugging Script

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Download the openmm debugging script and pipe its output to a log file. This script assists in troubleshooting installation errors by checking environment configurations.

```bash
$ bash -c "$(curl -Ls https://raw.githubusercontent.com/OpenFreeEnergy/openfe/main/devtools/debug_openmm.sh)" | tee -a debug.log
```

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

### Run OpenFE Test Suite

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Execute the standard test suite to verify your OpenFE installation. This includes an initial compilation step that may take longer on the first run.

```bash
$ openfe test
```

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

### Mamba Installation Success Message

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

This is the final output displayed after a successful OpenFEforge installation, including the Mamba version and links to its GitHub and Twitter.

```text

                        __    __    __    __
                       /  \  /  \  /  \  /  \
                      /    \/    \/    \/    \
      ███████████████/  /██/  /██/  /██/  /████████████████████████
                    /  / \   / \   / \   / \  \____
                   /  /   \_/   \_/   \_/   \    o \__,
                  / _/                       \_____/  `
                  |/
              ███╗   ███╗ █████╗ ███╗   ███╗██████╗  █████╗
              ████╗ ████║██╔══██╗████╗ ████║██╔══██╗██╔══██╗
              ██╔████╔██║███████║██╔████╔██║██████╔╝███████║
              ██║╚██╔╝██║██╔══██║██║╚██╔╝██║██╔══██╗██╔══██║
              ██║ ╚═╝ ██║██║  ██║██║ ╚═╝ ██║██████╔╝██║  ██║
              ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝     ╚═╝╚═════╝ ╚═╝  ╚═╝

              mamba (1.4.2) supported by @QuantStack

              GitHub:  https://github.com/mamba-org/mamba
              Twitter: https://twitter.com/QuantStack

█████████████████████████████████████████████████████████████
```

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

### Conda Initialization Output

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

This output details the changes made to shell configuration files during the 'conda init' step of the OpenFEforge installation.

```text
no change     /home/mmh/openfeforge/condabin/conda
no change     /home/mmh/openfeforge/bin/conda
no change     /home/mmh/openfeforge/bin/conda-env
no change     /home/mmh/openfeforge/bin/activate
no change     /home/mmh/openfeforge/bin/deactivate
no change     /home/mmh/openfeforge/etc/profile.d/conda.sh
no change     /home/mmh/openfeforge/etc/fish/conf.d/conda.fish
no change     /home/mmh/openfeforge/shell/condabin/Conda.psm1
no change     /home/mmh/openfeforge/shell/condabin/conda-hook.ps1
no change     /home/mmh/openfeforge/lib/python3.9/site-packages/xontrib/conda.xsh
no change     /home/mmh/openfeforge/etc/profile.d/conda.csh
modified      /home/mmh/.bashrc

==> For changes to take effect, close and re-open your current shell. ==
```

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

### AHFESolventSetupUnit

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_solvation_afe.rst

Represents the setup unit for the AHFESolvent protocol.

```APIDOC
## AHFESolventSetupUnit

### Description
This unit is responsible for setting up the molecular system and simulation parameters for the AHFESolvent protocol.

### Method Signature
`AHFESolventSetupUnit()`

### Parameters
Refer to `AbsoluteSolvationSettings` for configurable parameters.
```

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

### Generate a Minimal Spanning Ligand Network

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/creating_ligand_networks.rst

This snippet demonstrates how to set up and generate a ligand network using specified mappers, scorers, and a network planner. Ensure you have loaded your ligands into SmallMoleculeComponent objects and initialized the necessary OpenFE setup components.

```python
import openfe
from openfe import setup

# load a set of ligands
mols = [SmallMoleculeComponent.from_rdkit(x) for x in rdmols]

# generate the required mapper, scorer, and planner objects
mapper = setup.KartografAtomMapper()
scorer = setup.lomap_scorers.default_lomap_score
network_planner =  setup.ligand_network_planning.generate_minimal_spanning_network

# plan the ligand network
ligand_network = network_planner(ligands=mols, mappers=[mapper], scorer=scorer)
```

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

### Install Local Development Version of gufe

Source: https://github.com/openfreeenergy/openfe/blob/main/CONTRIBUTING.md

Clone and install a local development version of the gufe package. This is useful when developing openfe in tandem with gufe.

```bash
mamba activate openfe_env  # if not already activated
git clone git@github.com:OpenFreeEnergy/gufe.git
cd gufe/
pip install -e . --no-deps
```

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

### Test OpenMM Installation in Apptainer Container

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Verify that the Apptainer container can access a GPU and that OpenMM is functioning correctly. The output should list the CUDA platform if GPU access is successful.

```bash
$ singularity run --nv openfe_latest-apptainer.sif python -m openmm.testInstallation
```

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

### Quickrun within a Job Submission Script

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/execution/quickrun_execution.rst

Example of how to use the `openfe quickrun` command within a bash script for submission to a queueing engine like Slurm. Ensure the environment is activated.

```bash
#!/bin/bash

#SBATCH --job-name="openfe job"
#SBATCH --mem-per-cpu=2G

# activate an appropriate conda environment, or any "module load" commands required to
conda activate openfe_env

openfe quickrun transformation.json -d workdir/ -o workdir/results.json
```

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

### AHFEVacuumSetupUnit

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_solvation_afe.rst

Represents the setup unit for the AHFEVacuum protocol.

```APIDOC
## AHFEVacuumSetupUnit

### Description
This unit is responsible for setting up the molecular system and simulation parameters for the AHFEVacuum protocol.

### Method Signature
`AHFEVacuumSetupUnit()`

### Parameters
Refer to `AbsoluteSolvationSettings` for configurable parameters.
```

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

### Clone OpenFE Repository

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Clone the OpenFE GitHub repository to your local machine to begin a developer installation.

```bash
$ git clone https://github.com/OpenFreeEnergy/openfe.git
$ cd openfe
```

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

### Run OpenFE Tests from Apptainer Container

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Execute the OpenFE test suite from within the Apptainer container to ensure the installation is working correctly. The '--nv' flag is required for GPU access.

```bash
$ singularity run --nv openfe_latest-apptainer.sif openfe test
```

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

### JAX GPU Acceleration Warning

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/troubleshooting.rst

This warning indicates that a CUDA-enabled jaxlib is not installed, causing JAX to fall back to CPU. This does not affect the molecular dynamics simulation's computing platform.

```bash
WARNING:2025-06-10 09:01:40,857:jax._src.xla_bridge:966: An NVIDIA GPU may be present on this machine, but a CUDA-enabled jaxlib is not installed. Falling back to cpu.
```

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

### Create Protocol with Default Settings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/defining_protocols.rst

Instantiate a protocol using its default settings. Ensure the protocol module is imported.

```python
from openfe.protocols import openmm_rfe

settings = openmm_rfe.RelativeHybridTopologyProtocol.default_settings()
protocol = openmm_rfe.RelativeHybridTopologyProtocol(settings)
```

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

### Basic Quickrun Command

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/execution/quickrun_execution.rst

Execute a simulation defined by a JSON transformation file. Use `-d` to specify the working directory and `-o` for the output results file.

```bash
> openfe quickrun transformation.json -d workdir/ -o workdir/results.json
```

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

### Default CLI Planning Settings YAML

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/cli/cli_yaml.rst

This YAML file demonstrates the default settings for network generation, atom mapping, and partial charge calculation. It serves as a reference for understanding the structure and available options.

```yaml
network:
  method: generate_minimal_spanning_network
mapper:
  method: LomapAtomMapper
  settings:
    time: 1
    threed: True
    max3d: 0.95
    element_change: True
partial_charge:
  method: am1bcc
  settings:
    off_toolkit_backend: ambertools
```

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

### Generate system components

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/tutorials/rbfe_cli_tutorial.rst

Use the 'openfe generate' command to create the necessary system components, such as solvent, ions, and protein environments, based on your defined ligands and transformations.

```bash
openfe generate --config config.yaml --output-dir ./system_components
```

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

### List OpenFE Subcommands

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/cli/cli_basics.rst

View all available subcommands and their descriptions. Use `openfe -h` for the same output.

```none
Usage: openfe [OPTIONS] COMMAND [ARGS]...

  This is the command line tool to provide easy access to functionality from
  the OpenFE Python library.

Options:
  --version   Show the version and exit.
  --log PATH  logging configuration file
  -h, --help  Show this message and exit.

Network Planning Commands:
  plan-rhfe-network    Plan a relative hydration free energy network, saved as
                      JSON files for the quickrun command.
  plan-rbfe-network    Plan a relative binding free energy network, saved as
                      JSON files for the quickrun command.
  view-ligand-network  Visualize a ligand network

Quickrun Executor Commands:
  gather    Gather result jsons for network of RFE results into a TSV file
  quickrun  Run a given transformation, saved as a JSON file

Miscellaenous Commands:
  fetch             Fetch tutorial or other resource.
  charge-molecules  Generate partial charges for a set of molecules.
  test              Run the OpenFE test suite
```

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

### Run Transformation from JSON using CLI

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/cookbook/dumping_transformation.rst

Execute a transformation saved in a JSON file using the `openfe` command-line tool's `quickrun` command. Specify the output directory and a file for results.

```bash
$ openfe quickrun mytransformation.json -d dir_for_files -o output.json
```

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

### AlchemicalSettings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_rfe.rst

Settings specific to the alchemical setup within the RelativeHybridTopologyProtocol.

```APIDOC
## AlchemicalSettings

### Description
This settings class contains parameters specifically related to the alchemical transformation setup in the `RelativeHybridTopologyProtocol`. It governs how the system is modified to transition between the initial and final states during the free energy calculation.

### Model
`openfe.protocols.openmm_rfe.equil_rfe_settings.AlchemicalSettings`
```

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

### Create Protein-Membrane Complex in Chemical System

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/chemical_systems_and_thermodynamic_cycles.rst

Use `ProteinMembraneComponent.from_pdb_file` to load a protein-membrane system. Then, construct a `ChemicalSystem` by combining a ligand with this protein-membrane component, omitting a separate `SolventComponent`.

```python
protein_membrane = openfe.ProteinMembraneComponent.from_pdb_file('./protein_membrane.pdb')
ligand_A_complex = openfe.ChemicalSystem(components={'ligand': ligand_A, 'protein_membrane': protein_membrane})
```

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

### Activate Conda Environment

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Activate the 'openfe_env' conda environment to use its installed packages.

```bash
$ micromamba activate openfe_env
```

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

### Generate Adaptive Protocol Settings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/defining_protocols.rst

Use the experimental _adaptive_settings method to generate recommended settings based on input chemical systems and mappings. This method is subject to change.

```python
from openfe.protocols import openmm_rfe

settings = openmm_rfe.RelativeHybridTopologyProtocol._adaptive_settings(
    stateA=stateA,
    stateB=stateB,
    mapping=mapping,
)

protocol = openmm_rfe.RelativeHybridTopologyProtocol(settings)
```

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

### Check CUDA Version with nvidia-smi

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Run 'nvidia-smi' on the target HPC node to determine the compatible CUDA version for your installation.

```bash
$ nvidia-smi
Tue Mar 31 19:46:32 2026
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 590.48.01              Driver Version: 590.48.01      CUDA Version: 13.1     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA A100 80GB PCIe          On  |   00000000:65:00.0 Off |                    0 |
| N/A   32C    P0             44W /  300W |       0MiB /  81920MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------+

+-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI              PID   Type   Process name                        GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+
```

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

### Get Distances Between Mapped Atoms

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/creating_atom_mappings_and_scores.rst

Calculate the Cartesian distances between corresponding atoms in an atom mapping. This method returns a NumPy array of distances.

```python
mapping.get_distances()
```

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

### Incomplete Transformation Error

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/execution/quickrun_execution.rst

This error occurs if a transformation has started but is incomplete, and the `--resume` flag was not provided. It advises removing the cache file or resuming.

```text
Transformation has been started but is incomplete. Please remove
<work-dir>/quickrun_cache/dag-cache-<key>.json and rerun, or resume
execution using the ``--resume`` flag.
```

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

### Set up the RBFE calculation

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/tutorials/rbfe_cli_tutorial.rst

Configure the simulation parameters, including the force field, solvent model, and simulation engine, for the RBFE calculation. This is often done in a configuration file.

```yaml
settings:
  forcefield: "openff-2.0.0.offxml"
  solvent: "tip3p"
  engine: "openmm"
  protocol: "alchemical_free_energy"
```

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

### Install OpenFE with Specific CUDA Version using micromamba

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Create a new conda environment with OpenFE and a specified CUDA version compatible with your HPC system.

```bash
$ micromamba create -n openfe cuda-version=13.1 openfe=\ |version|
```

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

### Skeleton for a New CLI Subcommand

Source: https://github.com/openfreeenergy/openfe/blob/main/src/openfecli/README.md

This skeleton demonstrates the recommended structure for a new CLI subcommand module, including the command method, the main workflow method, and the CommandPlugin registration. Imports are excluded for brevity.

```python
import click
from openfe.utils.command_plugin import CommandPlugin

@click.command("my_command", short_help="This is my command")
# ... add decorators for arguments/options
def my_command(...):  # input params are based on arguments options
    """Docstring here is the help given by ``openfe my-command --help``"""
    ...  # do whatever you need to convert the user input to library objects
    my_command_main(...)  # takes library objects

def my_command_main(...):  # takes library objects
    ...  # run some simple library code
    return result

PLUGIN = CommandPlugin(
    command=my_command,
    section="My Section",
    requires_lib=(1, 0),
    requires_cli=(1, 0)
)
```

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

### Configure Debug Logging for openfe

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/troubleshooting.rst

Use this INI configuration file to set the log level to DEBUG for openfe. Save it as 'debug_logging.conf' and use the '--log' flag with 'openfe quickrun'.

```ini
[loggers]
keys=root

[handlers]
keys=stdout

[formatters]
keys=standardFormatter,msgOnly

[handler_stdout]
class=StreamHandler
level=DEBUG
formatter=standardFormatter
args=(sys.stdout,)

[logger_root]
level=DEBUG
handlers=stdout

[formatter_standardFormatter]
format=%(asctime)s %(levelname)s %(name)s: %(message)s

[formatter_msgOnly]
format=%(message)s
```

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

### Compressing Data for Zenodo Upload

Source: https://github.com/openfreeenergy/openfe/wiki/How-to-upload-large-test-data-to-Zenodo

Use tar to compress your test data directories before uploading to Zenodo. This ensures the data is packaged efficiently for storage and version control.

```bash
tar -czvf rbfe_results_serial_repeats.tar.gz rbfe_results_serial_repeats/
tar -czvf rbfe_results_parallel_repeats.tar.gz rbfe_results_parallel_repeats/

```

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

### Run the RBFE calculation

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/tutorials/rbfe_cli_tutorial.rst

Execute the RBFE calculation using the 'openfe run' command, specifying the project directory and any relevant configuration files. This command orchestrates the simulation setup and execution.

```bash
openfe run --project ./my_rbfe_project --settings settings.yaml
```

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

### Quickrun Cache Not Found Warning

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/execution/quickrun_execution.rst

This message appears when `--resume` is used but no cached results file is found, indicating a new execution will begin.

```text
openfe quickrun was run with --resume, but no cached results found at
<path-to-cache-file>. Starting new execution.
```

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

### SepTopSettings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_septop.rst

Configuration settings for the SepTopProtocol.

```APIDOC
## SepTopSettings

### Description
This model defines all tunable parameters for the Separated Topologies protocol, allowing customization of the simulation setup, execution, and analysis.

### Usage
Instantiate `SepTopSettings` or use `SepTopProtocol.default_settings()` to get a default configuration, then modify attributes as needed before passing to `SepTopProtocol`.

### Fields
Contains various settings related to alchemical transformations, lambda scheduling, and output options.
```

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

### Using the CLI with Custom YAML Settings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/cli/cli_yaml.rst

This command shows how to apply a custom YAML settings file to the `openfe plan-rbfe-network` command. Ensure your YAML file is correctly formatted and referenced using the `-s` option.

```bash
openfe plan-rbfe-network -M molecules.sdf -p protein.pdb -s settings.yaml
```

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

### PlainMDSimulationUnit

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_md.rst

Executes the Molecular Dynamics simulation steps.

```APIDOC
## PlainMDSimulationUnit

### Description
This unit performs the actual Molecular Dynamics simulation integration steps using OpenMM.

### Class Signature
openfe.protocols.openmm_md.PlainMDSimulationUnit
```

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

### Run openfe with Debug Logging Enabled

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/troubleshooting.rst

Execute 'openfe quickrun' with the '--log' flag pointing to your debug logging configuration file. This command enables verbose logging for easier debugging.

```bash
$ openfe --log debug_logging.conf quickrun -d results/ -o results/result_lig_ejm_31_solvent_lig_ejm_42_solvent.json transformations/rbfe_lig_ejm_31_solvent_lig_ejm_42_solvent.json
```

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

### Adapt Existing Settings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/defining_protocols.rst

Optionally provide an initial settings object to _adaptive_settings to receive an adapted copy, rather than using the default settings.

```python
from openfe.protocols import openmm_rfe

initial_settings = openmm_rfe.RelativeHybridTopologyProtocol.default_settings()
adapted_settings = openmm_rfe.RelativeHybridTopologyProtocol._adaptive_settings(
    stateA=stateA,
    stateB=stateB,
    mapping=mapping,
    initial_settings=initial_settings
)

protocol = openmm_rfe.RelativeHybridTopologyProtocol(adapted_settings)
```

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

### Enable JAX Acceleration in openfe

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/troubleshooting.rst

To enable JAX acceleration, set the environment variable 'PYMBAR_DISABLE_JAX' to 'FALSE' before running 'openfe quickrun'. This is useful if you need JAX acceleration despite potential memory issues.

```bash
export PYMBAR_DISABLE_JAX=FALSE
```

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

### Create RHFE Network via CLI

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/alchemical_network_model.rst

Use the 'openfe plan-rhfe-network' command to create a Relative Hydration Free Energy network. Specify the directory containing SDF files for molecules.

```bash
$ openfe plan-rhfe-network -M dir_with_sdfs/
```

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

### Charge Molecules with OpenFE CLI

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/tutorials/charge_molecules_cli_tutorial.rst

Use the `openfe charge` command to assign partial charges to molecules. Ensure your input file is in SDF format and specify the desired charging method.

```bash
openfe charge --input molecules.sdf --output molecules_charged.sdf --method am1bcc
```

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

### List Top-Level JSON Keys with jq

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/cookbook/jq_inspection.rst

Use `jq "keys"` to display all the top-level keys in a JSON file. For cleaner output, consider using `"keys[]"`.

```bash
$ jq "keys" rbfe_lig_ejm_46_solvent_lig_jmc_28_solvent.json
[
"estimate",
"protocol_result",
"uncertainty",
"unit_results"
]
```

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

### Create Environment with Conda-Lock

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Create a new environment named 'openfe' using a downloaded conda-lock file and activate it.

```bash
$ micromamba create -n openfe --file openfe-conda-lock.yml
$ micromamba activate openfe
```

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

### SepTopComplexSetupUnit

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_septop.rst

Unit responsible for setting up the complex system for the Separated Topologies protocol.

```APIDOC
## SepTopComplexSetupUnit

### Description
Handles the initial setup of the molecular system for the complex in the Separated Topologies protocol.

### Usage
This unit is typically called internally by `SepTopProtocol` during the setup phase.
```

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

### PlainMDProtocolSettings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_md.rst

Configuration settings for the PlainMDProtocol.

```APIDOC
## PlainMDProtocolSettings

### Description
This Pydantic model defines the configurable parameters and settings required to run the PlainMDProtocol.

### Model
openfe.protocols.openmm_md.plain_md_settings.PlainMDProtocolSettings
```

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

### Gather Results with CLI

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/introduction.rst

Aggregate simulation results from a directory into a summary table. The output is a tab-separated file containing estimated Delta G and its uncertainty.

```bash
$ openfe gather ./results/ -o final_results.tsv
```

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

### SepTopEquilOutputSettings

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_septop.rst

Settings for controlling the output of the equilibrium phase in the Separated Topologies protocol.

```APIDOC
## SepTopEquilOutputSettings

### Description
This settings class specifies the options for generating output files and data during the equilibrium phase of the Separated Topologies calculation.

### Usage
Can be configured within `SepTopSettings` to control what data is saved, how frequently, and in what format.

### Fields
Controls output related to the equilibrium simulation.
```

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

### Visualize Atom Mapping in 3D

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/guide/setup/creating_atom_mappings_and_scores.rst

Generate an interactive 3D visualization of an atom mapping using the mapping.view_3d() method. This requires the py3Dmol package and is best viewed in an interactive environment like a Jupyter notebook.

```python
from openfe.utils import visualization_3D

view = mapping.view_3d()
```

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

### SepTopSolventSetupUnit

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_septop.rst

Unit responsible for setting up the solvent system for the Separated Topologies protocol.

```APIDOC
## SepTopSolventSetupUnit

### Description
Handles the initial setup of the solvent system for the Separated Topologies protocol.

### Usage
This unit is typically called internally by `SepTopProtocol` during the setup phase.
```

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

### Create Conda Environment from Environment File

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/installation.rst

Create a conda environment named 'openfe_env' using the requirements specified in 'environment.yml'.

```bash
$ micromamba create -f environment.yml
```

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

### PlainMDProtocol

Source: https://github.com/openfreeenergy/openfe/blob/main/docs/reference/api/openmm_md.rst

Represents the main protocol for running a plain Molecular Dynamics simulation.

```APIDOC
## PlainMDProtocol

### Description
This class defines the overall structure and execution flow for a plain Molecular Dynamics simulation protocol.

### Class Signature
openfe.protocols.openmm_md.PlainMDProtocol
```