tesliper.tesliper

Provides a facade-like interface for easy access to tesliper’s functionality.

There are some conventions that are important to note:

tesliper stores multiple data entries of various types for each conformer. To prevent confusion with Python’s data type and with data itself, tesliper refers to specific kinds of data as “genres”. Genres in code are represented by specific strings, used as identifiers. To learn about data genres known to tesliper, see documentation for GaussianParser, which lists them.
tesliper identifies conformers using stem of an extracted file (i.e. its filename without extension). When files with identical names are extracted in course of subsequent Tesliper.extract() calls or in recursive extraction using tesliper_object.extract(recursive=True), they are treated as data for one conformer. This enables to join data from subsequent calculations steps, e.g. geometry optimization, vibrational spectra simulation, and electronic spectra simulation. Please note that if specific data genre is available from more than one calculation job, only recently extracted values will be stored.
tesliper was designed to deal with multiple conformers of single molecule and may not work properly when used to process data concerning different molecules (i.e. having different number of atoms, different number of degrees of freedom, etc.). If you want to use it for such purpose anyway, you may set Tesliper.conformers.allow_data_inconsistency to True. tesliper will then stop complaining and try to do its best.

Classes

Tesliper([input_dir, output_dir, ...])

This class is a main access point to tesliper's functionality.

class tesliper.tesliper.Tesliper(input_dir: str = '.', output_dir: str = '.', wanted_files: Optional[Iterable[Union[str, pathlib.Path]]] = None, quantum_software: str = 'gaussian')[source]

This class is a main access point to tesliper’s functionality. It allows you to extract data from specified files, provides a proxy to the trimming functionality, gives access to data in form of specialized arrays, enables you to calculate and average desired spectra, and provides an easy way to export data.

Most basic use might look like this:

>>> tslr = Tesliper()
>>> tslr.extract()
>>> tslr.calculate_spectra()
>>> tslr.average_spectra()
>>> tslr.export_averaged()

This extracts data from files in the current working directory, calculates available spectra using standard parameters, averages them using available energy values, and exports to current working directory in .txt format.

You can customize this process by specifying call parameters for used methods and modifying Tesliper’s configuration attributes:

to change source directory or location of exported files instantiate Tesliper object with input_dir and output_dir parameters specified, respectively. You can also set appropriate attributes on the instance directly.
To extract only selected files in input_dir use wanted_files init parameter. It should be given an iterable of filenames you want to parse. Again, you can also directly set an identically named attribute.
To change parameters used for calculation of spectra, modify appropriate entries of parameters attribute.
Use other export methods to export more data and specify fmt parameter in method’s call to export to other file formats.

>>> tslr = Tesliper(input_dir="./myjob/optimization/", output_dir="./myjob/output/")
>>> tslr.wanted_files = ["one", "two", "three"]  # only files with this names
>>> tslr.extract()  # use tslr.input_dir as source
>>> tslr.extract(path="./myjob/vcd_sim/")  # use other input_dir
>>> tslr.conformers.trim_not_optimized()  # trimming out unwanted conformers
>>> tslr.parameters["vcd"].update({"start": 500, "stop": 2500, "width": 2})
>>> tslr.calculate_spectra(genres=["vcd"])  # we want only VCD spectrum
>>> tslr.average_spectra()
>>> tslr.export_averaged(mode="w")  # overwrite previously exported files
>>> tslr.export_activities(fmt="csv")  # save activities for analysis elsewhere
>>> tslr.output_dir = "./myjob/ecd_sim/"
>>> tslr.export_job_file(  # prepare files for next step of calculations
...     route="# td=(singlets,nstates=80) B3LYP/Def2TZVP"
... )

When modifying Tesliper.parameters be careful to not delete any of the parameters. If you need to revert to standard parameters values, you can find them in Tesliper.standard_parameters.

>>> tslr.parameters["ir"] = {
...     "start": 500, "stop": 2500, "width": 2
... }  # this will cause problems!
>>> tslr.parameters = tslr.standard_parameters  # revert to default values

