developing back end run methods

CHANGES

@@ -5,7 +5,26 @@ CHANGES for MDPOW
 Add summary of changes for each release. Use ISO 8061 dates. Reference
 GitHub issues numbers and PR numbers.
 
+2022-12-07    0.8.1
+cadeduckworth
 
+Changes
+
+* for ensemble.EnsembleAnalysis._single_frame() 
+  changed 'pass' to 'raise NotImplementedError' (#216)
+* for ensemble.EnsembleAnalysis._single_universe() 
+  changed 'pass' to 'raise NotImplementedError' (#216)
+* for ensemble.EnsembleAnalysis.run() changed to detect 
+  and use _single_frame OR _single_universe (#216)
+* _prepare_universe and _conclude_universe removed from 
+  EnsembleAnalysis.run() method, no longer needed (per comments, #199)
+* defined new test for updated ensemble.EnsembleAnalysis.run() method (#216):
+  - new test, test_ensemble_analysis_run(), uses TestAnalysis class, 
+    is in test_ensemble.py
+  - new test checks that NotImplementedError is raised when _single_frame 
+    or _single_universe are not defined, to implement correct method
+* source and html docs updated for EnsembleAnalysis
+  to reflect changes and describe proper usage
 
 2022-??-??    0.8.1
 cadeduckworth, orbeckst, VOD555

doc/sphinx/source/analysis/ensemble_analysis.txt

@@ -15,10 +15,17 @@ Universes and be analyzed as a group.
 
 :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
+iterates over the systems in the ensemble or the frames in the systems. It sets up iterations between
+universes or universe frames allowing for analysis to be run on either whole systems or the frames of those
 systems. This allows for users to easily run analyses on MDPOW simulations.
 
+NotImplementedError will detect whether _single_universe or _single_frame
+should be implemented, based on which is defined in the EnsembleAnalysisClass.
+Only one of the two methods should be defined for an EnsembleAnalysisClass. 
+For verbose functionality, the analysis may show two iteration bars, 
+where only one of which will actually be iterated, while the other will 
+load to completion instantaneously, showing the system that is being worked on.
+
 .. autoclass:: mdpow.analysis.ensemble.EnsembleAnalysis
     :members:
 

mdpow/analysis/dihedral.py

@@ -78,7 +78,7 @@ def check_dihedral_inputs(selections):
         for group in selections:
             for k in group.keys():
                 if len(group[k]) != 4:
-                    msg = ''''Dihedral calculations require AtomGroups with
+                    msg = '''Dihedral calculations require AtomGroups with
                               only 4 atoms, %s selected''' % len(group)
                     logger.error(msg)
                     raise SelectionError(msg)

mdpow/analysis/ensemble.py

@@ -466,17 +466,25 @@ def _setup_frames(self, trajectory):
     def _single_universe(self):
         """Calculations on a single Universe object.
 
-            Run on each universe in the ensemble during when
-            self.run in called.
+           Run on each universe in the ensemble during when
+           self.run in called.
+
+           NotImplementedError will detect whether _single_universe
+           or _single_frame should be implemented, based on which 
+           is defined in the EnsembleAnalysisClass.
         """
-        pass  # pragma: no cover
+        raise NotImplementedError
 
     def _single_frame(self):
-        """Calculate data from a single frame of trajectory
+        """Calculate data from a single frame of trajectory.
 
-        Called on each frame for universes in the Ensemble.
+           Called on each frame for universes in the Ensemble.
+
+           NotImplementedError will detect whether _single_universe
+           or _single_frame should be implemented, based on which 
+           is defined in the EnsembleAnalysisClass.
         """
-        pass  # pragma: no cover
+        raise NotImplementedError
 
     def _prepare_ensemble(self):
         """For establishing data structures used in running
@@ -505,27 +513,27 @@ def _conclude_ensemble(self):
         pass  # pragma: no cover
 
     def run(self, start=None, stop=None, step=None):
-        """Runs _single_universe on each system and _single_frame
+        """Runs _single_universe on each system or _single_frame
         on each frame in the system.
 
         First iterates through keys of ensemble, then runs _setup_system
-        which defines the system and trajectory. Then iterates over
-        trajectory frames.
+        which defines the system and trajectory. Then iterates over each
+        system universe or trajectory frames of each universe as defined.
         """
         logger.info("Setting up systems")
         self._prepare_ensemble()
         for self._key in ProgressBar(self._ensemble.keys(), verbose=True):
             self._setup_system(self._key, start=start, stop=stop, step=step)
-            self._prepare_universe()
-            self._single_universe()
-            for i, ts in enumerate(ProgressBar(self._trajectory[self.start:self.stop:self.step], verbose=True,
+            try:
+                self._single_universe()
+            except NotImplementedError:
+                for i, ts in enumerate(ProgressBar(self._trajectory[self.start:self.stop:self.step], verbose=True,
                                                postfix=f'running system {self._key}')):
-                self._frame_index = i
-                self._ts = ts
-                self.frames[i] = ts.frame
-                self.times[i] = ts.time
-                self._single_frame()
-            self._conclude_universe()
+                    self._frame_index = i
+                    self._ts = ts
+                    self.frames[i] = ts.frame
+                    self.times[i] = ts.time
+                    self._single_frame()
             logger.info("Moving to next universe")
         logger.info("Finishing up")
         self._conclude_ensemble()

mdpow/tests/test_dihedral.py

@@ -93,3 +93,8 @@ def test_ValueError_different_ensemble(self):
                            match='Dihedral selections from different Ensembles, '):
             DihedralAnalysis([dh1, dh2])
 
+    def test_single_universe(self):
+        dh = self.Ens.select_atoms('name C4', 'name C17', 'name S2', 'name N3')
+        with pytest.raises(NotImplementedError):
+            DihedralAnalysis([dh])._single_universe()
+

mdpow/tests/test_ensemble.py

@@ -149,6 +149,21 @@ def _conclude_universe(self):
         TestRun = TestAnalysis(Sim).run(start=0, step=1, stop=10)
         assert Sim.keys() == TestRun.key_list
 
+    def test_ensemble_analysis_run(self):
+        class TestAnalysis(EnsembleAnalysis):
+            def __init__(self, test_ensemble):
+                super(TestAnalysis, self).__init__(test_ensemble)
+
+            def test_single_frame(self):
+                with pytest.raises(NotImplementedError) as excinfo:
+                    TestAnalysis._single_frame(self)
+                assert excinfo.type == 'NotImplementedError'
+
+            def test_single_universe(self):
+                with pytest.raises(NotImplementedError) as excinfo:
+                    TestAnalysis._single_universe(self)
+                assert excinfo.type == 'NotImplementedError'
+
     def test_value_error(self):
         ens = Ensemble(dirname=self.tmpdir.name, solvents=['water'])
         copy_ens = Ensemble()