diff --git a/CHANGES b/CHANGES index 4f943f76..6174dd28 100644 --- a/CHANGES +++ b/CHANGES @@ -5,7 +5,7 @@ CHANGES for MDPOW Add summary of changes for each release. Use ISO dates. Reference GitHub issues numbers and PR numbers. -2021-??-?? 0.8.0 +2021-12-29 0.8.0 ALescoulie, orbeckst Changes @@ -18,18 +18,17 @@ Changes Enhancements +* new Ensemble and EnsembleAtomGroup objects for loading set of system + simulations (issue #168, PR #179) +* new EnsembleAnalysis framework for collecting data from MDPOW simulations + (issue #168, PR #179) +* new EnsembleAnalysis: dihedrals (#190, PR #193) +* new EnsembleAnalysis: solvation shell (#195, PR #196) * new exception config.NoSectionError to indicate missing section ("protocol") in the YAML run input file (PR #187) * new config.NoOptionWarning when undefined options are used (with default None) and POWConfigParser.get() now logs when an option is used at level DEBUG (PR #187) -* new Ensemble and EnsembleAtomGroup objects for loading set of system - simulations (issue #168, PR #179) -* new EnsembleAnalysis framework for collecting data from MDPOW simulations - (issue #168, PR #179) -* new SolvationAnalysis for quantifing the number of solvent molecules - within a given distance (#195) - Fixes diff --git a/doc/sphinx/source/analysis.txt b/doc/sphinx/source/analysis.txt index ff547e70..648249c5 100644 --- a/doc/sphinx/source/analysis.txt +++ b/doc/sphinx/source/analysis.txt @@ -1,21 +1,59 @@ -================== -Analysis Submodule -================== +======== +Analysis +======== .. versionadded:: 0.8.0 -MDPOW module for analyzing simulations. The :doc:`analysis/ensemble` objects -and :doc:`analysis/ensemble_analysis` allow for the construction the simplified of analyses. +The :mod:`mdpow.analysis` module contains tools for analyzing whole +sets (ensembles) of FEP simulations and a framework to write new +analysis tools [Lescoulie2021]_. -The :doc:`analysis/ensemble` and :doc:`analysis/ensemble_analysis` sections -assumes a basic understanding of object oriented programming in python and -are for users who wish to construct their own analyses. +.. _tools: +Analysis tools +-------------- + +MDPOW analysis tools are based on the :ref:`framework`. They generally +take as an input the top level directory of a complete FEP run and +then collect individual simulations and run a specific analysis over +all FEP simulations. They then make data available (typically, as a +:class:`pandas.DataFrame`). .. toctree:: :maxdepth: 1 - analysis/ensemble - analysis/ensemble_analysis analysis/solvation - analysis/dihedral \ No newline at end of file + analysis/dihedral + + +.. _framework: + +Ensemble Analysis Framework +--------------------------- + +The *Ensemble Analysis framework* [Lescoulie2021]_ allows for the +construction analysis tools that work with whole sets (ensembles) of +FEP simulations. They generally follow (and can use) standard +MDAnalysis analysis classes. + +The :ref:`ensemble-objects` and :ref:`ensembleanalysis-base` sections +assume a basic understanding of object oriented programming in Python +and are for users who wish to construct their own analyses. The code +in the :ref:`tools` serves as example implementations and is described +in more detail in [Lescoulie2021]_. + +.. toctree:: + :maxdepth: 1 + + analysis/ensemble_analysis + analysis/ensemble + + +References +---------- +.. [Lescoulie2021] A. Lescoulie, "SPIDAL Summer REU 2021: Upgrading MDPOW and + adding analysis functionality," Technical Report, Arizona + State University, Tempe, AZ, 2021. doi: + `10.6084/m9.figshare.17156018`_ + +.. _`10.6084/m9.figshare.17156018`: https://doi.org/10.6084/m9.figshare.17156018 diff --git a/doc/sphinx/source/analysis/dihedral.txt b/doc/sphinx/source/analysis/dihedral.txt index 3ea936f4..81e7f6e1 100644 --- a/doc/sphinx/source/analysis/dihedral.txt +++ b/doc/sphinx/source/analysis/dihedral.txt @@ -2,8 +2,9 @@ Dihedral Analysis ================= -Analyzes selected dihedral angles over a multi-system simulation. Built using the :doc:`analysis/ensemble_analysis` -Framework to run over a collection of systems contained in an :class:`~mdpow.analysis.ensemble.Ensemble` . +Analyzes selected dihedral angles over a multi-system +simulation. Built using the :ref:`framwework` to run over a collection +of systems contained in an :class:`~mdpow.analysis.ensemble.Ensemble`. .. versionadded:: 0.8.0 diff --git a/doc/sphinx/source/analysis/ensemble.txt b/doc/sphinx/source/analysis/ensemble.txt index 50f6122f..fd4f9bce 100644 --- a/doc/sphinx/source/analysis/ensemble.txt +++ b/doc/sphinx/source/analysis/ensemble.txt @@ -1,3 +1,5 @@ +.. _ensemble-objects: + ================ Ensemble Objects ================ @@ -5,7 +7,7 @@ Ensemble Objects .. versionadded:: 0.8.0 Ensemble -________ +-------- The :class:`~mdpow.analysis.ensemble.Ensemble` object is a collection of :class:`MDAnalysis.Universe ` objects. @@ -30,7 +32,7 @@ can also be built by manually adding and popping universes into an empty instanc .. automethod:: _load_universe_from_dir EnsembleAtomGroup -_________________ +----------------- The :class:`~mdpow.analysis.ensemble.EnsembleAtomGroup` is created by running the on an :class:`~mdpow.analysis.ensemble.Ensemble` diff --git a/doc/sphinx/source/analysis/ensemble_analysis.txt b/doc/sphinx/source/analysis/ensemble_analysis.txt index fcac17b7..67c6bc21 100644 --- a/doc/sphinx/source/analysis/ensemble_analysis.txt +++ b/doc/sphinx/source/analysis/ensemble_analysis.txt @@ -1,22 +1,18 @@ -============================ - Ensemble Analysis Framework -============================ +.. _ensembleanalysis-base: + +============================== + Ensemble Analysis base class +============================== .. versionadded:: 0.8.0 The Analysis modules help in the implementation analyses of MDPOW simulations. To simplify the process of analyzing a collection of systems generated by a free energy simulation -the objects in :doc:`analysis/ensemble` allow for a molecule directory's +the objects in :ref:`ensemble-objects` allow for a molecule directory's systems to be loaded into `MDAnalysis `_ Universes and be analyzed as a group. -Ensemble Analysis Framework -=========================== - -EnsembleAnalysis ----------------- - :class:`~mdpow.analysis.ensemble.EnsembleAnalysis` is a class inspired by the :class:`AnalysisBase ` from MDAnalysis which iterates over the systems in the ensemble and the frames in the systems. It sets up both iterations between diff --git a/doc/sphinx/source/analysis/solvation.txt b/doc/sphinx/source/analysis/solvation.txt index 5e7a2127..c011efb1 100644 --- a/doc/sphinx/source/analysis/solvation.txt +++ b/doc/sphinx/source/analysis/solvation.txt @@ -2,11 +2,12 @@ Solvation Shell Analysis ======================== -Analyzes the number of solvent molecules within given distances of the solute. +Analyzes the number of solvent molecules within given distances of the +solute. The solvation tool is built with the :ref:`framwework`. .. versionadded:: 0.8.0 .. autoclass:: mdpow.analysis.solvation.SolvationAnalysis :members: - .. automethod:: run \ No newline at end of file + .. automethod:: run diff --git a/doc/sphinx/source/index.txt b/doc/sphinx/source/index.txt index cbcada9d..24864c28 100644 --- a/doc/sphinx/source/index.txt +++ b/doc/sphinx/source/index.txt @@ -139,9 +139,9 @@ For current issues and open feature requests please look through the scripts equil fep + analysis utilities forcefields - analysis .. rubric:: Indices and tables