-
Notifications
You must be signed in to change notification settings - Fork 51
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
regenerated generated reST doc files
- Loading branch information
Showing
12 changed files
with
216 additions
and
202 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,15 +1,25 @@ | ||
.. _estimators_BAR: | ||
alchemlyb.estimators.BAR | ||
======================== | ||
|
||
BAR | ||
=== | ||
The :class:`~alchemlyb.estimators.BAR` estimator is a light wrapper around the implementation of the Bennett Acceptance Ratio (BAR) method from :mod:`pymbar` (:class:`pymbar.mbar.BAR`). | ||
It uses information from neighboring sampled states to generate an estimate for the free energy difference between these state. | ||
.. currentmodule:: alchemlyb.estimators | ||
|
||
.. SeeAlso:: | ||
:class:`alchemlyb.estimators.MBAR` | ||
.. autoclass:: BAR | ||
|
||
API Reference | ||
------------- | ||
.. autoclass:: alchemlyb.estimators.BAR | ||
:members: | ||
:inherited-members: | ||
|
||
.. automethod:: __init__ | ||
|
||
|
||
.. rubric:: Methods | ||
|
||
.. autosummary:: | ||
|
||
~BAR.__init__ | ||
~BAR.fit | ||
~BAR.get_params | ||
~BAR.set_params | ||
|
||
|
||
|
||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,12 +1,32 @@ | ||
.. _estimators_MBAR: | ||
|
||
MBAR | ||
==== | ||
The :class:`~alchemlyb.estimators.MBAR` estimator is a light wrapper around the reference implementation of MBAR from :mod:`pymbar` (:class:`pymbar.mbar.MBAR`). | ||
As a generalization of BAR, it uses information from all sampled states to generate an estimate for the free energy difference between each state. | ||
|
||
API Reference | ||
------------- | ||
.. autoclass:: alchemlyb.estimators.MBAR | ||
:members: | ||
:inherited-members: | ||
alchemlyb.estimators.MBAR | ||
========================= | ||
|
||
.. currentmodule:: alchemlyb.estimators | ||
|
||
.. autoclass:: MBAR | ||
|
||
|
||
.. automethod:: __init__ | ||
|
||
|
||
.. rubric:: Methods | ||
|
||
.. autosummary:: | ||
|
||
~MBAR.__init__ | ||
~MBAR.fit | ||
~MBAR.get_params | ||
~MBAR.predict | ||
~MBAR.set_params | ||
|
||
|
||
|
||
|
||
|
||
.. rubric:: Attributes | ||
|
||
.. autosummary:: | ||
|
||
~MBAR.overlap_matrix | ||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,11 +1,26 @@ | ||
.. _estimatators_TI: | ||
alchemlyb.estimators.TI | ||
======================= | ||
|
||
TI | ||
== | ||
The :class:`~alchemlyb.estimators.TI` estimator is a simple implementation of `thermodynamic integration <https://en.wikipedia.org/wiki/Thermodynamic_integration>`_ that uses the trapezoid rule for integrating the space between :math:`\left<\frac{dH}{d\lambda}\right>` values for each :math:`\lambda` sampled. | ||
.. currentmodule:: alchemlyb.estimators | ||
|
||
API Reference | ||
------------- | ||
.. autoclass:: alchemlyb.estimators.TI | ||
:members: | ||
:inherited-members: | ||
.. autoclass:: TI | ||
|
||
|
||
.. automethod:: __init__ | ||
|
||
|
||
.. rubric:: Methods | ||
|
||
.. autosummary:: | ||
|
||
~TI.__init__ | ||
~TI.fit | ||
~TI.get_params | ||
~TI.separate_dhdl | ||
~TI.set_params | ||
|
||
|
||
|
||
|
||
|
||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,20 +1,40 @@ | ||
Amber parsing | ||
============= | ||
alchemlyb.parsing.amber | ||
======================= | ||
|
||
.. automodule:: alchemlyb.parsing.amber | ||
|
||
The parsers featured in this module are constructed to properly parse `Amber MD`_ output files containing derivatives of the Hamiltonian and FEP (BAR/MBAR) data. | ||
|
||
|
||
|
||
|
||
|
||
|
||
.. rubric:: Functions | ||
|
||
.. autosummary:: | ||
|
||
any_none | ||
convert_to_pandas | ||
extract_dHdl | ||
extract_u_nk | ||
file_validation | ||
|
||
|
||
|
||
.. _Amber MD: http://ambermd.org/ | ||
|
||
|
||
.. rubric:: Classes | ||
|
||
.. TODO | ||
.. autosummary:: | ||
|
||
FEData | ||
SectionParser | ||
|
||
|
||
Notes on what options need to be set in Amber to produce the required output. See the Gromacs parser page for an example of the information that we would like to have here. | ||
|
||
|
||
|
||
|
||
|
||
|
||
API Reference | ||
------------- | ||
This submodule includes these parsing functions: | ||
|
||
.. autofunction:: alchemlyb.parsing.amber.extract_dHdl | ||
.. autofunction:: alchemlyb.parsing.amber.extract_u_nk |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,39 +1,30 @@ | ||
Gromacs parsing | ||
=============== | ||
.. automodule:: alchemlyb.parsing.gmx | ||
|
||
The parsers featured in this module are constructed to properly parse XVG files containing Hamiltonian differences (for obtaining reduced potentials, :math:`u_{nk}`) and/or Hamiltonian derivatives (for obtaining gradients, :math:`\frac{dH}{d\lambda}`). | ||
To produce such a file from an existing EDR energy file, use ``gmx energy -f <.edr> -odh dhdl.xvg`` with your installation of `Gromacs`_. | ||
|
||
If you wish to use FEP-based estimators such as :class:`~alchemlyb.estimators.MBAR` that require reduced potentials for all lambda states in the alchemical leg, you will need to use these MDP options: | ||
|
||
.. code-block:: none | ||
alchemlyb.parsing.gmx | ||
===================== | ||
|
||
calc-lambda-neighbors = -1 ; calculate Delta H values for all other lambda windows | ||
dhdl-print-energy = potential ; total potential energy of system included | ||
In addition, the full set of lambda states for the alchemical leg should be explicitly specified in the ``fep-lambdas`` option (or ``coul-lambdas``, ``vdw-lambdas``, etc.), since this is what Gromacs uses to determine what lambda values to calculate :math:`\Delta H` values for. | ||
|
||
To use TI-based estimators that require gradients, you will need to include these options: | ||
|
||
.. code-block:: none | ||
.. automodule:: alchemlyb.parsing.gmx | ||
|
||
dhdl-derivatives = yes ; write derivatives of Hamiltonian with respect to lambda | ||
|
||
|
||
|
||
|
||
Additionally, the parsers can properly parse XVG files (containing Hamiltonian differences and/or Hamiltonian derivatives) produced during expanded ensemble simulations. To produce such a file during the simulation, use ``gmx mdrun -deffnm <name> -dhdl dhdl.xvg`` with your installation of `Gromacs`_. | ||
To run an expanded ensemble simulation you will need to use the following MDP option: | ||
|
||
|
||
.. rubric:: Functions | ||
|
||
.. code-block:: none | ||
.. autosummary:: | ||
|
||
extract_dHdl | ||
extract_u_nk | ||
|
||
|
||
|
||
free_energy = expanded ; turns on expanded ensemble simulation, lambda state becomes a dynamic variable | ||
|
||
|
||
|
||
|
||
.. _`Gromacs`: http://www.gromacs.org/ | ||
.. _`MDP options`: | ||
|
||
|
||
|
||
|
||
|
||
API Reference | ||
------------- | ||
This submodule includes these parsing functions: | ||
|
||
.. autofunction:: alchemlyb.parsing.gmx.extract_dHdl | ||
.. autofunction:: alchemlyb.parsing.gmx.extract_u_nk |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,15 +1,30 @@ | ||
GOMC parsing | ||
============== | ||
alchemlyb.parsing.gomc | ||
====================== | ||
|
||
.. automodule:: alchemlyb.parsing.gomc | ||
|
||
The parsers featured in this module are constructed to properly parse `GOMC <http://gomc.eng.wayne.edu/>`_ free energy output files, | ||
containing the Hamiltonian derivatives (:math:`\frac{dH}{d\lambda}`) for TI-based estimators and Hamiltonian differences (:math:`\Delta H` | ||
for all lambda states in the alchemical leg) for FEP-based estimators (BAR/MBAR). | ||
|
||
|
||
|
||
|
||
|
||
|
||
.. rubric:: Functions | ||
|
||
.. autosummary:: | ||
|
||
extract_dHdl | ||
extract_u_nk | ||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
API Reference | ||
------------- | ||
This submodule includes these parsing functions: | ||
|
||
.. autofunction:: alchemlyb.parsing.gomc.extract_dHdl | ||
.. autofunction:: alchemlyb.parsing.gomc.extract_u_nk |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,33 +1,29 @@ | ||
NAMD parsing | ||
============= | ||
.. automodule:: alchemlyb.parsing.namd | ||
|
||
The parsers featured in this module are constructed to properly parse `NAMD`_ ``.fepout`` output files containing derivatives of the Hamiltonian and FEP (BAR) data. | ||
See the NAMD documentation for the `theoretical backdrop <https://www.ks.uiuc.edu/Research/namd/2.13/ug/node60.html>`_ and `implementation details <https://www.ks.uiuc.edu/Research/namd/2.13/ug/node61.html>`_. | ||
alchemlyb.parsing.namd | ||
====================== | ||
|
||
If you wish to use BAR on FEP data, be sure to provide the ``.fepout`` file from both the forward and reverse transformations. | ||
.. automodule:: alchemlyb.parsing.namd | ||
|
||
After calling :meth:`~alchemlyb.parsing.namd.extract_u_nk` on the forward and reverse work values, these dataframes can be combined into one: | ||
|
||
|
||
|
||
|
||
.. code-block:: python | ||
|
||
|
||
.. rubric:: Functions | ||
|
||
# replace zeroes in initial dataframe with nan | ||
u_nk_fwd.replace(0, np.nan, inplace=True) | ||
# replace the nan values with the reverse dataframe -- | ||
# this should not overwrite any of the fwd work values | ||
u_nk_fwd[u_nk_fwd.isnull()] = u_nk_rev | ||
# replace remaining nan values back to zero | ||
u_nk_fwd.replace(np.nan, 0, inplace=True) | ||
# sort final dataframe by `fep-lambda` (as opposed to `timestep`) | ||
u_nk = u_nk_fwd.sort_index(level=u_nk_fwd.index.names[1:]) | ||
.. autosummary:: | ||
|
||
extract_u_nk | ||
|
||
|
||
|
||
The ``fep-lambda`` index states at which lambda this particular frame was sampled, whereas the columns are the evaluations of the Hamiltonian (or the potential energy U) at other lambdas (sometimes called "foreign lambdas"). | ||
|
||
|
||
|
||
|
||
.. _`NAMD`: http://www.ks.uiuc.edu/Research/namd/ | ||
|
||
|
||
|
||
|
||
|
||
API Reference | ||
------------- | ||
This submodule includes these parsing functions: | ||
|
||
.. autofunction:: alchemlyb.parsing.namd.extract_u_nk |
37 changes: 27 additions & 10 deletions
37
docs/preprocessing/alchemlyb.preprocessing.subsampling.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,14 +1,31 @@ | ||
.. _subsampling: | ||
|
||
Subsampling | ||
=========== | ||
alchemlyb.preprocessing.subsampling | ||
=================================== | ||
|
||
.. automodule:: alchemlyb.preprocessing.subsampling | ||
|
||
The functions featured in this module can be used to easily subsample either :ref:`dHdl <dHdl>` or :ref:`u_nk <u_nk>` datasets to give less correlated timeseries. | ||
|
||
|
||
|
||
|
||
|
||
|
||
.. rubric:: Functions | ||
|
||
.. autosummary:: | ||
|
||
equilibrium_detection | ||
slicing | ||
statistical_inefficiency | ||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
API Reference | ||
------------- | ||
.. autofunction:: alchemlyb.preprocessing.subsampling.slicing | ||
.. autofunction:: alchemlyb.preprocessing.subsampling.statistical_inefficiency | ||
.. autofunction:: alchemlyb.preprocessing.subsampling.equilibrium_detection |
19 changes: 3 additions & 16 deletions
19
docs/visualisation/alchemlyb.visualisation.plot_convergence.rst
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,19 +1,6 @@ | ||
.. _visualisation_plot_convergence: | ||
|
||
Plot the Forward and Backward Convergence | ||
alchemlyb.visualisation.plot\_convergence | ||
========================================= | ||
|
||
The function :func:`~alchemlyb.visualisation.plot_convergence` allows | ||
the user to visualise the convergence by plotting the free energy change | ||
computed using the equilibrated snapshots between the proper target time frames | ||
in both forward (data points are stored in `forward` and `forward_error`) and | ||
reverse (data points are stored in `backward` and `backward_error`) directions. | ||
The unit in the y axis could be labelled to other units by setting *units*, | ||
which by default is :math:`kT`. The user can pass :class:`matplotlib.axes.Axes` into | ||
the function to have the convergence drawn on a specific axes. | ||
|
||
Please check :ref:`How to plot convergence <plot_convergence>` for usage. | ||
.. currentmodule:: alchemlyb.visualisation | ||
|
||
API Reference | ||
------------- | ||
.. autofunction:: alchemlyb.visualisation.plot_convergence | ||
.. autofunction:: plot_convergence |
Oops, something went wrong.
3ae6668
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@orbeckst Sorry for asking this. It seems that some doc for the visualisation has been removed from the rst files. I wonder if I can have some advice on where should I put these descriptions? Thank you.
3ae6668
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Have to check — some of the docs get autogenerated. Looks as if we lost important docs, sorry.
When you do docs, try building them locally with
(which is what I did).
I'll look into it more on Monday (or so...). If you find anything in the meantime, please open a PR. Right now I am not sure what to do except revert the changes.
3ae6668
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I raised #136. We can do a 0.4.2 to fix this ... sigh.