Add Ensemble Objects (#179)

* new Ensemble framework for aggregate analysis in mdpow.analysis
* part of #168 (adding analysis to MDPOW)
* new submodule mdpow.analysis
* new Ensemble, EnsembleAtomGroup, and EnsembleAnalysis classes
* add docs (new section on Analysis)
* add tests including ensemble test data (water simulations, octanol to be added later)
* update CHANGES

CHANGES

@@ -21,6 +21,9 @@ Enhancements
 * 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 (PR #179)
+* new EnsembleAnalysis framework for collecting data from MDPOW simulations (PR #179)
 
 
 Fixes

doc/sphinx/source/analysis.txt

@@ -0,0 +1,19 @@
+==================
+Analysis Submodule
+==================
+
+.. 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 :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.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   analysis/ensemble
+   analysis/ensemble_analysis

doc/sphinx/source/analysis/ensemble.txt

@@ -0,0 +1,45 @@
+================
+Ensemble Objects
+================
+
+.. versionadded:: 0.8.0
+
+Ensemble
+________
+
+The :class:`~mdpow.analysis.ensemble.Ensemble` object is a collection
+of :class:`MDAnalysis.Universe <MDAnalysis.core.groups.universe.Universe>` objects.
+It is intended to store the set of systems generated by running :program:`mdpow-fep`.
+
+The :class:`~mdpow.analysis.ensemble.Ensemble` object works by storing the
+systems in a dictionary and extending the functionality of an
+:class:`MDAnalysis.Universe <MDAnalysis.core.groups.universe.Universe>` to a collection
+of universes. It when given a directory finds the simulation files, reads then loads
+them into a dictionary. The object can be indexed the same as a dictionary,
+and has methods analogous the the :class:`MDAnalysis.Universe <MDAnalysis.core.groups.universe.Universe>` object. The main
+one being :meth:`~mdpow.analysis.ensemble.Ensemble.select_atoms` which returns a
+:class:`~mdpow.analysis.ensemble.EnsembleAtomGroup` .
+An :class:`~mdpow.analysis.ensemble.Ensemble` in its current form
+can also be built by manually adding and popping universes into an empty instance.
+
+.. autoclass:: mdpow.analysis.ensemble.Ensemble
+    :members:
+
+    .. automethod:: _build_ensemble
+
+    .. automethod:: _load_universe_from_dir
+
+EnsembleAtomGroup
+_________________
+
+The :class:`~mdpow.analysis.ensemble.EnsembleAtomGroup` is created by running
+the  on an :class:`~mdpow.analysis.ensemble.Ensemble`
+:meth:`~mdpow.analysis.ensemble.Ensemble.select_atoms`. It stores
+:class:`MDAnalysis.AtomGroup <MDAnalysis.core.groups.AtomGroup>` selections of the groups
+generated by running select atom on individual universes in a dictionary with
+the same key structure as the parent :class:`~mdpow.analysis.ensemble.Ensemble`
+class. It returns a copy of the parent :class:`~mdpow.analysis.ensemble.Ensemble`
+object when the :meth:`~mdpow.analysis.ensemble.EnsembleAtomGroup.ensemble` is run.
+
+.. autoclass:: mdpow.analysis.ensemble.EnsembleAtomGroup
+    :members:

doc/sphinx/source/analysis/ensemble_analysis.txt

@@ -0,0 +1,39 @@
+============================
+ Ensemble Analysis Framework
+============================
+
+.. 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
+systems to be loaded into `MDAnalysis <https://mdanalysis.org>`_
+Universes and be analyzed as a group.
+
+Ensemble Analysis Framework
+===========================
+
+EnsembleAnalysis
+----------------
+
+:class:`~mdpow.analysis.ensemble.EnsembleAnalysis` is a class inspired by the
+:class:`AnalysisBase <MDAnalysis.analysis.base.AnalysisBase>` from MDAnalysis which
+iterates over the systems in the ensemble and the frames in the systems. It sets up both iterations between
+universes and universe frames allowing for analysis to be run on both whole systems and the frames of those
+systems. This allows for users to easily run analyses on MDPOW simulations.
+
+.. autoclass:: mdpow.analysis.ensemble.EnsembleAnalysis
+    :members:
+
+    .. automethod:: _prepare_ensemble
+
+    .. automethod:: _prepare_universe
+
+    .. automethod:: _single_universe
+
+    .. automethod:: _single_frame
+
+    .. automethod:: _conclude_ensemble
+
+    .. automethod:: _conclude_universe

doc/sphinx/source/index.txt

@@ -141,7 +141,7 @@ For current issues and open feature requests please look through the
    fep
    utilities
    forcefields
-
+   analysis
 
 .. rubric:: Indices and tables
 

mdpow/analysis/__init__.py

@@ -0,0 +1,2 @@
+# Analysis Subpackage
+# Alia Lescoulie (ALescoulie) 2021