tesliper.glassware.conformers

A tesliper’s main data storage.

Classes

Conformers(*args[, ...])

Container for data extracted from quantum chemical software output files.

class tesliper.glassware.conformers.Conformers(*args, allow_data_inconsistency: bool = False, temperature_of_the_system: float = 298.15, **kwargs)[source]

Container for data extracted from quantum chemical software output files.

Data for each file is stored in the underlying OrderedDict, under the key of said file’s name. Its values are dictionaries with genres name (as key) and appropriate data pairs. Beside this, its essential functionality is transformation of stored data to corresponding DataArray objects with use of arrayed() method. It provides some control over this transformation, especially in terms of including/excluding particular conformers’ data on creation of new DataArray instance. This type of control is here called trimming. Trimming can be achieved by use of various trim methods defined in this class or by direct changes to kept attribute. See its documentation for more information.

primary_genres: Class attribute. Data genres considered most important, used as default when checking for conformers completeness (see trim_incomplete() method).

Notes

Inherits from collections.OrderedDict.

Parameters

*args – list of arguments for creation of underlying dictionary
allow_data_inconsistency (bool, optional) – specifies if data inconsistency should be allowed in created DataArray object instances, defaults to False
temperature_of_the_system (float, optional) – Temperature of the system in Kelvin units, must be zero or higher. Defaults to room temperature = 298.15 K.
**kwargs – list of arbitrary keyword arguments for creation of underlying dictionary

property temperature: float

Temperature of the system expressed in Kelvin units.

Value of this parameter is passed to data arrays created with the arrayed() method, provided that the target data array class supports a parameter named t in it’s constructor.

New in version 0.9.1.

Raises: ValueError – if set to a value lower than zero.

clear()[source]: Remove all items from the Conformers instance.

popitem(last=True)[source]

Remove and return a (key, value) pair from the dictionary.

Pairs are returned in LIFO order if last is true or FIFO order if false.

move_to_end(key, last=True)[source]

Move an existing element to the end (or beginning if last==False).

Raises KeyError if the element does not exist.

copy() → a shallow copy of conformers[source]

property kept

List of booleans, one for each conformer stored, defining if particular conformers data should be included in corresponding DataArray instance, created by arrayed() method. It may be changed by use of trim methods, by setting its value directly, or by modification of the underlying list. For the first option refer to those methods documentation, for rest see the Examples section.

Returns

List of booleans, one for each conformer stored, defining if particular conformers data should be included in corresponding DataArray instance.

Return type

list of bool

Raises

TypeError – If assigned values is not a sequence. If elements of given sequence are not one of types: bool, int, str.
ValuesError – If number of given boolean values doesn’t match number of contained conformers.
KeyError – If any of given string values is not in underlying dictionary keys.
IndexError – If any of given integer values is not in range 0 <= i < number of conformers.

Examples

New list of values can be set in a few ways. Firstly, it is the most straightforward to just assign a new list of boolean values to the kept attribute. This list should have the same number of elements as the number of conformers contained. A ValueError is raised if it doesn’t.

>>> c = Conformers(one={}, two={}, tree={})
>>> c.kept
[True, True, True]
>>> c.kept = [False, True, False]
>>> c.kept
[False, True, False]
>>> c.kept = [False, True, False, True]
Traceback (most recent call last):
...
ValueError: Must provide boolean value for each known conformer.
4 values provided, 3 excepted.

Secondly, list of filenames of conformers intended to be kept may be given. Only these conformers will be kept. If given filename is not in the underlying Conformers’ dictionary, KeyError is raised.

>>> c.kept = ['one']
>>> c.kept
[True, False, False]
>>>  c.kept = ['two', 'other']
Traceback (most recent call last):
...
KeyError: Unknown conformers: other.

Thirdly, list of integers representing conformers indices may be given. Only conformers with specified indices will be kept. If one of given integers can’t be translated to conformer’s index, IndexError is raised. Indexing with negative values is not supported currently.

>>> c.kept = [1, 2]
>>> c.kept
[False, True, True]
>>> c.kept = [2, 3]
Traceback (most recent call last):
...
IndexError: Indexes out of bounds: 3.

Fourthly, assigning True or False to this attribute will mark all conformers as kept or not kept respectively.

>>> c.kept = False
>>> c.kept
[False, False, False]
>>> c.kept = True
>>> c.kept
[True, True, True]

