diff --git a/README.md b/README.md index a97a99fb..f1708768 100644 --- a/README.md +++ b/README.md @@ -4,9 +4,13 @@ [![PyPI Version](https://badge.fury.io/py/pymbar.png)](https://pypi.python.org/pypi/pymbar) [![DOI](https://zenodo.org/badge/9991771.svg)](https://zenodo.org/badge/latestdoi/9991771) -pymbar +pymbar 3 LTS ====== +**Warning** +You are looking at the documentation for pymbar 3 LTS. +If you want the latest version, look [here](https://github.com/choderalab/pymbar) + Python implementation of the [multistate Bennett acceptance ratio (MBAR)](http://www.alchemistry.org/wiki/Multistate_Bennett_Acceptance_Ratio) method for estimating expectations and free energy differences from equilibrium samples from multiple probability densities. See our [docs](http://pymbar.readthedocs.org/en/latest/). @@ -16,15 +20,11 @@ Installation The easiest way to install the `pymbar` release is via [conda](http://conda.pydata.org): ```bash -conda install -c conda-forge pymbar -``` -You can also install `pymbar` from the [Python package index](https://pypi.python.org/pypi/pymbar) using `pip`: -```bash -pip install pymbar +conda install -c conda-forge "pymbar<4" ``` The development version can be installed directly from github via `pip`: ```bash -pip install git+https://github.com/choderalab/pymbar.git +pip install git+https://github.com/choderalab/pymbar.git@pymbar-3-lts ``` Usage diff --git a/docs/conf.py b/docs/conf.py index 0a14cf23..cc639219 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -44,7 +44,7 @@ # 'sphinx.ext.autosummary' #] extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', 'sphinx.ext.pngmath', 'sphinx.ext.ifconfig', + 'sphinx.ext.todo', 'sphinx.ext.imgmath', 'sphinx.ext.ifconfig', 'numpydoc', 'sphinx.ext.inheritance_diagram', 'sphinx.ext.autosummary', 'sphinx.ext.extlinks', 'sphinxcontrib.bibtex'] @@ -52,7 +52,7 @@ autosummary_generate = True autodoc_default_flags = ['members', 'inherited-members'] numpydoc_show_class_members = False - +bibtex_bibfiles = ["references.bib"] # concatenate both class and __init__ docstrings when generating autodoc class # docs autoclass_content = 'both' @@ -92,7 +92,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -168,7 +168,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +#html_static_path = ['_static'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied @@ -313,3 +313,7 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False +rst_prolog = """.. attention:: + You are looking at the documentation for the pymbar 3 LTS branch. + If you want to update to the latest pymbar version, see this page https://pymbar.readthedocs.io/en/stable/moving_from_pymbar3.html +""" diff --git a/docs/getting_started.rst b/docs/getting_started.rst index e47d5380..b6d72905 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -11,26 +11,27 @@ Installing ``pymbar`` conda (recommended) ------------------- -The easiest way to install the ``pymbar`` release is via `conda `_: +This documentation covers ``pymbar`` 3. +This is a long term support branch of ``pymbar``. +The easiest way to install the LTS version of ``pymbar`` release is via `conda `_: -:: - $ conda install -c conda-forge pymbar +.. code-block:: console -pip ---- + $ conda install -c conda-forge "pymbar<4" -You can also install ``pymbar`` from the `Python package index `_ using ``pip``: +pip (pypi) +---------- -:: - $ pip install pymbar +Note: We are currently not releasing new versions of the LTS branch on ``PyPI``. Development version ------------------- The development version can be installed directly from github via ``pip``: -:: - $ pip install git+https://github.com/choderalab/pymbar.git +.. code-block:: console + + $ pip install git+https://github.com/choderalab/pymbar.git@pymbar-3-lts Running the tests ================= @@ -42,5 +43,6 @@ The test suite uses `pytest `_, in ad You can then run the tests with: -:: +.. code-block:: console + $ pytest -vv pymbar diff --git a/docs/index.rst b/docs/index.rst index 59e7c683..aa4caf2a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,8 +18,8 @@ Documentation getting_started mbar timeseries - testsystems - references + utils + zbibliography Indices and tables ================== diff --git a/docs/mbar.rst b/docs/mbar.rst index 7572a7a0..feccb966 100644 --- a/docs/mbar.rst +++ b/docs/mbar.rst @@ -5,4 +5,5 @@ The :mod:`mbar` module: :class:`MBAR` The :mod:`mbar` module contains the :class:`MBAR` class, which implements the `multistate Bennett acceptance ratio (MBAR) `_ method :cite:`shirts-chodera:jcp:2008:mbar`. -.. automodule:: pymbar.mbar +.. autoclass:: pymbar.MBAR + :members: diff --git a/docs/testsystems.rst b/docs/testsystems.rst index 9c2e419f..c26d5103 100644 --- a/docs/testsystems.rst +++ b/docs/testsystems.rst @@ -12,4 +12,3 @@ These test systems are also convenient to use if you want to easily generate syn .. automodule:: pymbar.testsystems.timeseries .. automodule:: pymbar.testsystems.exponential_distributions .. automodule:: pymbar.testsystems.gaussian_work -.. automodule:: pymbar.testsystems.pymbar_datasets diff --git a/docs/timeseries.rst b/docs/timeseries.rst index e21a0ba6..13eca542 100644 --- a/docs/timeseries.rst +++ b/docs/timeseries.rst @@ -67,3 +67,4 @@ A number of other useful functions for computing autocorrelation functions from same process are also provided. .. automodule:: pymbar.timeseries + :members: diff --git a/docs/utils.rst b/docs/utils.rst index 143dc691..a0613b2b 100644 --- a/docs/utils.rst +++ b/docs/utils.rst @@ -6,3 +6,4 @@ Utilities : :mod:`pymbar.utils` These functions are some miscellaneous functions used by other parts of the ``pymbar`` library. .. automodule:: pymbar.utils + :members: diff --git a/pymbar/mbar.py b/pymbar/mbar.py index e414ea5e..5f9f9da2 100644 --- a/pymbar/mbar.py +++ b/pymbar/mbar.py @@ -330,12 +330,12 @@ def __init__(self, u_kn, N_k, maximum_iterations=10000, relative_tolerance=1.0e- # pick new random ones of these K. new_kindices = k_indices[np.random.randint(int(N_k[k]), size=int(N_k[k]))] rinit[k_indices] = new_kindices - + self.f_k_boots[b,:] = mbar_solvers.solve_mbar_for_all_states(self.u_kn[:,rinit], self.N_k, f_k_init, solver_protocol, solver_tolerance) if verbose: if b%10==0: - print("Calculated {:d}/{:d} bootstrap samples".format(b,self.nbootstraps)) - + print("Calculated {:d}/{:d} bootstrap samples".format(b,self.nbootstraps)) + self.Log_W_nk = mbar_solvers.mbar_log_W_nk(self.u_kn, self.N_k, self.f_k) # Print final dimensionless free energies. @@ -688,7 +688,7 @@ def computeExpectationsInner(self, A_n, u_ln, state_map, >>> results = mbar.computeExpectationsInner(A_n, u_n, state_map) """ - + logfactor = 4.0 * np.finfo(np.float64).eps # make sure all results are larger than this number. # We tried 1 before, but expecations that are all very small (like @@ -1115,9 +1115,9 @@ def computeMultipleExpectations(self, A_in, u_n, compute_uncertainty=True, compu which is the energy of the n samples evaluated at a the chosen state. - + Parameters: - ------------- + ----------- A_in : np.ndarray, float, shape=(I, k, N) A_in[i,n] = A_i(x_n), the value of phase observable i for configuration n at state of interest @@ -1136,7 +1136,7 @@ def computeMultipleExpectations(self, A_in, u_n, compute_uncertainty=True, compu If true, return is a dictionary, else its a tuple Returns - ------------- + ------- 'mu' : np.ndarray, float, shape=(I) result_vals['mu'] is the estimate for the expectation of A_i(x) at the state specified by u_kn If return_dict, key will be 'mu'