Merge pull request #4 from shirtsgroup/xrefs

Update all links and references
shirtsgroup · Apr 29, 2024 · b7680a8 · b7680a8
2 parents 5fe7031 + edf7589
commit b7680a8
Show file tree

Hide file tree

Showing 20 changed files with 1,484 additions and 440 deletions.
diff --git a/alchemistry/Bibliography.ipynb b/alchemistry/Bibliography.ipynb
@@ -0,0 +1,36 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "05374969-127b-4546-b8e1-54d869d3079f",
+   "metadata": {},
+   "source": [
+    "# Bibliography\n",
+    "\n",
+    "```{bibliography}\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/alchemistry/Glossary.ipynb b/alchemistry/Glossary.ipynb
@@ -0,0 +1,331 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "37722a3c-30a7-4cd6-b77b-ac54b85d9a33",
+   "metadata": {},
+   "source": [
+    "(glossary_head)=\n",
+    "# Glossary, Terms, and Definitions"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ced36afc-eb37-4c05-ad46-b65cbce8dbb1",
+   "metadata": {},
+   "source": [
+    "## Nomenclature and Variables\n",
+    "In an effort to keep things uniform, this section contains all the common constants and variables that are seen throughout the fundamentals sections. Although the Table itself is not in any particular order, the sorting buttons should help you find what you are looking for. The alternate listings of some variables are things one may encounter in literature, although this site will strive to be uniform in its naming process."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b40bf308-c235-4e96-8dff-c60140bf7e33",
+   "metadata": {},
+   "source": [
+    "% LNN: Can't use the \"glossary\" directive because it can only do plain text in its reference for {term} roles. Using math, as many of these terms are, wont render correctly. Instead, I'm using shorthand references we can insert as standard sphinx/myst links. I tried every way of linking under the sun and nothing worked if its in the {glossary} directive. The markdown-it-py implementation of Pandoc's deffinition list just isn't able to handle the math as MyST says the \"role implementation is up to the developer.\" "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d36c5a3b-c130-4cdb-b4a5-7ffdc5502b3f",
+   "metadata": {},
+   "source": [
+    "% This syntax reproducex the {glossary} and {term} directives exactly in the tippy\n",
+    "(kb)=\n",
+    "### Boltzmann's Constant\n",
+    "\n",
+    "Symbol: $ k_B$\n",
+    "\n",
+    "[Boltzmann's Constant](http://en.wikipedia.org/wiki/Boltzmann_constant)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d97d9ae7-5317-4ebf-bd29-26a2adf92147",
+   "metadata": {},
+   "source": [
+    "(pot)=\n",
+    "### Potential Energy\n",
+    "\n",
+    "Symbol: $ U $\n",
+    "\n",
+    "This is the total internal energy  calculated a classical simulation, the sum of the potential and kinetic energies."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "5ba1315d-e5ac-454b-968c-2115f3838360",
+   "metadata": {},
+   "source": [
+    "(temp)=\n",
+    "### Temperature\n",
+    "\n",
+    "Symbol: $ T $\n",
+    "\n",
+    "This is often shown with $k_B$ as well, and so common in fact that there is a common variable affiliated with it: $\\beta$."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1be514e5-3b06-4e6e-92d5-12b3e8b4bde8",
+   "metadata": {},
+   "source": [
+    "(beta)=\n",
+    "### $\\beta$\n",
+    "\n",
+    "Inverse Boltzmann constant times temperature: $\\beta=(k_BT)^{-1}$\n",
+    "\n",
+    "Because it is so common in most the equations, one will see $\\beta^{-1}$ more often than $k_BT$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0fe1d80d-f0ad-4671-9a88-8c6ced82d724",
+   "metadata": {},
+   "source": [
+    "(p)=\n",
+    "### Pressure\n",
+    "\n",
+    "Symbol: $P$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "29d34a48-f2c7-445b-a499-6c689a7376c0",
+   "metadata": {},
+   "source": [
+    "(rpot)=\n",
+    "### Reduced Potential\n",
+    "\n",
+    "Symbol: $u$\n",
+    "\n",
+    "Expressed as $u=\\beta(U+PV-\\sum \\mu N_i)$.  For many equations, it is simpler to work with the reduced potential.\n",
+    "\n",
+    "In the case of NVT ensembles, the PV and $\\mu N_i$ terms are zero.  For NPT ensembles, the $\\sum \\mu N_i$ is zero, and for $NV\\mu$ ensembles, the PV term is zero."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8f6459e6-e4f7-4387-ad76-8dfbe5a6c85d",
+   "metadata": {},
+   "source": [
+    "(v)=\n",
+    "### Volume (traditional)\n",
+    "Symbol: $V$\n",
+    "\n",
+    "**CAUTION:** Volume in this sense is the kind you think of with box size. Not to be confused with the *Phase Space Volume.* This particular volume is not often considered by itself and should only show up on this site within $PV$ terms, or *NVT*."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2fc3f7ee-8ed8-4d3e-a54b-0cfa888a3f67",
+   "metadata": {},
+   "source": [
+    "(gamma)=\n",
+    "### Phase Space Volume\n",
+    "Symbol: $\\Gamma$\n",
+    "\n",
+    "Total set of coordinates and momenta where the system has a nonzero probability of being found\n",
+    "\n",
+    "**CAUTION:** This is not volume in standard physical sense, meaning the volume of the box, but the volume space times the momentum space."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "153b0260-3f02-4318-8f8e-6d502c92f63e",
+   "metadata": {},
+   "source": [
+    "(q)=\n",
+    "### Coordinates and Momentum, collective\n",
+    "Symbol: $q$ or $\\vec{q}$\n",
+    "\n",
+    "Can also be seen as $\\mathbf{x}$, $\\mathbf{\\vec{x}}$, and a number of other terms in literature."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1db5772c-8aa9-4a8f-9187-8c78dd05dd79",
+   "metadata": {},
+   "source": [
+    "(lj)=\n",
+    "### Lennard-Jones Parameters\n",
+    "Symbols: $\\epsilon$ and $\\sigma$\n",
+    "\n",
+    "Lennard-Jones parameters for the well depth and the radius of the point particle respectively."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b954d85f-58e7-4e30-8518-d6e1302fdc75",
+   "metadata": {},
+   "source": [
+    "(part)=\n",
+    "### Partition Function\n",
+    "Symbol: $Q$\n",
+    "\n",
+    "Partition function for the canonical or NVT ensemble, but sometimes also signifies an arbitrary partition function of any ensemble. <br/>$Q=\\int_{\\Gamma}e^{-\\beta U (\\vec{q})}\\,\\mathrm{d}\\vec{q}$\n",
+    "\n",
+    "In the examples here, this will represent the canonical partition function although most of the theory shown here works for an arbitrary partition function as well, though sometimes with slight modifications, where $Q=\\int_{\\Gamma}e^{-u(\\vec{q})}\\,\\mathrm{d}\\vec{q}$"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d7fef26c-ef51-41e2-af2a-c32d05c3e96c",
+   "metadata": {},
+   "source": [
+    "(tau)=\n",
+    "#### Autocorrelation Time\n",
+    "Symbol: $\\tau$\n",
+    "\n",
+    "[Autocorrelation time](correlation)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "34ba896e-9f81-4ab3-90f8-c3102ccb6eae",
+   "metadata": {},
+   "source": [
+    "(nvt)=\n",
+    "### NVT\n",
+    "System held at constant **N**umber of particles, **V**olume, and **T**emperature. Free energy calculations performed in this ensemble yield Helmholtz free energies."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "28c11317-a1fd-4bf5-91cb-9fb382af0009",
+   "metadata": {},
+   "source": [
+    "(npt)=\n",
+    "### NPT\n",
+    "System held at constant **N**umber of particles, **P**ressue, and **T**emperature. Free energy calculations performed in this ensemble yield Gibbs free energies."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "da54f896-67a4-428a-ae3d-24aec0dbb2bc",
+   "metadata": {},
+   "source": [
+    "### TI\n",
+    "[Thermodynamic Integration](TI)\n",
+    "\n",
+    "\n",
+    "### EXP\n",
+    "[Exponential Averaging](exp_avg)\n",
+    "Also called \"free energy perturbation\" and the \"Zwanzig relationship.\"\n",
+    "\n",
+    "### BAR\n",
+    "[Bennett Acceptance Ratio](BAR)\n",
+    "\n",
+    "\n",
+    "### MBAR\n",
+    "[Multistate Bennett Acceptance Ratio](fundamentals/MBAR)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6e7c7c5f-c761-4c48-8171-1646ffd0c72b",
+   "metadata": {},
+   "source": [
+    "(boltz_weight)=\n",
+    "### Boltzmann Weight\n",
+    "The probability of a microstate $\\vec{q}$, defined $e^{-u(\\vec{q})}/Q$, where $u(\\vec{q})$ is the reduced potential.  It can also refer to simply $e^{-u(\\vec{q})}$, although this is not a full weight because it is not normalized by the partition function."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "54f79745-800f-4c0d-ab5e-f344868b0b94",
+   "metadata": {},
+   "source": [
+    "(state)=\n",
+    "### State \n",
+    "\n",
+    "Variable: $K$ \n",
+    "\n",
+    "A unique set of conditions and parameters that completely describe a thermodynamic system. For all examples here, the upper case variable $K$ will denote all states (or the count thereof), and the lower case variable $k$ will refer to a specific state."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "863b0089-bb4a-4f8a-a00a-626d8265a67a",
+   "metadata": {},
+   "source": [
+    "(lambda)=\n",
+    "### $\\lambda$\n",
+    "Alchemical variable, thermodynamic path coordinate\n",
+    "\n",
+    "The most common symbol for denoting/tracking the progress along some alchemical pathway. Since most free energy calculations involve an [alchemical thermodynamic path](Intermediate_States), [this site](<welcome>) was named accordingly."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "72cecd90-0bac-451d-b545-8136df75bdc1",
+   "metadata": {},
+   "source": [
+    "(annihilation)=\n",
+    "### Annihilating or Annihilated\n",
+    "The act of removing ALL of an atoms interactions with the system, this includes the molecule's interactions with itself.\n",
+    "\n",
+    "Intermolecular force = OFF, Intramolecular forces = OFF. Also known as disappeared or destroyed. Not to be confused with \"decoupling.\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ed87577e-3525-4e46-8114-ccbcd1710fd1",
+   "metadata": {},
+   "source": [
+    "(decoupling)=\n",
+    "### Decoupling\n",
+    "The act of removing an atom or molecules interactions with its surroundings ONLY; the interactions between the molecule itself remain active.\n",
+    "\n",
+    "Intermolecular force = OFF, Intramolecular forces = ON. Not to be confused with \"annihilation.\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "0128919d-f1bc-441e-a081-e602cf98b7a7",
+   "metadata": {},
+   "source": [
+    "(fe_facts)=\n",
+    "## Facts from the Free Energy Difference Definition\n",
+    "There are a number of key notes we can learn from the definition of free energy differences. Each of these can be important in interpreting simulation results.\n",
+    "\n",
+    "1. **Only free energy *differences* are ever calculated.** There is never a calculation where absolute free energies are needed (and rarely can they be calculated at all) as all of the biological or thermodynamical quantities of interest are based on a free energy difference. As such, there must always be a minimum of two defined thermodynamic states.\n",
+    "    * Even *absolute* free energies of binding are still free energy differences between two states: the ligand restricted to the binding site, and the ligand free to explore all other configurations.\n",
+    "1. **Free energy differences between states at different temperatures are usually not what you want to be calculating** for problems of interest.  If it did, you would get $\\Delta A_{ij} = -k_B T_j \\ln Q_j + k_B T_i \\ln Q_i$, which is no longer a ratio calculation and not needed for biological systems of interest. Temperature dependence on free energy is more likely to be \"what is $ \\Delta A_{ij} $ change at two different temperatures?\"\n",
+    "1. **There are two different phase space volumes.** $\\Gamma_i$ and $\\Gamma_j$ are often the same, but they are not required to be. The methods presented here almost always assumes that the two phase spaces overlap. However, when the spaces do not overlap, these methods break down and it is difficult to identify this problem without in depth knowledge of your system. Consider the example of a hard sphere solute with radius $\\sigma$ at state $i$ and a Lennard Jones repulsion/dispersion potential, with the same $\\sigma$ at state $j$. Since $\\Gamma _i$ will not have molecules at a distance less than $\\sigma$, but $\\Gamma_j$ will, the two phase spaces are not the same and these methods will either break down or return very error-prone results.\n",
+    "    * The degree to which the phase spaces are shared is called the \"phase space overlap\". Efficient free energy calculations require significant phase space overlap. There are  [a number of strategies to address](Intermediate_States) lack of overlap between target spaces, but determining the best way for any given situation is still a research question.\n",
+    "    * It should also be noted that \"near zero probability\" and \"always zero probability\" are two distinct things when considering phase space. So long as there is a chance for an observation to be made, no matter how small, it is considered part of the phase space."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "edd9b414-3c1a-45fb-839f-7b699037cec9",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "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.12.3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}