Trimming functionality, used in previous example in tslr.conformers.trim_not_optimized(), allows you to filter out conformers that shouldn’t be used in further processing and analysis. You can trim off conformers that were not optimized, contain imaginary frequencies, or have other unwanted qualities. Conformers with similar geometry may be discarded using an RMSD sieve. For more information about trimming, please refer to the documentation of Conformers class.

For more exploratory analysis, Tesliper provides an easy way to access desired data as an instance of specialized DataArray class. Those objects implement a number of convenience methods for dealing with specific data genres. A more detailed information on DataArray see arrays module documentation. To get data in this form use array = tslr["genre"] were "genre" is string with the name of desired data genre. For more control over instantiation of DataArray you may use Tesliper.conformers.arrayed factory method.

>>> energies = tslr["gib"]
>>> energies.values
array([-304.17061762, -304.17232455, -304.17186735])
>>> energies.populations
array([0.0921304 , 0.56174031, 0.3461293 ])
>>> energies.full_name
'Thermal Free Energy'

Please note, that if some conformers do not provide values for a specific data genre, it will be ignored when retriving data for DataArray instantiation, regardles if it were trimmed off or not.

>>> tslr = Tesliper()
>>> tslr.conformers.update([
>>> ...     ('one', {'gib': -304.17061762}),
>>> ...     ('two', {'gib': -304.17232455}),
>>> ...     ('three', {'gib': -304.17186735}),
>>> ...     ('four', {})
>>> ... ])
>>> tslr.conformers.kept
[True, True, True, True]
>>> energies = tslr["gib"]
>>> energies.filenames
array(['one', 'two', 'three'], dtype='<U5')

conformers

Container for data extracted from Gaussian output files. It provides trimming functionality, enabling to filter out conformers of unwanted qualities.

Type: Conformers

spectra

Spectra calculated so far, using calculate_spectra() method. Possible keys are spectra genres: “ir”, “vcd”, “uv”, “ecd”, “raman”, and “roa”. Values are Spectra instances with lastly calculated spetra of this genre.

Type: dict of str: Spectra

averaged

Spectra averaged using available energies genres, calculated with last call to average_spectra() method. Keys are tuples of two strings: averaged spectra genre and energies genre used for averaging.

Type: dict of str: (dict of str: float or callable)

experimental

Experimental spectra loaded from disk. Possible keys are spectra genres: “ir”, “vcd”, “uv”, “ecd”, “raman”, and “roa”. Values are Spectra instances with experimental spetra of this genre.

Type: dict of str: Spectra

quantum_software

A name, lower case, of the quantum chemical computations software used to obtain data. Used by tesliper to figure out, which parser to use to extract data, if custom parsers are available. Only “gaussian” is supported out-of-the-box.

Type: str

parameters

Parameters for calculation of each spectra genres: “ir”, “vcd”, “uv”, “ecd”, “raman”, and “roa”. Avaliable parameters are:

“start”: float or int, the beginning of the spectral range,
“stop”: float or int, the end of the spectral range,
“step”: float or int, step of the abscissa,
“width”: float or int, width of the peak,
“fitting”: callable, function used to simulate peaks as curves, preferably one of datawork.gaussian or datawork.lorentzian.

“start”, “stop”, and “step” expect its values to by in cm^-1 units for vibrational and scattering spectra, and nm units for electronic spectra. “width” expects its value to be in cm^-1 units for vibrational and scattering spectra, and eV units for electronic spectra.

Type: dict of str: (dict of str: float or callable)

Parameters

input_dir (str or path-like object, optional) – Path to directory containing files for extraction, defaults to current working directory.
output_dir (str or path-like object, optional) – Path to directory for output files, defaults to current working directory.
wanted_files (list of str or list of Path, optional) – List of files or filenames representing wanted files. If not given, all files are considered wanted. File extensions are ignored.
quantum_software (str) – A name of the quantum chemical computations software used to obtain data. Used by tesliper to figure out, which parser to use, if custom parsers are available.

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

