4.2.2. Ensemble Objects

Added in version 0.8.0.

4.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)

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 in dirname argument directory when creating an Ensemble .

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']

Added in version 0.8.0.

_build_ensemble()

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) → Universe | None

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 the dirname argument.

add_system(key, universe: Universe)

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.

keys()

Returns list of system keys

pop(key)

Removes and returns system at specified key.

Logs if KeyError is raised.

select_atoms(*args, **kwargs)

Returns EnsembleAtomGroup containing selections from the Ensemble

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)

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])

4.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: Ensemble)

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.

property ensemble

Returns the ensemble of the EnsembleAtomGroup

keys()

List of keys to specific atom groups in the system

positions(keys=None)

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)

Returns EnsembleAtomGroup containing selections from the EnsembleAtomGroup

Uses the same selection commands as MDAnalysis, and has the same keys as EnsembleAtomGroup