6.2.2. Ensemble Objects¶
New in version 0.8.0.
6.2.2.1. Ensemble¶
The Ensemble
object is a collection
of MDAnalysis.Universe
objects.
It is intended to store the set of systems generated by running mdpow-fep.
The Ensemble
object works by storing the
systems in a dictionary and extending the functionality of an
MDAnalysis.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 MDAnalysis.Universe
object. The main
one being select_atoms()
which returns a
EnsembleAtomGroup
.
An Ensemble
in its current form
can also be built by manually adding and popping universes into an empty instance.
-
class
mdpow.analysis.ensemble.
Ensemble
(dirname=None, solvents=('octanol', 'water'), topology_paths=None, interactions=('Coulomb', 'VDW'), **universe_kwargs)[source]¶ Collection of related
MDAnalysis.Universe
objects.Stores systems produced by running mdpow-fep organized by solvent, interaction, and lambda.
Given a mdpow simulation directory will load the MD simulation files with the directory structure as keys.
Keywords: - dirname
- Molecule Simulation directory. Loads simulation files present in
lambda directories into the new instance. With this method for
generating an
Ensemble
the lambda directories are explored and_load_universe_from_dir()
searches for .gro, .gro.b2z, .gro.gz, and .tpr files for topology, and .xtc files for trajectory. It will default to using the tpr file available. - solvents
- Solvents from directory given to the new instance. Default
solvents=('water', 'octanol')
- topology_paths
- Specifies topologies used in loading simulated systems. Given with a dictionary with keys-value pair for each solvent and its respective topology path.
- interactions
- Interactions from directory given to the instance. Default
interactions=('Coulomb', 'VDW')
- universe_kwargs
- Keywords arguments
for loading
MDAnalysis.Universe
objects from MDPOW files indirname
argument directory when creating anEnsemble
.
Examples
Typical workflow for MDPOW directory:
ens = Ensemble(dirname='molecule')
Typical workflow for adding universes individually:
ens = Ensemble() u = mda.Universe(md.gro', 'md.xtc') ens.add_system(u)
Topology paths can be specified when defining the _ensemble by giving the paths to each solvent topology in a dictionary with the topology_paths argument:
ens = Ensemble(dirname='molecule', topology_paths={'water': water_path, 'octanol': octanol_path}
Interactions can also be specified when initializing the with a list using the interactions argument:
ens = Ensemble(dirname='molecule', interactions=['Coulomb']
New in version 0.8.0.
-
_build_ensemble
()[source]¶ Finds simulation files genderated by MDPOW and attempts to build
MDAnalysis.Universe
in the lambda directories.Run if
dirname
argument is given when initializing the class. First enters FEP directory, then traverses solvent and interaction directories to search lambda directories for system files.
-
static
_load_universe_from_dir
(solv_dir=None, **universe_kwargs) → Optional[MDAnalysis.core.universe.Universe][source]¶ Loads system simulation files in directory into an
MDAnalysis.Universe
If multiple topologies are found it will default to using the .tpr file. If more than one trajectory is present they will be sorted alphabetically and passed into the
MDAnalysis.Universe
This method is run automatically by_build_ensemble()
when initializing the class using thedirname
argument.
-
add_system
(key, universe: MDAnalysis.core.universe.Universe)[source]¶ Adds system from universe object for trajectory and topology files
Existing mda.Universe object or trajectory and topology path. Ensure that paths are set to absolute when creating the universe.
-
select_atoms
(*args, **kwargs)[source]¶ Returns
EnsembleAtomGroup
containing selections from theEnsemble
Uses the same selection commands as MDAnalysis, and has the same keys as the
Ensemble
-
select_systems
(keys=None, solvents=None, interactions=None, lambdas=None, lambda_range=None)[source]¶ Select specific subset of systems and returns them in an Ensemble.
This can be accomplished in two ways, by specific keys, or by specifying the desired system attributes solvents, interactions and lambdas. All arguments are stored in list form.
Keywords: - keys
- System keys from
Ensemble
to be returned. - solvents
- Solvents from
Ensemble
to be returned. - interactions
- Interactions from
Ensemble
to be returned - lambdas
- Specific lambdas to be returned
- lambda_range
- Range of lambda to be returned
Examples
Specific key workflow example:
Ens = Ensemble(dirname='Mol') w_v_0_25 = Ens.select_systems(keys=[('water', 'VDW', '0000'), ('water', 'VDW', '0025')]
For the system attributes workflow there are two ways of selecting lambdas, the :param lambdas: keyword saves specific lambdas or the :param lambda_range: which saves the lambdas that fall within the given range.
Specific lambdas example:
Ens = Ensemble(dirname='Mol') w_v_0_25 = Ens.select_systems(solvents=['water'], interactions=['VDW'], lambdas=['0000', '0025'])
Range of lambdas example:
Ens = Ensemble(dirname='Mol') w_v = Ens.select_systems(solvents=['water'], interactions=['VDW'], lambda_range=[0, 1])
6.2.2.2. EnsembleAtomGroup¶
The EnsembleAtomGroup
is created by running
the on an Ensemble
select_atoms()
. It stores
MDAnalysis.AtomGroup
selections of the groups
generated by running select atom on individual universes in a dictionary with
the same key structure as the parent Ensemble
class. It returns a copy of the parent Ensemble
object when the ensemble()
is run.
-
class
mdpow.analysis.ensemble.
EnsembleAtomGroup
(group_dict: dict, ensemble: mdpow.analysis.ensemble.Ensemble)[source]¶ - Group for storing selections from
Ensemble
- objects made using the
select_atoms()
method.
EnsembleAtomGroup
is not set up for manual initialization, they should be obtained by selecting atoms from an existing object.-
ensemble
¶ Returns the ensemble of the EnsembleAtomGroup
-
positions
(keys=None)[source]¶ Returns the positions of the keys of the selected atoms.
If no keys are specified positions for all keys are returned
-
select_atoms
(*args, **kwargs)[source]¶ Returns
EnsembleAtomGroup
containing selections from theEnsembleAtomGroup
Uses the same selection commands as MDAnalysis, and has the same keys as
EnsembleAtomGroup
- Group for storing selections from