property temperature: float

Temperature of the system expressed in Kelvin units.

Value of this parameter is passed to data arrays created with the Conformers.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.

Notes

It’s actually just a proxy to self.conformers.temperatue.

property energies: Dict[str, tesliper.glassware.arrays.Energies]

Data for each energies’ genre as Energies data array. Returned dictionary is of form {“genre”: Energies} for each of the genres: “scf”, “zpe”, “ten”, “ent”, and “gib”. If no values are available for a specific genre, an empty Energies array is produced as corresponding dictionary value.

>>> tslr = Tesliper()
>>> tslr.energies
{
    "scf": Energies(genre="scf", ...),
    "zpe": Energies(genre="zpe", ...),
    "ten": Energies(genre="ten", ...),
    "ent": Energies(genre="ent", ...),
    "gib": Energies(genre="gib", ...),
}

Returns: Dictionary with genre names as keys and Energies data arrays as values.
Return type: dict

property activities: Dict[str, Union[tesliper.glassware.arrays.VibrationalActivities, tesliper.glassware.arrays.ScatteringActivities, tesliper.glassware.arrays.ElectronicActivities]]

Data for default activities used to calculate spectra as appropriate SpectralActivities subclass. Returned dictionary is of form {“genre”: SpectralActivities} for each of the genres: “dip”, “rot”, “vosc”, “vrot”, “raman1”, and “roa1”. If no values are available for a specific genre, an empty data array is produced as corresponding dictionary value.

>>> tslr = Tesliper()
>>> tslr.activities
{
    "dip": VibrationalActivities(genre="dip", ...),
    "rot": VibrationalActivities(genre="rot", ...),
    "vosc": ElectronicActivities(genre="vosc", ...),
    "vrot": ElectronicActivities(genre="vrot", ...),
    "raman1": ScatteringActivities(genre="raman1", ...),
    "roa1": ScatteringActivities(genre="roa1", ...),
}

Returns: Dictionary with genre names as keys and SpectralActivities data arrays as values.
Return type: dict

property wanted_files: Optional[Set[str]]

Set of files that are desired for data extraction, stored as filenames without an extension. Any iterable of strings or Path objects is transformed to this form.

>>> tslr = Tesliper()
>>> tslr.wanted_files = [Path("./dir/file_one.out"), Path("./dir/file_two.out")]
>>> tslr.wanted_files
{"file_one", "file_two"}

May also be set to None or other “falsy” value, in such case it is ignored.

property standard_parameters: Dict[str, Dict[str, Union[int, float, Callable]]]: Default parameters for spectra calculation for each spectra genre (ir, vcd, uv, ecd, raman, roa). This returns a dictionary, but in fact it is a convenience, read-only attribute, modifying it will have no persisting effect.

update(other: Optional[Dict[str, dict]] = None, **kwargs)[source]

Update stored conformers with given data.

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.

>>> tslr.conformers
Conformers([('one', {'scf': -100, 'stoichiometry': 'CH4'})])
>>> tslr.update(
...     {'one': {'scf': 97}, 'two': {'scf': 82, 'stoichiometry': 'CH4'}}
... )
>>> tslr.conformers
Conformers([
    ('one', {'scf': 97, 'stoichiometry': 'CH4'}),
    ('two', {'scf': 82, 'stoichiometry': 'CH4'}),
])

property input_dir: pathlib.Path: Directory, from which files should be read.

property output_dir: pathlib.Path: Directory, to which generated files should be written.

extract_iterate(path: Optional[Union[str, pathlib.Path]] = None, wanted_files: Optional[Iterable[str]] = None, extension: Optional[str] = None, recursive: bool = False) → Generator[Tuple[str, dict], None, None][source]

Extracts data from chosen Gaussian output files present in given directory and yields data for each conformer found.

Uses Tesliper.input_dir as source directory and Tesliper.wanted_files list of chosen files if these are not explicitly given as ‘path’ and ‘wanted_files’ parameters.

