Outputs parsing

This section describes the general approach used for the parsing of outputs produced by TURBOMOLE. In particular here we focus mainly on the text output that is written in the stdout. In the following we will consider that this output is written in a file name name_of_the_executable.log.

Since some outputs are stored in files structured with data groups you can also use the DataGroups object described in The data group files. The information from there will only be just parsed as strings though and most of information should be extracted from the log files using the objects described below.

Lastly we will also deal below with the methods to extract the list of states from the outputs of a calculation. This does not rely on the parsing of the log files.

The log files

Quick Start

Before digging in the details of how the objects are organized it will be good to have a quick look at how you can use the objects available and a few examples of the data that they can extract. If you instead prefer to have an idea about the structure of the object you can first check the Overall Structure section and then come back here to the examples.

The most important method to parse your output file is the from_file class method. All the data and file objects can be created using it.

Starting with a basic example of an RIDFT calculation, for which the ridft.log file is the output of the calculation, you can extract the relevant data (in the form of a data object) in the same manner. For example, the final energy (as well as its decomposition into its different contributions) is obtained using the turbomoleio.output.data.ScfEnergiesData object:

>>> from turbomoleio.output.data import ScfEnergiesData
>>> energy_data = ScfEnergiesData.from_file('ridft.log')
>>> energy_data
<turbomoleio.output.data.ScfEnergiesData at 0x7fb15f425eb8>

>>> print(energy_data.total_energy)
-0.49586861429
>>> print(energy_data.virial_theorem)
1.42945116692

Similarly, the complete information of this same RIDFT calculation can be gathered in an ScfOutput object. This object contains a series of basic data objects (such as the above ScfEnergiesData). An instance of ScfOutput can be generated using the following procedure:

>>> from turbomoleio.output.files import ScfOutput
>>> scf_output = ScfOutput.from_file('ridft.log')

You can access the basic data objects through different attributes. For example, you have access to the above ScfEnergiesData object from the energies attribute:

>>> print(scf_output.energies.total_energy)
-0.49586861429

You can also have access to the SCF iterations of the calculations:

>>> iterations = scf_output.scf.iterations
>>> iterations
<turbomoleio.output.data.ScfIterationData at 0x7fd37d6282b0>

So-called helper functions are available for the different data objects. For example, from the ScfIterationData object above, you can directly have a plot of the convergence:

>>> iterations.plot_energies()

Overall Structure

The code that performs the parsing is organized on three levels. At the lowest level there is a generic turbomoleio.output.parser.Parser object that takes the string of the file and is only focused on the extraction of information. This has several properties, each one tailored to parse specific subsections of the text and extract the relevant data using regular expressions. The properties return a dictionary with the data that have been extracted or None, if the section that it should parse could not be found in the string. In addition these properties are lazy, in the sense that they will store the output before returning it and if called again they will not repeat the parsing. The Parser object, although it can be easily used to extract some punctual information, is probably less useful to the generic user, who would mostly interact with the higher level objects.

The second level is given by a series of common data objects (see Common data objects). These objects describe single pieces of information that could be gathered together based on similarity and type of information (e.g. data related to basis set, data related to Cosmo, …). They rely on the Parser to extract the data (can call one or more of its methods) and store them in a systematic way as attributes, so that they can be accessed easily. The root method for initializing the data objects is a from_parser class method that takes a Parser as an input. The user however is much more likely to use the class method from_file, that takes the path to a TURBOMOLE output file as an input.

The top level is given by the File data objects, that are designed to parse the outputs files produced by the different kinds of TURBOMOLE executables. The objects contain as attributes different instances of the data objects, thus collecting in a single place all the information that can be extracted from a specific output file. These file objects can also be easily created with the from_file method.

Note that, like most of the other objects in turbomoleio, data and files objects are all MSONable (see monty documentation). This means that they can be converted to and generated from a dictionary with the as_dict and from_dict methods.

This should be enough to understand how to interact with these objects from the user side. If you need more information about the internal implementation or you wish to implement the parsing of additional quantities you should check out the Output logs parsing section of the developer guide.

Data and File Objects

The data and file objects are found in the turbomoleio.output.data and turbomoleio.output.files respectively. Here we provide a list of all the objects in the modules along with a quick description of the data that they contain. You can check the API documentation of each of them for more details about their content.

Common data objects

turbomoleio.output.data.TurbomoleData Turbomole version and executable used.

turbomoleio.output.data.RunData Information about where the calculation was executed and the timings.

