add example

docs/source/conf.py

@@ -14,7 +14,7 @@
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = ['nbsphinx']
 
 templates_path = ['_templates']
 exclude_patterns = []

docs/source/examples.rst

@@ -6,4 +6,4 @@ Examples
 .. toctree::
    :maxdepth: 1
 
-   three_harmonics
+   examples/three_harmonics.ipynb

examples/three_harmonics.ipynb → docs/source/examples/three_harmonics.ipynb

@@ -4,23 +4,24 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Compute free energy differences among three states"
+    "# Compute free energy differences among three states\n",
+    "\n",
+    "In this example, we will use BayesMBAR to compute the free energy differences among three states.\n",
+    "Each of the three states corresponds to a harmonic oscillator with a different force constant and equilibrium position.\n",
+    "Because the potential energy function is quadratic, the free energy differences among the three states can be computed analytically.\n",
+    "To compute the free energy differences using BayesMBAR, we follow the following steps:\n",
+    "\n",
+    "1. Draw samples from the Boltzmann distribution of each state.\n",
+    "2. For each sample from each state, compute its reduced potential energy in all three states. Put the reduced potential energies in a matrix, which will be used as input to BayesMBAR.\n",
+    "3. Use BayesMBAR to compute the free energy differences among the three states. \n",
+    "\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "/cluster/tufts/dinglab/shared_apps/miniconda3/envs/test/lib/python3.12/site-packages/fastprogress/fastprogress.py:107: UserWarning: Couldn't import ipywidgets properly, progress bar will use console behavior\n",
-      "  warn(\"Couldn't import ipywidgets properly, progress bar will use console behavior\")\n"
-     ]
-    }
-   ],
+   "outputs": [],
    "source": [
     "import math\n",
     "import numpy as np\n",
@@ -30,20 +31,34 @@
     "from bayesmbar import BayesMBAR"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Define the eqilibrium positions and force constants of the three harmonic oscillators and compute the free energy differences among the three states using the analytical formula."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 2,
    "metadata": {},
    "outputs": [],
    "source": [
     "M = 3 ## number of states\n",
-    "mu = np.array([0.0, 1.0, 2.0])\n",
-    "k = np.array([16.0, 25.0, 36.0])\n",
+    "mu = np.array([0.0, 1.0, 2.0]) ## equilibrium positions\n",
+    "k = np.array([16.0, 25.0, 36.0]) ## force constants\n",
     "sigma = np.sqrt(1.0 / k)\n",
     "\n",
     "F_true = np.array([-np.log(sigma[i] / sigma[0]) for i in range(1, M)])"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Draw samples from the Boltzmann distribution of each state and compute the reduced potential energies of the samples in all three states."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 3,
@@ -59,6 +74,13 @@
     "num_conf = np.array([n for i in range(M)])\n"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Run BayesMBAR to compute the free energy differences among the three states and compare the results with the analytical formula."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": 4,
@@ -68,7 +90,7 @@
      "name": "stderr",
      "output_type": "stream",
      "text": [
-      "An NVIDIA GPU may be present on this machine, but a CUDA-enabled jaxlib is not installed. Falling back to cpu.\n"
+      "CUDA backend failed to initialize: Unable to load CUDA. Is it installed? (Set TF_CPP_MIN_LOG_LEVEL=0 and rerun for more info.)\n"
      ]
     },
     {
@@ -83,11 +105,11 @@
       "\n",
       "                    Tolerance EPS = 1.00000E-12                  \n",
       "\n",
-      "At iterate    0; f= 8.73798E+00; |1/2*Newton_decrement^2|: 2.67554E-04\n",
+      "At iterate    0; f= 8.74608E+00; |1/2*Newton_decrement^2|: 2.49502E-04\n",
       "\n",
-      "At iterate    1; f= 8.73770E+00; |1/2*Newton_decrement^2|: 1.21303E-07\n",
+      "At iterate    1; f= 8.74583E+00; |1/2*Newton_decrement^2|: 6.92783E-08\n",
       "\n",
-      "At iterate    2; f= 8.73770E+00; |1/2*Newton_decrement^2|: 1.87904E-14\n",
+      "At iterate    2; f= 8.74583E+00; |1/2*Newton_decrement^2|: 3.57769E-15\n",
       "\n",
       "N_iter   = total number of iterations\n",
       "N_func   = total number of function and gradient evaluations\n",
@@ -96,17 +118,14 @@
       "             * * *     \n",
       "\n",
       "N_iter    N_func        F\n",
-      "     3         5    8.737705E+00\n",
-      "  F = 8.737704723510 \n",
+      "     3         5    8.745826E+00\n",
+      "  F = 8.745826354948 \n",
       "\n",
       "CONVERGENCE: 1/2*Newton_decrement^2 < EPS\n",
       "\n",
       "=====================================================\n",
       "Sample from the likelihood\n",
-      "Running window adaptation\n",
-      " |████████████████████████████████████████| 100.00% [200/200 00:00<?]\n",
-      "Sample using the NUTS sampler\n",
-      " |████████████████████████████████████████| 100.00% [2000/2000 00:00<?]\n"
+      "Sample using the NUTS sampler\n"
      ]
     }
    ],
@@ -121,7 +140,8 @@
     "    sample_size=2000,\n",
     "    warmup_steps=200,\n",
     "    optimize_steps=0,\n",
-    "    random_seed=0\n",
+    "    random_seed=0,\n",
+    "    verbose=False\n",
     ")"
    ]
   },

docs/source/index.rst

@@ -17,12 +17,3 @@ This package provides a Python implementation of the BayesMBAR method.
 
    installation
    examples
-
-
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`