Parameters

path (str or pathlib.Path, optional) – Path to directory, from which Gaussian files should be read. If not given or is None, Tesliper.output_dir will be used.
wanted_files (list of str, optional) – Filenames (without a file extension) of conformers that should be extracted. If not given or is None, Tesliper.wanted_files will be used. If Tesliper.wanted_files is also None, all found Gaussian output files will be parsed.
extension (str, optional) – Only files with given extension will be parsed. If omitted, Tesliper will try to guess the extension from contents of input directory.
recursive (bool) – If True, also subdirectories are searched for files to parse, otherwise subdirectories are ignored. Defaults to False.

Yields

tuple – Two item tuple with name of parsed file as first and extracted data as second item, for each Gaussian output file parsed.

extract(path: Optional[Union[str, pathlib.Path]] = None, wanted_files: Optional[Iterable[str]] = None, extension: Optional[str] = None, recursive: bool = False)[source]

Extracts data from chosen Gaussian output files present in given directory.

Uses Tesliper.input_dir as source directory and Tesliper.wanted_files list of chosen files if these are not explicitly given as path and wanted_files parameters.

Parameters

path (str or pathlib.Path, optional) – Path to directory, from which Gaussian files should be read. If not given or is None, Tesliper.output_dir will be used.
wanted_files (list of str, optional) – Filenames (without a file extension) of conformers that should be extracted. If not given or is None, Tesliper.wanted_files will be used.
extension (str, optional) – Only files with given extension will be parsed. If omitted, Tesliper will try to guess the extension from contents of input directory.
recursive (bool) – If True, also subdirectories are searched for files to parse, otherwise subdirectories are ignored. Defaults to False.

load_parameters(path: Union[str, pathlib.Path], spectra_genre: Optional[str] = None) → dict[source]

Load calculation parameters from a file.

Parameters

path (str or pathlib.Path, optional) – Path to the file with desired parameters specification.
spectra_genre (str, optional) – Genre of spectra that loaded parameters concerns. If given, should be one of “ir”, “vcd”, “uv”, “ecd”, “raman”, or “roa” – parameters for that spectra will be updated with loaded values. Otherwise no update is done, only parsed data is returned.

Returns

Parameters read from the file.

Return type

dict

Notes

For information on supported format of parameters configuration file, please refer to ParametersParser documentation.

load_experimental(path: Union[str, pathlib.Path], spectrum_genre: str) → tesliper.glassware.spectra.SingleSpectrum[source]

Load experimental spectrum from a file. Data read from file is stored as SingleSpectrum instance in Tesliper.experimental dictionary under spectrum_genre key.

Parameters

path (str or pathlib.Path) – Path to the file with experimental spectrum.
spectrum_genre (str) – Genre of the experimental spectrum that will be loaded. Should be one of “ir”, “vcd”, “uv”, “ecd”, “raman”, or “roa”.

Returns

Experimental spectrum loaded from the file.

Return type

SingleSpectrum

calculate_single_spectrum(genre: str, conformer: Union[str, int], start: Optional[Union[int, float]] = None, stop: Optional[Union[int, float]] = None, step: Optional[Union[int, float]] = None, width: Optional[Union[int, float]] = None, fitting: Optional[Callable[[numpy.ndarray, numpy.ndarray, numpy.ndarray, float], numpy.ndarray]] = None) → tesliper.glassware.spectra.SingleSpectrum[source]

Calculates spectrum for requested conformer.

‘start’, ‘stop’, ‘step’, ‘width’, and ‘fitting’ parameters, if given, will be used instead of the parameters stored in Tesliper.parameters attribute. ‘start’, ‘stop’, and ‘step’ values will be interpreted as cm^-1 for vibrational or scattering spectra/activities and as nm for electronic ones. Similarly, ‘width’ will be interpreted as cm^-1 or eV. If not given, values stored in appropriate Tesliper.parameters are used.

Parameters