turbomoleio.output.data.BasisData Basis sets used for the calculation.

turbomoleio.output.data.CosmoData Information about the use of cosmo.

turbomoleio.output.data.SymmetryData Information on the symmetry of the molecule.

turbomoleio.output.data.FunctionalData Exchange-correlation functional.

turbomoleio.output.data.RiData Information about the use of the Resolution of Identity approach.

turbomoleio.output.data.DispersionCorrectionData Dispersion correction used in the calculation.

turbomoleio.output.data.DFTData Information about a dft calculation (composed of FunctionalData, RiData, DispersionCorrectionData and grids size information).

turbomoleio.output.data.ScfIterationData Details about the iterations in a scf calculation.

turbomoleio.output.data.ScfData Information about options and operations in an scf calculation (contains ScfIterationData and other information such as DIIS, virtual orbital shift, convergence criteria, …).

turbomoleio.output.data.ScfEnergiesData Final energies and different contributions obtained from an scf calculation.

turbomoleio.output.data.ElectrostaticMomentsData Electrostatic moments (charge, dipole and quadrupole).

turbomoleio.output.data.GeometryData Geometry of the system: molecule and centers of mass/charge.

turbomoleio.output.data.SpinData Information about the spin in the calculation.

turbomoleio.output.data.SmearingData Information about the smearing.

turbomoleio.output.data.IntegralData Thresholds for integrals.

turbomoleio.output.data.EscfIterationData Details about the iterations in an escf calculation.

turbomoleio.output.data.EscfData Output of an escf calculation.

turbomoleio.output.data.StatptData Initial information provided in statpt.

turbomoleio.output.data.RelaxData Initial information provided in relax.

turbomoleio.output.data.RelaxGradientsData Gradient values extracted from the relax/stapt output.

turbomoleio.output.data.RelaxConvergenceData Final information about convergence.

turbomoleio.output.data.AoforceNumericalIntegrationData Information about the numerical integration in aoforce.

turbomoleio.output.data.AoforceRotationalData Analysis of rotational states in aoforce.

turbomoleio.output.data.AoforceVibrationalData Analysis of vibrational states in aoforce.

turbomoleio.output.data.MP2Data Information about an MP2 calculation.

turbomoleio.output.data.MP2Results Results from an MP2 calculation.

turbomoleio.output.data.PeriodicityData Information about the periodicity of the calculation.

File data objects

turbomoleio.output.files.ScfOutput Data from a dscf, ridft or riper calculations.

turbomoleio.output.files.EscfOutput Data from an escf calculation (contains some data about the previous scf calculation).

turbomoleio.output.files.EscfOnlyOutput Data from an escf calculation (data only related to escf).

turbomoleio.output.files.GradOutput Data from a grad or rdgrad calculation.

turbomoleio.output.files.EgradOutput Data from an egrad calculation (contains both the “grad”-related and “escf”-related data).

turbomoleio.output.files.RelaxOutput Data from a relax calculation.

turbomoleio.output.files.StatptOutput Data from a statpt calculation.

turbomoleio.output.files.AoforceOutput Data from an aoforce calculation.

turbomoleio.output.files.Ricc2Output Data from an Ri CC2 calculation.

turbomoleio.output.files.MP2Output Data from an MP2 calculation (mpgrad, ricc2 or pnoccsd).

turbomoleio.output.files.JobexOutput Data from the last step of a jobex calculation.

The States object

The list of eigenstates of a molecule with their occupation can normally be extracted from the TURBOMOLE outputs using the eiger script. In turbomoleio a similar code has been implemented that uses the content of the different data groups in the control file (possibly accessing subfiles linked in control) to build an instance of turbomoleio.output.states.States. This is a subclass of collections.abc.MutableSequence containing a list of turbomoleio.output.states.State. The states are sorted in ascending order based on the eigenvalues and each State contains the information about the eigenvalue, the irreducible representation, the index associated with the irreducible representation, the occupation and, for UHF calculations, the spin.

Similarly to the other output parsing objects it can be instantiated using the from_file class method

states = States.from_file("control")

Here, in general, the control file alone is not enough and the code needs to access the $scfmo, $uhfmo_alpha and $uhfmo_beta datagroups, that are usually stored in external files, to read the eigenvalues. If the files are not available the generation of the object fails.

The States object offer various methods to extract further information from the list of states, like the gap or the has_hole to determine if in the list of eigenstates there is one empty state with energy lower than some occupied state. You can check the rest of the API to have a list of the methods available.