Hands-On Session 8: Analyze AFE simulation results using FE-ToolKit
=================================================================== 

| Zeke Piskulich\ :sup:`1`, Timothy Giese\ :sup:`1`, and Darrin M. York\ :sup:`1`
| :sup:`1`\ Laboratory for Biomolecular Simulation Research, Institute
  for Quantitative Biomedicine and Department of Chemistry and Chemical
  Biology, Rutgers University, Piscataway, NJ 08854, USA

Learning Objectives
-------------------

.. include:: /ModularTutorials/Alchemical/fe-toolkit/analyzing-abfe-fe-toolkit.rst
    :start-after: .. start-learning-objectives
    :end-before: .. end-learning-objectives

.. include:: /ModularTutorials/Alchemical/fe-toolkit/edgembar-html-reports.rst
    :start-after: .. start-learning-objectives
    :end-before: .. end-learning-objectives

.. include:: /ModularTutorials/Alchemical/fe-toolkit/edgembar-python-api.rst
    :start-after: .. start-learning-objectives
    :end-before: .. end-learning-objectives

.. include:: /ModularTutorials/Alchemical/fe-toolkit/optimizing-lambda-schedule.rst
    :start-after: .. start-learning-objectives
    :end-before: .. end-learning-objectives


Activities
----------

.. contents::
   :local:
   :depth: 4

.. mermaid::

    flowchart LR

    %% ===== extract simulation outputs to dats =====
    A1["Amber AFE outputs<br/>mdouts<br/>rem.log<br/>rest.in"]
    P1{{"<b>[§8.2.2.1]</b><br/>Extract per-lambda data<br/>edgembar-amber2dats.py"}}
    O1["<b>[from §8.2.2.1]</b><br/>efep dat files<br/>edge/env/stage/trial dats"]
    A1 --> P1
    P1 --> O1

    %% ===== build edge xml and run edgembar =====
    P2{{"<b>[§8.2.2.2]</b><br/>Discover edges, write xml<br/>DiscoverEdges.py"}}
    O2["<b>[from §8.2.2.2]</b><br/>Edge input<br/>edge_ejm31.xml"]
    P3{{"<b>[§8.2.2.2]</b><br/>Run BAR/MBAR analysis<br/>edgembar_omp"}}
    O3["<b>[from §8.2.2.2]</b><br/>Report script and data<br/>edge_ejm31.py<br/>edge_ejm31.html<br/>edge_ejm31.nc"]
    O1 --> P2
    P2 --> O2
    O2 --> P3
    P3 --> O3

    classDef file fill:#fff7e6,stroke:#d98c00,stroke-width:1.5px,color:#111;
    classDef program fill:#e8f1ff,stroke:#1f77b4,stroke-width:1.8px,color:#111;
    classDef result fill:#eaf7ea,stroke:#2ca02c,stroke-width:1.5px,color:#111;
    class A1 file;
    class P1,P2,P3,P4,P5 program;
    class O1,O2,O3,O4,O5 result;


In HandsOn9 and HandsOn10, you will learn how to run different variations of alchemical free energy simulations. In this HandsOn tutorial, you will learn how to analyze the results of these simulations using FE-Toolkit. 

You will learn how to extract data from simulation output files, generate analysis reports for relative and absolute binding free energy calculations, and interpret the results.


For these calculations, you will use the following mamba environment. If you have previously used other amber modules in this session, you may need to run modules purge first to avoid conflicts with the FE-Toolkit environment.

.. code-block:: console

    module purge
    unset PYTHONPATH
    mamba activate ambertools

Accessing the Tutorial Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

To get the tutorial data during the workshop, you can get a copy into your scratch with this command.

.. code-block:: bash

   DataDir="/data/amber26/TutorialData/HandsOn8_FE_Toolkit"
   TutorialDir="/scratch/$USER/TutorialData/HandsOn8_FE_Toolkit"
   mkdir -p $TutorialDir
   cp -r $DataDir/* $TutorialDir
   cd $TutorialDir
   cp -r input working_dir
   cd working_dir

.. danger::

    These files are nearly 50 gb. The limit of the DIPC home directory is 50 gb. 

.. include:: /ModularTutorials/Alchemical/fe-toolkit/analyzing-abfe-fe-toolkit.rst
    :start-after: .. start-tutorial
    :end-before: .. end-tutorial


.. include:: /ModularTutorials/Alchemical/fe-toolkit/edgembar-html-reports.rst
    :start-after: .. start-tutorial
    :end-before: .. end-tutorial

For the next tutorial, change directories into the API subdirectory.

.. code-block:: bash

    cd ../API

.. include:: /ModularTutorials/Alchemical/fe-toolkit/edgembar-python-api.rst
    :start-after: .. start-tutorial
    :end-before: .. end-tutorial

For the next tutorial, change directories into the LambdaSchedules subdirectory.

.. code-block:: bash

    cd ../LambdaSchedules

.. code-block:: bash

    mamba deactivate
    module load Amber/25.0-foss-2022a-AmberTools-25-CUDA-12.1.1-DeePMD 


.. include:: /ModularTutorials/Alchemical/fe-toolkit/optimizing-lambda-schedule.rst
    :start-after: .. start-tutorial
    :end-before: .. start-skip-download


.. include:: /ModularTutorials/Alchemical/fe-toolkit/optimizing-lambda-schedule.rst
    :start-after: .. end-skip-download
    :end-before: .. end-tutorial

Alternative Methods
-------------------

pymbar - a python package for MBAR analysis. See the pymbar documentation for more information: https://pymbar.readthedocs.io/en/latest/



References
-------------------

.. footbibliography::