From b40f6d65f01581fed8368f8e8d2452e0a748a4eb Mon Sep 17 00:00:00 2001 From: Oliver Beckstein Date: Mon, 3 Jan 2022 14:11:47 -0700 Subject: [PATCH] updated CHANGES and EnsembleAnalysis docs --- .github/workflows/ci.yaml | 20 +++---- CHANGES | 15 +++-- README.rst | 3 +- doc/sphinx/source/analysis.txt | 60 +++++++++++++++---- doc/sphinx/source/analysis/dihedral.txt | 5 +- doc/sphinx/source/analysis/ensemble.txt | 6 +- .../source/analysis/ensemble_analysis.txt | 16 ++--- doc/sphinx/source/analysis/solvation.txt | 5 +- doc/sphinx/source/index.txt | 2 +- 9 files changed, 85 insertions(+), 47 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index b0c1c4e6..55fcd022 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -24,24 +24,24 @@ jobs: matrix: # only test all GROMACS version on the oldest and latest # Python to keep the testing matrix manageable and only use 2 - # macos runners (latest GROMACS, oldes and latest Python) + # macos runners (latest GROMACS, oldest and latest Python) os: [ubuntu-latest] - python-version: [3.9] + python-version: ["3.9"] gromacs-version: ["4.6.5", "2018.6", "2020.6", "2021.1"] include: - os: ubuntu-latest - python-version: 3.6 - gromacs-version: 2021.1 + python-version: "3.6" + gromacs-version: "2021.1" - os: ubuntu-latest - python-version: 3.7 - gromacs-version: 2021.1 + python-version: "3.7" + gromacs-version: "2021.1" - os: ubuntu-latest - python-version: 3.8 - gromacs-version: 2021.1 + python-version: "3.8" + gromacs-version: "2021.1" - os: macos-latest - python-version: 3.9 - gromacs-version: 2021.1 + python-version: "3.9" + gromacs-version: "2021.1" env: MPLBACKEND: agg diff --git a/CHANGES b/CHANGES index 6147a57a..19dec6a8 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/README.rst b/README.rst index 2657250e..c82edd00 100644 --- a/README.rst +++ b/README.rst @@ -43,7 +43,8 @@ Documentation Installation ------------ -See `INSTALL`_ for detailed instructions. MDPOW currently supports Python 3.7 to 3.9. +See `INSTALL`_ for detailed instructions. MDPOW currently supports and +is tested with Python 3.7 to 3.9. You will also need `Gromacs`_ (currently tested with versions 4.6.5, 2018, 2020, 2021 but 2016 and 2019 should also work). 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