genre (str) – Spectra genre (or related spectral activities genre) that should be calculated. If given spectral activity genre, this genre will be used to calculate spectra instead of the default activities.
conformer (str or int) – Conformer, specified as it’s identifier or it’s index, for which spectrum should be calculated.
start (int or float, optional) – Number representing start of spectral range.
stop (int or float, optional) – Number representing end of spectral range.
step (int or float, optional) – Number representing step of spectral range.
width (int or float, optional) – Number representing half width of maximum peak height.
fitting (function, optional) – Function, which takes spectral data, freqs, abscissa, width as parameters and returns numpy.array of calculated, non-corrected spectrum points. Basically one of datawork.gaussian or datawork.lorentzian.

Returns

Calculated spectrum.

Return type

SingleSpectrum

calculate_spectra(genres: Iterable[str] = ()) → Dict[str, tesliper.glassware.spectra.Spectra][source]

Calculates spectra for each requested genre using parameters stored in Tesliper.parameters attribute.

Parameters: genres (iterable of str) – List of spectra genres (or related spectral activities genres) that should be calculated. If given spectral activity genre, this genre will be used to calculate spectra instead of the default activities. If given empty sequence (default), all available spectra will be calculated using default activities.
Returns: dict of str – Dictionary with calculated spectra genres as keys and Spectra objects as values.
Return type: Spectra

get_averaged_spectrum(spectrum: str, energy: str, temperature: Optional[float] = None) → tesliper.glassware.spectra.SingleSpectrum[source]

Average previously calculated spectra using populations derived from specified energies.

New in version 0.9.1: The optional temperature parameter.

Changed in version 0.9.1: If spectra needed for averaging was not calulated so far, it will try to calulate it instead of raising a KeyError.

Parameters

spectrum (str) – Genre of spectrum that should be averaged. This spectrum should be previously calculated using calculate_spectra() method.
energy (str) – Genre of energies, that should be used to calculate populations of conformers. These populations will be used as weights for averaging.
temperature (float, optional) – Temperature used for calculation of the Boltzmann distribution for spectra averaging. If not given, Tesliper.temperature() value is used.

Returns

Calculated averaged spectrum.

Return type

SingleSpectrum

Raises

ValueError – If no data for calculation of requested spectrum is available.

average_spectra() → Dict[Tuple[str, str], tesliper.glassware.spectra.SingleSpectrum][source]

For each previously calculated spectra (stored in Tesliper.spectra attribute) calculate it’s average using population derived from each available energies genre.

Returns: Averaged spectrum for each previously calculated spectra and energies known as a dictionary. It’s keys are tuples of genres used for averaging and values are SingleSpectrum instances (so this dictionary is of form {tuple(“spectra”, “energies”): SingleSpectrum}).
Return type: dict

export_data(genres: Sequence[str], fmt: str = 'txt', mode: str = 'x')[source]

Saves specified data genres to disk in given file format.

File formats available by default are: “txt”, “csv”, “xlsx”, “gjf”. Note that not all formats may are compatible with every genre (e.g. only genres associated with Geometry may be exported fo .gjf format). In such case genres unsupported by given format are ignored.

Files produced are written to Tesliper.output_dir directory with filenames automatically generated using adequate genre’s name and conformers’ identifiers. In case of “xlsx” format only one file is produced and different data genres are written to separate sheets. If there are no values for given genre, no files will be created for this genre.

Parameters

genres (list of str) – List of genre names, that will be saved to disk.
fmt (str) – File format of output files, defaults to “txt”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.

export_energies(fmt: str = 'txt', mode: str = 'x')[source]

Saves energies and population data to disk in given file format.

File formats available by default are: “txt”, “csv”, “xlsx”. Files produced are written to Tesliper.output_dir directory with filenames automatically generated using adequate genre’s name and conformers’ identifiers. In case of “xlsx” format only one file is produced and different data genres are written to separate sheets.

Parameters

fmt (str) – File format of output files, defaults to “txt”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.

export_spectral_data(fmt: str = 'txt', mode: str = 'x')[source]