Lastly, list of kept values may be modified by setting its elements to True or False. It is advised against, however, as mistake such as c.kept[:2] = [True, False, False] will break some functionality by forcibly changing size of kept list.

Notes

Type of the first element of given sequence is used for dynamic dispatch.

update(other=None, **kwargs)[source]

Works like dict.update, but if key is already present, it updates dictionary associated with given key rather than assigning new value. Keys of dictionary passed as positional parameter (or additional keyword arguments given) should be conformers’ identifiers and its values should be dictionaries of {“genre”: values} for those conformers.

Please note, that values of status genres like ‘optimization_completed’ and ‘normal_termination’ will be updated as well for such key, if are present in given new values.

Lists requested data and returns as appropriate DataArray instance.

New in version 0.9.1: The strict parameter.

Parameters

genre – String representing data genre. Must be one of known genres.
full – Boolean indicating if full set of data should be taken, ignoring any trimming conducted earlier. Defaults to False.
strict – Boolean indicating if additional kwargs that doesn’t match signature of data array’s constructor should cause an exception as normally (strict = True) or be silently ignored (strict = False). Defaults to True.
kwargs – Additional keyword parameters passed to data array constructor. Any explicitly given parameters will take precedence over automatically retrieved and default values.

Returns

Arrayed data of desired genre as appropriate DataArray object.

Return type

DataArray

Notes

For now, the special “filenames” genre always ignores kwargs.

by_index(index: int) → dict[source]: Returns data for conformer on desired index.

key_of(index: int) → str[source]: Returns name of conformer associated with given index.

index_of(key: str) → int[source]: Return index of given key.

has_genre(genre: str, ignore_trimming: bool = False) → bool[source]

Checks if any of stored conformers contains data of given genre.

Parameters

genre (str) – Name of genre to test.
ignore_trimming (bool) – If all known conformers should be considered (ignore_trimming = True) or only kept ones (ignore_trimming = False, default).

Returns

Boolean value indicating if any of stored conformers contains data of genre in question.

Return type

bool

has_any_genre(genres: Iterable[str], ignore_trimming: bool = False) → bool[source]

Checks if any of stored conformers contains data of any of given genres.

Parameters

genres (iterable of str) – List of names of genres to test.
ignore_trimming (bool) – If all known conformers should be considered (ignore_trimming = True) or only kept ones (ignore_trimming = False, default).

Returns

Boolean value indicating if any of stored conformers contains data of any of genres in question.

Return type

bool

all_have_genres(genres: Iterable[str], ignore_trimming: bool = False) → bool[source]

Checks if all stored conformers contains data of given genres.

Parameters

genres (iterable of str) – List of names of genres to test.
ignore_trimming (bool) – If all known conformers should be considered (ignore_trimming = True) or only kept ones (ignore_trimming = False, default).

Returns

Boolean value indicating if each stored conformers contains data of all genres in question.

Return type

bool

trim_incomplete(wanted: Optional[Iterable[str]] = None, strict: bool = False) → None[source]

Mark incomplete conformers as “not kept”.

Conformers that does not contain one or more data genres specified as wanted will be marked as “not kept”. If wanted parameter is not given, it evaluates to primary_genres. If no conformer contains all wanted genres, conformers that match the specification most closely are kept. The “closeness” is defined by number of conformer’s genres matching wanted genres in the first place (the more, the better) and the position of particular genre in wanted list in the second place (the closer to the beginning, the better). This “match closest” behaviour may be turned off by setting parameter strict to True. In such case, only conformers containing all wanted genres will be kept.

Parameters

wanted – List of data genres used as completeness reference. If not given, evaluates to primary_genres.
strict – Indicates if all wanted genres must be present in the kept conformers (strict=True) or if “match closest” mechanism should be used as a fallback (strict=False, this is the default).

Notes

Conformers previously marked as “not kept” will not be affected.

trim_imaginary_frequencies() → None[source]

Mark all conformers with imaginary frequencies as “not kept”.

Notes

Conformers previously marked as “not kept” will not be affected. Conformers that doesn’t contain “freq” genre will be treated as not having imaginary frequencies.

trim_non_matching_stoichiometry(wanted: Optional[str] = None) → None[source]

Mark all conformers with stoichiometry other than wanted as “not kept”. If not given, wanted evaluates to the most common stoichiometry.

Parameters: wanted – Only conformers with same stoichiometry will be kept. Evaluates to the most common stoichiometry if not given.

Notes

