Package: tesliper
teslipertesliper: Theoretical Spectroscopist's Little Helper is a program for batch processing
of Gaussian output files, focused on calculations of vibrational, electronic, and
scattering spectra from Gaussian-calculated quantum properties of molecule's conformers.It allows to easily exclude conformers that are not suitable for further analysis:
erroneous, not optimized, of higher energy or lower contribution than a user-given
threshold. It also implements an RMSD sieve, enabling one to filter out similar
structures. It lets you calculate theoretical IR, VCD, UV, ECD, Raman, and ROA spectra
for each conformer or as a population-weighted average and export obtained spectral data
in one of supported file formats:.txt,.csv, or.xlsx. Finally, if allows to
easily setup a next calculations step with batch export to.gjfGaussian input files.tesliperis written in Python 3.6 and makes use of some additional third party
packages (see below or requirements.txt). It may be used as a package or as a
stand-alone application with dedicated GUI.tesliperGetting StartedRequirementsInstalling to your Python distributionA standalone applicationHow to usePrimerIn Python scriptsA graphical interfaceLicenseContributing totesliperBugs and suggestionsParticipating in codeRoadmapAcknowledgementsGetting StartedYou can usetesliperfrom python or as standalone application with dedicated graphical
user interface. See below for details.RequirementsPython 3.6+
numpy
openpyxl
matplotlib (optional, for GUI)tesliperusestkinterto deliver the graphical interface. It is included in
most Python distributions, but please be aware, that some might miss it. You will
need to install it manually in such case.Installing to your Python distributiontesliperis available on PyPI, you can install it to your python distribution by
simply running:$ python -m pip install tesliperor$ python -m pip install tesliper[gui]if you would like to be able to use a graphical interface.A standalone applicationThis option is currently available only for Windows users.
To get your copy oftesliper, simply download aTesliper.exefile from thelatest relase.
This file is a standalone application, no installation is required.How to useFull documentation is available online:https://tesliper.readthedocs.io/.PrimerConventions that are important to note:tesliperstores multiple data entries of various types for each conformer. To
prevent confusion with Python's datatypeand with data itself,tesliperrefers to
specific kinds of data as "genres". Genres in code are represented by specific strings,
used as identifiers. To learn about data genres known totesliper, seeAvailable data
genres.tesliperidentifies conformers using a stem of an extracted file (i.e. its filename
without extension). When files with identical names are extracted in course of
subsequentTesliper.extractcalls or in recursive extraction usingTesliper.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.tesliperwas 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 setTesliper.conformers.allow_data_inconsistencytoTrue.tesliperwill then stop
complaining and try to do its best.In Python scriptsTesliperclass is the main access point totesliper'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:fromtesliperimportTeslipertslr=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 modifyingTesliper's configuration attributes:to change source directory
or location of exported files instantiateTesliperobject withinput_dirandoutput_dirparameters specified, respectively. You can also set appropriate
attributes on the instance directly;to extract only selected files ininput_dirusewanted_filesinit parameter.
It should be given an iterable of filenames you want to parse. Again, you can
also directly set an identically named attribute;useTesliper.conformers.trim...methods to easily filter out conformers you wish
to ignore in further analysis;to change parameters used for calculation of spectra, modify appropriate entries
ofparametersattribute;use other export methods to export more data and specifyfmtparameter
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 these namestslr.extract()# use tslr.input_dir as sourcetslr.extract(path="./myjob/vcd_sim/")# use other input_dirtslr.conformers.trim_not_optimized()# filtering out unwanted conformerstslr.parameters["vcd"].update({"start":500,"stop":2500,"width":2})tslr.calculate_spectra(genres=["vcd"])# we want only VCD spectrumtslr.average_spectra()tslr.export_averaged(mode="w")# overwrite previously exported filestslr.export_activities(fmt="csv")# save activities for analysis elsewheretslr.output_dir="./myjob/ecd_sim/"tslr.export_job_file(# prepare files for next step of calculationsroute="# td=(singlets,nstates=80) B3LYP/Def2TZVP")A graphical interfaceIf you are usingtesliperas a standalone application, simply double click on theTesliper.exefile to start the application. To invoke it from the command line,
just runtesliper-gui. GUI consists of three panels and a number of controls.
The panels are: "Extracted data", "Energies list", and "Spectra view". First two
offer a list of conformers read so far using "Chose files" and "Chose folder" buttons
on the left. The last enables to preview calculated spectra."Extracted data" panel shows an identifier of each conformer (a file name) and an
overview of data extracted. Little checkboxes on the left of each conformer may be
clicked to mark this conformer as "kept" or "not kept"."Energies list" offers the same set of conformers and checkboxes, but with energies
values listed for each conformer. The view may be changed using "Show" dropdown box
in "Energies and Structure" section of controls, to present difference in energy
between conformers or their percentage contribution in population."Spectra view" tab shows calculated spectra. It may be controlled using "Calculate
spectra" section. After choosing a spectra genre to calculate you may control if it is
simulated using lorentzian or gaussian fitting function, change peak width, spectra
bounds, etc. You may view spectra for one conformer, all of them stacked, or averaged.
You may also load an experimental spectrum (.txt or .csv format) for comparison.Once done with extracting files and tweaking parameters, export selected data to desired
format or save the session for later using buttons in "Session control" section.A detailed tutorial with screenshots is available in the documentation:https://tesliper.readthedocs.io/en/stable/gui.html.LicenseThis project is licensed with BSD 2-Clause license.
SeeLICENSE.txtfile for details.Contributing totesliperContributions are welcome!tesliperis a growing project and definitely has room
for improvements.Bugs and suggestionsBug reports are of great value, if you encounter a problem please let me know by
submitting anew issue.
If you have a suggestion howteslipercan be improved, please let me know as well!Participating in codeIf you'd like to contribute totesliper's codebase, that's even better! If there is a
specific bug that you know how to fix or a feature you'd like to develop, please let me
know viaissues. To start coding, get your
working copy oftesliper's source code by cloning the repository and then setup your
environment by installing development dependencies (probably to a virtual environment):python -m pip install .[dev]Please remember to add/update relevant tests along with your code changes.
Make sure the test suite passes by runningpython -m pytest testor, if you'd like to also generate the coverage report, you can invoke the pytest
with the pytest-cov plugin (included in the "dev" installation), as shown below.
The .coveragerc file includes plugin's configuration (i.e. to omit GUI code).python -m pytest --cov=tesliper --cov-config=.coveragerc testIf you contribute code totesliper, the test coverage badge will be updated by the CI
service after your changes are merged.Althoughmypyis not incorporated intesliper's
development (yet!), I believe that type hints greatly improve the experience of using
the package. Please, add them to the new code you submit. If you're willing to
supplement typing of the existing code, that would be very much welcome!tesliper's codebase is formatted withblackandisort, please use these tools before submitting your
code contribution. To make it easier, you may use a pre-commit configuration available
in this repository. To include it in your workflow, simply runpre-commit installin
your copy's root directory. Note, that this configuration also sets upflake8linter.To get your change introduced to the codebase, please make a Pull Request to thefixesbranch for quick bug fixes or to thedevbranch for new features and bigger changes.
If at a loss, do not hesitate to reach to me directly! :)RoadmapIdeas for possible future improvements to the software are listed below. Based on the
feedback from the Community, I will decide, which ones are desired and worth working on.New Functionality:command line interfacesupport for Jaguar & other packagesoption for usingcclibfor parsingspectra comparison featurevelocity and length electronic spectra comparisonparsing conformational search filesGUI: manually choose spectra colourUX Improvements:supplement loggingauto finding optimal spectra rangeGUI: export spectra as imageGUI: spectra colour by populationGUI: drag&drop supportGUI: display tooltips on hoverAcknowledgementsMany thanks to the scientists, who advised me on the domain-specific details and helped
to test the software:Joanna Rode0000-0003-0592-4053Magdalena Jawiczuk0000-0003-2576-4042Marcin GĂłrecki0000-0001-7472-3875as well as to people, who reviewed the project:@alejandrogalloand@arepstein.