cctk.Ensemble

class cctk.Ensemble(name=None)

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 are dict objects containing calculation-specific information.

There are various shortcuts for handling Ensemble objects:

• ensemble[molecule] or ensemble[0] will return new Ensemble objects with only the specified molecules.

  Lists or slices can also be used: so ensemble[0:10:2] or ensemble[[molecule1, molecule2, molecule3]] will also return new Ensemble 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.

• To access Molecule objects, use ensemble.molecule: ensemble.molecule[0] will return the first object, whereas ensemble.molecule[1:3] will return a list.

• ensemble.items() will return a list of (molecule, property) pairs.

• ensemble.molecule_list() and ensemble.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

__init__(name=None)

Create new instance.

Parameters:

name (str) – name of Ensemble

Methods

__init__([name])	Create new instance.
add_molecule(molecule[, properties, copy])	Adds a molecule to the ensemble.
combined_properties()	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 index idx and False 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.
molecule_list()	Returns a list of the constituent molecules.
properties([num])	Returns a list of the constituent properties.
properties_list()	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)

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

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.

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

get_property(idx, prop)

has_property(idx, prop)

Returns True if property is defined for index idx and False otherwise.

items()

Returns a list of (molecule, properties) tuple pairs.

classmethod join_ensembles(ensembles, name=None)

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

keys()

lowest_molecules(property_name, num=1)

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 of Molecule (otherwise)

molecule_list()

Returns a list of the constituent molecules.

properties(num=None)

Returns a list of the constituent properties.

properties_list()

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)

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)

values()