Conformers previously marked as “not kept” will not be affected. Conformers that doesn’t contain stoichiometry data are always treated as non-matching.

trim_not_optimized() → None[source]

Mark all conformers that failed structure optimization as “not kept”.

Notes

Conformers previously marked as “not kept” will not be affected. Conformers that doesn’t contain optimization data are always treated as optimized.

trim_non_normal_termination() → None[source]

Mark all conformers, which calculation job did not terminate normally,: as “not kept”.

Notes

Conformers previously marked as “not kept” will not be affected. Conformers that doesn’t contain data regarding their calculation job’s termination are always treated as terminated abnormally.

trim_inconsistent_sizes() → None[source]

Mark as “not kept” all conformers that contain any iterable data genre, that is of different length, than in case of majority of conformers.

Examples

>>> c = Conformers(
...     one={'a': [1, 2, 3]},
...     two={'a': [1, 2, 3]},
...     three={'a': [1, 2, 3, 4]}
... )
>>> c.kept
[True, True, True]
>>> c.trim_inconsistent_sizes()
>>> c.kept
[True, True, False]

Notes

Conformers previously marked as “not kept” will not be affected.

trim_to_range(genre: str, minimum: Union[int, float] = - inf, maximum: Union[int, float] = inf, attribute: str = 'values') → None[source]

Marks as “not kept” all conformers, which numeric value of data of specified genre is outside of the range specified by minimum and maximum values.

Parameters

genre – Name of genre that should be compared to specified minimum and maximum values.
minimum – Minimal accepted value - every conformer, which genre value evaluates to less than minimum will be marked as “not kept”. Defaults to float(-inf).
maximum – Maximal accepted value - every conformer, which genre value evaluates to more than maximum will be marked as “not kept”. Defaults to float(inf).
attribute – Attribute of DataArray of specified genre that contains one-dimensional array of numeric values. defaults to “values”.

Raises

AttributeError – If DataArray associated with genre genre has no attribute attribute.
ValueError – If data retrieved from specified genre’s attribute is not in the form of one-dimensional array.
TypeError – If comparision cannot be made between elements of specified genre’s attribute and minimum or maximum values.

Notes

Conformers previously marked as “not kept” will not be affected.

trim_rmsd(threshold: typing.Union[int, float], window_size: typing.Optional[typing.Union[int, float]], geometry_genre: str = 'last_read_geom', energy_genre: str = 'scf', ignore_hydrogen: bool = True, moving_window_strategy: typing.Callable = <function stretching_windows>) → None[source]

Marks as “not kept” all conformers that are identical with some other conformer, judging by a provided RMSD threshold.

To minimize computation cost, conformers are compared inside windows, that is a subsets of the original list of conformers. Those windows are generated by the moving_window_strategy function. The recommended strategy, and a default value, is streaching_windows(), but other are also available: fixed_windows() and pyramid_windows(). This function will be called with list of energies for conformers compared and (if it is not None) window_size parameter.

With default moving_window_strategy conformers, which energy difference (dE) is higher than given window_size are always treated as different, while those with dE smaller than window_size and RMSD value smaller than given threshold are considered identical. From two identical conformers, the one with lower energy is “kept”, and the other is discarded (marked as “not kept”).

Notes

RMSD threshold and size of the energy window should be chosen depending on the parameters of conformers’ set: number of conformers, size of the conformer, its lability, etc. However, threshold of 0.5 angstrom and window_size of 5 to 10 kcal/mol is a good place to start if in doubt.

Parameters

threshold (int or float) – Maximum RMSD value to consider conformers identical.
window_size (int or float) – Size of the energy window, in kcal/mol, inside which RMSD matrix is calculated. Essentially, a difference in conformers’ energy, after which conformers are always considered different.
geometry_genre (str) – Genre of geometry used to calculate RMSD matrix. “last_read_geom” is default.
energy_genre (str) – Genre of energy used to sort and group conformers into windows of given energy size. “scf” is used by default.
ignore_hydrogen (bool) – If hydrogen atom should be discarded before RMSD calculation. Defaults to True.
moving_window_strategy (callable) – Function that generates windows, inside which RMSD comparisions is performed.

Raises

InconsistentDataError – If requested genres does not provide the same set of conformers.
ValueError – When called with ignore_hydrogen=True but requested Geometry.atoms cannot be collapsed to 1-D array.

select_all() → None[source]: Marks all conformers as ‘kept’. Equivalent to conformers.kept = True.