Saves unprocessed spectral data to disk in given file format.

File formats available by default are: “txt”, “csv”, “xlsx”. Files produced are written to Tesliper.output_dir directory with filenames automatically generated using adequate genre’s name and conformers’ identifiers. In case of “xlsx” format only one file is produced and different data genres are written to separate sheets.

Parameters

fmt (str) – File format of output files, defaults to “txt”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.

export_activities(fmt: str = 'txt', mode: str = 'x')[source]

Saves unprocessed spectral activities to disk in given file format.

File formats available by default are: “txt”, “csv”, “xlsx”. Files produced are written to Tesliper.output_dir directory with filenames automatically generated using adequate genre’s name and conformers’ identifiers. In case of “xlsx” format only one file is produced and different data genres are written to separate sheets.

Parameters

fmt (str) – File format of output files, defaults to “txt”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.

export_spectra(fmt: str = 'txt', mode: str = 'x')[source]

Saves spectra calculated previously to disk in given file format.

File formats available by default are: “txt”, “csv”, “xlsx”. Files produced are written to Tesliper.output_dir directory with filenames automatically generated using adequate genre’s name and conformers’ identifiers. In case of “xlsx” format only one file is produced and different data genres are written to separate sheets.

Parameters

fmt (str) – File format of output files, defaults to “txt”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.

export_averaged(fmt: str = 'txt', mode: str = 'x')[source]

Saves spectra calculated and averaged previously to disk in given file format.

File formats available by default are: “txt”, “csv”, “xlsx”. Files produced are written to Tesliper.output_dir directory with filenames automatically generated using adequate genre’s name and conformers’ identifiers. In case of “xlsx” format only one file is produced and different data genres are written to separate sheets.

Parameters

fmt (str) – File format of output files, defaults to “txt”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.

export_job_file(fmt: str = 'gjf', mode: str = 'x', geometry_genre: str = 'last_read_geom', **kwargs)[source]

Saves conformers to disk as job files for quantum chemistry software in given file format.

Currently only “gjf” format is provided, used by Gaussian software. Files produced are written to Tesliper.output_dir directory with filenames automatically generated using conformers’ identifiers.

Parameters

fmt (str) – File format of output files, defaults to “gjf”.
mode (str) – Specifies how writing to file should be handled. May be one of: “a” (append to existing file), “x” (only write if file doesn’t exist yet), “w” (overwrite file if it already exists). Defaults to “x”.
geometry_genre (str) – Name of the data genre representing conformers’ geometry that should be used as input geometry. Please note that the default value “last_read_geom” is not necessarily an optimized geometry. Use “optimized_geom” if this is what you need.
kwargs –
Any additional keyword parameters are passed to the writer object, relevant to the fmt requested. Keyword supported by the default "gjf"-format writer are as follows:

route
A calculations route: keywords specifying calculations directives for quantum chemical calculations software.

link0
Dictionary with “link zero” commands, where each key is command’s name and each value is this command’s parameter.

comment
Contents of title section, i.e. a comment about the calculations.

post_spec
Anything that should be placed after conformer’s geometry specification. Will be written to the file as given.

serialize(filename: str = '.tslr', mode: str = 'x') → None[source]

Serialize instance of Tesliper object to a file in output_dir.

Parameters

filename (str) – Name of the file, to which content will be written. Defaults to “.tslr”.
mode (str) – Specifies how writing to file should be handled. Should be one of characters: “x” or “w”. “x” - only write if file doesn’t exist yet; “w” - overwrite file if it already exists. Defaults to “x”.

Raises

ValueError – If given any other mode than “x” or “w”.

Notes

If output_dir is None, current working directory is assumed.

classmethod load(source: Union[pathlib.Path, str]) → tesliper.tesliper.Tesliper[source]

Load serialized Tesliper object from given file.

Parameters: source (pathlib.Path or str) – Path to the file with serialized Tesliper object.
Returns: New instance of Tesliper class containing data read from the file.
Return type: Tesliper