docs/examples/run_REXEE.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "87324540",
   "metadata": {},
   "source": [
    "# Tutorial 1: Launching a REXEE simulation"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2d9b443",
   "metadata": {},
   "source": [
    "In this tutorial, we will show how one can launch an ensemble of expanded ensemble simulations in parallel using functions in `ensemble_md`. To this end, we will at least need 4 files: one top file (`sys.top`) and one gro file (`sys.gro`) for the system of interest, one mdp file as the template for customizing mdp files for different replicas (`expanded.mdp`), and finally a yaml file speciying the REXEE-relevant parameters (`params.yaml`). \n",
    "\n",
    "In our case, the system of interest is a linear model composed of 4 interaction sites, where the first and last atom have a charge of +0.2 and -0.2, respectively. In `expanded.mdp`, we define 9 alchemical states in total to decouple the van der Waals interactions and coulombic interactions. Our goal is to run an ensemble composed of 4 replicas of expanded ensemble, each of which sample 6 alchemical states, with the shift between adjacent replicas being 1 state. That is, we want replicas 0 to 3 to sample states 0 to 6, 1 to 7, 2 to 8, and 3 to 9, respectively. Each replica will be performed for 5 iterations, with the length of each iteration being 500 steps (i.e. 1 ps). We will use the Metropolis MC scheme to swap replicas, and use exponential averaging with histogram correction for combining weights of exchanging replicas. The histogram cutoff will be set as 1000 to avoid overcorrection and we will swap 2 pairs of replicas in each attempt when possible. All STDOUT will be redirected to `results.txt`. \n",
    "\n",
    "To have all these settings, we should have a yaml file with the following content. \n",
    "```\n",
    "# User-defined parameters\n",
    "parallel: True               # Whether the replicas of EXEE should be run in parallel or not\n",
    "n_sim: 4                     # Number of replica simulations\n",
    "n_iterations: 5              # Number of iterations\n",
    "s: 1                         # Shift in λ ranges (e.g. s = 2 if λ_2 = (2, 3, 4) & λ_3 = (4, 5, 6))\n",
    "nst_sim: 500                 # Number of simulation steps for each homogeneous replica\n",
    "mdp: 'expanded.mdp'          # The MDP template that has the whole range of λ values\n",
    "mc_scheme: 'metropolis'      # The method for swapping simulations. Choices include \"same_state\", \"metropolis\", and \"metropolis-eq\".\n",
    "w_scheme: 'hist-exp-avg'     # The method for combining weights. Choices include \"None\" (unspecified), exp_avg, ...\n",
    "N_cutoff: 1000               # The histogram cutoff. Only required if histo-exp-avg is used.\n",
    "n_pairs: 2                   # Number of pairs of simulations to be swapped in each attempt.\n",
    "outfile: 'results.txt'       # The output file for logging how replicas interact with each other.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cedf8d9",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.8.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}