reject_all() → None[source]: Marks all conformers as ‘not kept’. Equivalent to conformers.kept = False.

kept_keys(indices: bool = False) → tesliper.glassware.conformers._KeptKeysView[source]

Equivalent of dict.keys() but gives view only on conformers marked as “kept”. Returned view may also provide information on conformers index in its Conformers instance if requested with indices=True.

>>> c = Conformers(c1={"g": 0.1}, c2={"g": 0.2}, c3={"g": 0.3}}
>>> c.kept = [True, False, True]
>>> list(c.kept_keys())
["c1", "c3"]
>>> list(c.kept_keys(indices=True))
[(0, "c1"}), (2, "c3")]

Parameters: indices (bool) – If resulting Conformers view should also provide index of each conformer. Defaults to False.
Returns: View of kept conformers.
Return type: _KeptKeysView

kept_values(indices: bool = False) → tesliper.glassware.conformers._KeptValuesView[source]

Equivalent of dict.values() but gives view only on conformers marked as “kept”. Returned view may also provide information on conformers index in its Conformers instance if requested with indices=True.

>>> c = Conformers(c1={"g": 0.1}, c2={"g": 0.2}, c3={"g": 0.3}}
>>> c.kept = [True, False, True]
>>> list(c.kept_values())
[{"g": 0.1}, {"g": 0.3}]
>>> list(c.kept_values(indices=True))
[(0, {"g": 0.1}), (2,  {"g": 0.3})]

Parameters: indices (bool) – If resulting Conformers view should also provide index of each conformer. Defaults to False.
Returns: View of kept conformers.
Return type: _KeptValuesView

fromkeys(value=None): Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None, /): Return the value for key if key is in the dictionary, else default.

items() → a set-like object providing a view on D's items

kept_items(indices: bool = False) → tesliper.glassware.conformers._KeptItemsView[source]

Equivalent of dict.items() but gives view only on conformers marked as “kept”. Returned view may also provide information on conformers index in its Conformers instance if requested with indices=True.

>>> c = Conformers(c1={"g": 0.1}, c2={"g": 0.2}, c3={"g": 0.3}}
>>> c.kept = [True, False, True]
>>> list(c.kept_items())
[("c1", {"g": 0.1}), ("c3", {"g": 0.3})]
>>> list(c.kept_items(indices=True))
[(0, "c1", {"g": 0.1}), (2, "c3", {"g": 0.3})]

Parameters: indices (bool) – If resulting Conformers view should also provide index of each conformer. Defaults to False.
Returns: View of kept conformers.
Return type: _KeptItemsView

keys() → a set-like object providing a view on D's keys

pop(k[, d]) → v, remove specified key and return the corresponding: value. If key is not found, d is returned if given, otherwise KeyError is raised.

setdefault(key, default=None)

Insert key with a value of default if key is not in the dictionary.

Return the value for key if key is in the dictionary, else default.

values() → an object providing a view on D's values

property untrimmed: tesliper.glassware.conformers.Conformers

Temporally remove trimming. Implemented as context manager to use with python’s ‘with’ keyword.

Examples

>>> c = Conformers(one={}, two={}, tree={})
>>> c.kept = [False, True, False]
>>> with c.untrimmed:
>>>     c.kept
[True, True, True]
>>> c.kept
[False, True, False]

trimmed_to(blade: Union[Sequence[bool], Sequence[str], Sequence[int], bool]) → tesliper.glassware.conformers.Conformers[source]

Temporally set trimming blade to given one. Implemented as context manager to use with python’s ‘with’ keyword.

Parameters: blade (bool or sequence of bool, str, or int) – Temporary trimming blade. To better understand how blade setting works, see Conformers.kept documentation.

Examples

>>> c = Conformers(one={}, two={}, tree={})
>>> c.kept = [True, True, False]
>>> with c.trimmed_to([1, 2]):
>>>     c.kept
[False, True, True]
>>> c.kept
[True, True, False]

property inconsistency_allowed: tesliper.glassware.conformers.Conformers

Temporally sets Conformers’ ‘allow_data_inconsistency’ attribute to true. Implemented as context manager to use with python’s ‘with’ keyword.

Examples

>>> c = Conformers(...)
>>> with c.inconsistency_allowed:
>>>     # do stuff here while c.allow_data_inconsistency is True
>>>     c.allow_data_inconsistency
True
>>> c.allow_data_inconsistency
False