cctk.Ensemble¶
- class cctk.Ensemble(name=None)[source]¶
Bases:
object
Class representing a collection of molecules. They do not all need to have the same atoms or bonds.
Ensembles are composed of molecules and properties. Molecules are
Molecule
objects, whereas properties aredict
objects containing calculation-specific information.There are various shortcuts for handling
Ensemble
objects:ensemble[molecule]
orensemble[0]
will return newEnsemble
objects with only the specified molecules.Lists or slices can also be used: so
ensemble[0:10:2]
orensemble[[molecule1, molecule2, molecule3]]
will also return newEnsemble
objects.
- Individual properties can be read through tuple indexing:
ensemble[0,"energy"]
will return the energy of the first molecule, while
ensemble[:,"energy"]
will return a list of all the energies.
- Individual properties can be read through tuple indexing:
To access
Molecule
objects, useensemble.molecule
:ensemble.molecule[0]
will return the first object, whereasensemble.molecule[1:3]
will return a list.ensemble.items()
will return a list of (molecule, property) pairs.ensemble.molecule_list()
andensemble.properties_list()
return lists of molecules and properties, respectively.
- name¶
name, for identification
- Type:
str
- _items¶
keys:
Molecule
objects; values: dictionaries containing properties from each molecule, variable. should always be one layer deep.- Type:
dict
- molecules¶
special object that accesses the keys
- Type:
MoleculeIndexer
Methods
__init__
([name])Create new instance.
add_molecule
(molecule[, properties, copy])Adds a molecule to the ensemble.
Returns a dictionary containing the most up-to-date version of each property.
get_properties_dict
(idx)Returns the dictionary of molecule properties for the specified molecule.
get_property
(idx, prop)has_property
(idx, prop)Returns
True
if property is defined for indexidx
andFalse
otherwise.items
()Returns a list of (molecule, properties) tuple pairs.
join_ensembles
(ensembles[, name])Creates a new Ensemble object from existing ensembles.
keys
()lowest_molecules
(property_name[, num])Retrieves the molecules with the lowest values of the specified property.
Returns a list of the constituent molecules.
properties
([num])Returns a list of the constituent properties.
Returns a list of dictionaries.
sort_by
(property_name[, ascending])Sorts the ensemble by the specified property.
values
()- add_molecule(molecule, properties=None, copy=False)[source]¶
Adds a molecule to the ensemble.
- Parameters:
molecule (Molecule) – the molecule to be added
properties (dict) – property name (str) to property value
copy (bool) – whether to store an independent copy of the molecule
- combined_properties()[source]¶
Returns a dictionary containing the most up-to-date version of each property.
- get_properties_dict(idx)[source]¶
Returns the dictionary of molecule properties for the specified molecule.
- Parameters:
idx (int or cctk.Molecule) – a molecule belonging to this ensemble, either 0-indexed or given explicitly as a Molecule
- Returns:
the property dict corresponding to this Molecule
- has_property(idx, prop)[source]¶
Returns
True
if property is defined for indexidx
andFalse
otherwise.
- classmethod join_ensembles(ensembles, name=None)[source]¶
Creates a new Ensemble object from existing ensembles.
If every ensemble has energies defined, then the new ensemble will have energies defined too.
- Parameters:
name (str) – name of Ensemble created
ensembles (list of Ensembles) – Ensemble objects to join
- lowest_molecules(property_name, num=1)[source]¶
Retrieves the molecules with the lowest values of the specified property.
- Parameters:
property_name (str) – the name of the property to sort on
num (int) – how many molecules to return
- Returns:
lowest
Molecule
(if num==1)list
ofMolecule
(otherwise)
- properties_list()[source]¶
Returns a list of dictionaries. One dictionary per geometry. Each dictionary contains the property names and property values for each geometry in the ensemble.
- sort_by(property_name, ascending=True)[source]¶
Sorts the ensemble by the specified property. Throws an error if the property is missing for any entries. Consistent, sort-compatible property values are assumed and not checked.
- Parameters:
property_name (str) – the name of the property to sort on (must be a string or number)
ascending (bool) – whether the property should increase or decrease in value
- Returns:
new Ensemble (current ensemble is not modified)