.. _ensemble-objects:

================
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:
