cctk.ConformationalEnsemble

class cctk.ConformationalEnsemble(name=None)

Bases: Ensemble

Class that representing a group of conformers. All members must have the same atom types in the same order.

__init__(name=None)

Create new instance.

Parameters:

name (str) – name of Ensemble

Methods

__init__([name])	Create new instance.
add_molecule(molecule[, properties, copy, ...])	Checks that the molecule contains the same atom types in the same order as existing molecules, and that the molecule has the same charge/multiplicity.
align([to_geometry, comparison_atoms, ...])	Aligns every geometry in this ensemble to the specified geometry, optionally computing the root-mean-square distance between each geometry and the reference geometry.
assign_connectivity([index])	Assigns connectivity for all molecules based on molecule of index index.
boltzmann_average(which[, energies, temp, ...])	Computes the Boltzmann-weighted average of a property over the whole ensemble.
combined_properties()	Returns a dictionary containing the most up-to-date version of each property.
eliminate_redundant([RMSD_cutoff, ...])	Aligns every geometry in this ensemble and then creates a new ensemble that contains only the non-redundant conformers.
get_geometric_parameters(parameter, atom1, atom2)	Computes and outputs geometric parameters (bond distances, angles, or dihedral angles) for every member of self.molecules.
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, copy])	Creates a new ConformationalEnsemble 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, checks=True)

Checks that the molecule contains the same atom types in the same order as existing molecules, and that the molecule has the same charge/multiplicity.

align(to_geometry=0, comparison_atoms='heavy', compute_RMSD=False)

Aligns every geometry in this ensemble to the specified geometry, optionally computing the root-mean-square distance between each geometry and the reference geometry.

Alignments are based on atom_numbers. The current ensemble will not be altered. RMSDs will be calculated over the comparison atoms only.

Parameters:

• to_geometry (int) – the reference geometry to align to (0-indexed)

• comparison_atoms (str or list) – which atoms to use when computing alignments “heavy” for all non-hydrogen atoms, “all” for all atoms, or a list of 1-indexed atom numbers

• compute_RMSD (Bool) – whether to return RMSD before and after rotation

Returns:

new aligned ConformationalEnsemble or new aligned ConformationalEnsemble, before_RMSD array, after_RMSD array

assign_connectivity(index=0)

Assigns connectivity for all molecules based on molecule of index index. Much faster than assigning connectivity for each individually – but assumes all bonding is the same.

boltzmann_average(which, energies=None, temp=298, energy_unit='hartree', return_weights=False)

Computes the Boltzmann-weighted average of a property over the whole ensemble.

Parameters:

• which (str) – which property to compute

• energy (np.ndarray) – list of energies to use for weighting. Will default to self[:,"energy"], although other strings can be passed as well as shorthand for self[:,energy].

• temp (float) – temperature for Boltzmann-weighting, in K

• energy_unit (str) – either kcal_mol or hartree

• return_weights (bool) – whether to return a list of weights too

Returns:

weighted property, of the same shape as the individual property

combined_properties()

Returns a dictionary containing the most up-to-date version of each property.

eliminate_redundant(RMSD_cutoff=0.5, comparison_atoms='heavy', return_RMSD=False)

Aligns every geometry in this ensemble and then creates a new ensemble that contains only the non-redundant conformers. If energies are available, the lowest energy conformer will be kept for every redundancy. The current ensemble will not be modified. The resulting ensemble will be sorted by energy (if available).

Parameters:

• RMSD_cutoff (float) – remove conformers that are more similar than this threshold

• to_geometry (int) – the reference geometry to align to (0-indexed)

• comparison_atoms (str or list) – which atoms to use when computing alignments “heavy” for all non-hydrogen atoms, “all” for all atoms, or a list of 1-indexed atom numbers

• return_RMSD (bool) – whether or not to return list of RMSD values

Returns:

new ConformationalEnsemble, RMSDs to the reference geometry

get_geometric_parameters(parameter, atom1, atom2, atom3=None, atom4=None)

Computes and outputs geometric parameters (bond distances, angles, or dihedral angles) for every member of self.molecules.

Parameters:

• parameter (str) – one of angle, distance, or dihedral

• atom1 (int) – number of the atom in question

• atom2 (int) – same, but for the second atom

• atom3 (int) – same, but for the third atom (only required for parameter angle or dihedral)

• atom4 (int) – same, but for the fourth atom (only required for parameter dihedral)

Returns:

a list of the specified parameter’s values for each geometry

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, copy=False)

Creates a new ConformationalEnsemble object from existing ensembles. Both molecules and properties are copied.

Parameters:

• name (str) – name of ConformationalEnsemble created

• ensembles (list of ConformationalEnsembles) – ConformationalEnsemble objects to join

• copy (bool) – whether to make copies of the component molecules

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