Digichem Report
digichem report is used to generate compiled PDF reports (and associated images) from completed calculation results:
$ digichem report LOG_FILE
Note
The reports that are generated by this program are typically written automatically at the end of each calculation.
The digichem report command is useful for making reports from calculations where they are missing (perhaps because the
calculation was submitted manually, or an error occurred), or where you want to make a change to a report (for example, by
including a different selection of orbitals).
Input files
Unlike most other Digichem commands, digichem report normally needs more data than is found in just the main calculation
log file to generate the report. This is because electron densities (such as are required to render orbital densities etc.)
are typically stored in a separate, binary checkpoint file. For Gaussian, this is the .chk (or .fchk) file, for Orca it is
the .gbw file etc.
Digichem will try to intelligently guess the location of these checkpoint files based on the location of the given log files.
In most cases, both files will have the same name (just with a different file extension), in which case this is easy to do.
If Digichem cannot locate the required checkpoint files, these can be explicitly included with the -C option.
Digichem accepts both the formatted (.fchk) and unformatted (.chk) checkpoint files:
$ digichem report -C Benzene.log chk:checkpoint.chk # For a .chk file
$ digichem report -C Benzene.log fchk:checkpoint.fchk # For a .fchk file
You don’t normally need to specify both a .chk and .fchk file (but you can if you want to).
Orca uses two types of ‘checkpoint’ files. The first (.gbw) is more akin to a traditional checkpoint file, while densities are stored separately (.densities). Both types are required to generate electron density plots, and both will normally be located automatically.
If these files have been moved, they can be specified with the gbw: and density: options
respectively:
$ digichem report -C Benzene.log gbw:C6H6.gbw density:C6H6.densities
Turbomole handles density files quite differently to other calculation engines. Rather than storing densities in a single checkpoint file, Turbomole utilises several files stored in the same directory. Normally, the main calculation log file(s) will also be stored in this same directory, in which case Digichem will automatically locate the necessary density files.
If the density files are located in a different location to the main log file, simply specify the path to the entire directory, rather than any of the individual density files.
For example, in a directory structure like this:
Benzene/
Benzene.out <-- Main log file
Output/ <-- Turbomole working directory
basis
control
coord
energy
gradient
gsdens
mos
...
An appropriate command would be:
$ digichem report -C Benzene/Benzene.out Benzene/Output/
Output location
Digichem will try to intelligently guess an appropriate output location to write the report to based on the location of the given output file. In a Digichem-like file structure, such as this:
Benzene/
Gaussian 16 Optimisation Frequencies PBE0 (GD3BJ) Gas Phase Pople Basis Sets 6-31G(d,p)/
Flags/
Input/
Logs/
Output/
Benzene.log
Benzene.fchk
Report/
image/
Benzene.pdf <-- Report written here.
Results/
The report is written to the Report folder, as normal.
If the calculation was not submitted by Digichem, the report will be written to a Report folder in the same location as the output files:
Benzene/
Benzene.log
Benzene.fchk
Report/
image/
Benzene.pdf <-- Report written here.
You can specify an explicit output location with the -O option. If the given file name ends in .pdf, this is taken
to be the name of the PDF file:
$ digichem report Benzene.log -O "Custom Report.pdf"
Resulting in:
Benzene/
Benzene.log
Benzene.fchk
image/
Custom Report.pdf <-- Report written here.
Otherwise, the given file is presumed to be a folder name, and the report will be written inside it:
$ digichem report Benzene.log -O "Custom Report/"
Resulting in:
Benzene/
Benzene.log
Benzene.fchk
image/
Custom Report/
image/
Benzene.pdf <-- Report written here.
To speed up the report generation process, digichem will reuse any rendered images available in the report image folder.
If you change the output location with the -O option, these previous images will not be available in the new location,
and they will need to be re-rendered.
Image rendering
By default, digichem report will not overwrite rendered image files (such as orbitals or other electron densities).
This greatly speeds up the report generation process, but means some changes (for example, the isovalue of an orbital) won’t
be reflected unless the images are regenerated.
To force the generation of new images, use the -S render: {use_existing: False} option:
$ digichem report Benzene.log -S render: {use_existing: False}
You can also choose to re-render only a select number of images with the digichem image command.
Combined calculations
Just like the silico result command, digichem report can merge results from
several different calculations into a single PDF.
To generate a merged report, use the -m option to specify the location of the various log files. You should
also specify an output location with the -O option (because Digichem can’t guess where to write automatically in
this case):
$ digichem report -m "Benzene/Gaussian Optimisation" "Benzene/Gaussian Frequency" -O "Merged report"
Multiple calculations
digichem report can also generate reports for multiple individual calculations simultaneously. Simply specify the location of each of the
log files sequentially (without the -m option):
$ digichem report Benzene/Benzene.log Pyridine/Pyridine.log
By default, the reports will be written to the usual ‘Report’ folder of each calculation.
You can instead write to a common directory with the -d option:
$ digichem report Benzene.log Pyridine.log -d "Custom Reports"
Each report will be placed in a sub-directory named after the input file. For example, the above command would result in:
Benzene.log
Pyridine.log
Custom Reports/
Pyridine/
image/
Pyridine.pdf
Benzene/
image/
Benzene.pdf
Alternatively, you can use the -r option to write each report to a location relative to each input file:
$ digichem report Benzene/Benzene.log Pyridine/Pyridine.log -r "Custom Report"
Which would result in:
Benzene/
Benzene.log
Custom Report/
image/
Benzene.pdf
Pyridine/
Pyridine.log
Custom Report/
image/
Pyridine.pdf
Note
You cannot use the normal output (-O) option when writing multiple reports simultaneously (because otherwise
they would all overwrite each other). If you try to do this, you will get an error such as the following:
$ digichem report Benzene.log Pyridine.log -O "Custom Reports"
digichem: ERROR: stopped with error
Digichem_exception: The -O/--output argument cannot be given for multiple, separate result files. Try -r or -d instead
Report & image options
Several aspects of the report can be modified be changing appropriate settings. This can be achieved
with the -S option, which takes a YAML string containing the new settings. Many of Digichem’s
settings are nested into a hierarchy and each level of the hierarchy is represented by a new dict (or object
in JSON parlance).
For example, the setting to control the isovalue used for rendering orbital densities is located here:
render:
orbital:
isovalue: 0.02
When running the digichem report command, this value can be changed as follows:
$ digichem report Benzene.log -S "render: {orbital: {isovalue: 0.04}}"
The full list of available report options is provided below.
Render options
- render
Options for controlling the appearance of 3D molecule images.
- enable_renderingbool[True]
Set to False to disable image rendering.
- engine(vmd, batoms)[vmd]
The rendering engine to use
- vmd
VMD specific options (only applies if engine == ‘vmd’
- executable[vmd]
Path to the VMD (Visual Molecular Dynamics) executable
- tachyon[tachyon]
The tachyon ray-tracing library, performs the actual rendering. Tachyon is typically packaged with VMD, but often isn’t added to the path automatically
- rendering_style(pastel, light-pastel, dark-pastel, sharp, gaussian, vesta)[pastel]
The render/display mode, changes the appearance of rendered molecules/orbitals. Possible options are: pastel: The default style, uses light, pastel-ish colours for orbitals with low transparency. Normal atom colours. light-pastel: Similar to pastel, but with lighter orbital colours. dark-pastel: Similar to pastel, but with darker orbital colours, reminiscant of the ‘sharp’ style. sharp: Orbitals are darkly coloured around their edge but have high transparency in their center. Normal atom colours. gaussian: A style attempting to mimic that of GaussView. vesta: A style attempting to mimic that of VESTA.
- batoms
Beautiful Atoms/Blender specific options (only applies if engine == ‘batoms’
- blender
Path to the blender executable, in which beautiful atoms should be installed
- cpusint[1]
The number of CPUs/threads to use. This option is overridden if running in a calculation environemnt (where it uses the same number of CPUs as the calculation did)
- render_samplesint[64]
The number of render samples (or passes) to use. Higher values result in higher image quality and greater render times
- perspective(orthographic, perspective)[orthographic]
The perspective mode
- safe_cubesbool[False]
Whether to sanitize cubes so older software can parse them (VMD < 1.9.2 etc)
- use_existingbool[True]
If True, previously created files will be reused. If False, new images will rendered, replacing the old. This is on by default for 3D rendered images because they are expensive (time-consuming) to render.
- auto_cropbool[True]
Whether to enable automatic cropping of excess whitespace around the border of generated images. If False, overall image rendering is likely to take less time, but molecules may only occupy a small portion of the true image.
- resolutionint[512]
The target resolution for rendered images. Higher values will increase image quality, at the cost of increased render time and file size.
- orbital
Specific options for orbital density plots.
- cube_grid_sizeCube_grid_points[Default]
The size of grid used to generate cube files. Densities are plotted on a 3D grid of points, this option controls how many points there are in the grid (per dimension). In addition to an integer number of points (~100 is often sufficient), any of the following keywords can also be specified: Tiny, Small, Medium, Large, Huge or Default.
- isovaluefloat[0.02]
The isovalue to use for rendering orbital density.
- spin
Specific options for spin density plots.
- cube_grid_sizeCube_grid_points[Large]
The size of the grid use to plot cube data. As cubes of this type are rendered with a smaller isovalue, it is often necessary to use a larger grid size than normal to maintain quality.
- isovaluefloat[0.0004]
The isovalue to use for plotting spin density.
- density
Specific options for total density plots.
- cube_grid_sizeCube_grid_points[Large]
The size of the grid use to plot cube data.
- isovaluefloat[0.02]
The isovalue to use for plotting total density.
- difference_density
Specific options for excited states difference density plots.
- cube_grid_sizeCube_grid_points[Default]
The size of the grid use to plot cube data.
- isovaluefloat[0.001]
The isovalue to use for difference density plots.
- natural_transition_orbital
Specific options for NTO plots.
- cube_grid_sizeCube_grid_points[Default]
The size of the grid use to plot cube data.
- isovaluefloat[0.02]
The isovalue to use for NTO plots.
- dipole_moment
Specific options for permanent dipole moment plots.
- scalingfloat[1.0]
The value (x) to scale the TDM by, where 1 D = x Å.
- transition_dipole_moment
Specific options for transition dipole moment plots.
- electric_scalingfloat[5.0]
The value (x) to scale the TEDM by, where 1 D = x Å.
- magnetic_scalingfloat[10.0]
The value (x) to scale the TMDM by, where 1 au = x Å.
Report options
- report
Options for controlling the generation of calculation reports.
- front_page_image(skeletal, rendered)[rendered]
The image to use for the front page of the report.
- turbomole
Options that control the running of Turbomole calculations to generate cube files from completed calculations. Note that when reports are created automatically following calculation completion these options will be overridden with the specifics of that calculation.
- num_cpuint[1]
The number of CPUs with which to run.
- memoryTurbomole_memory[1GB]
The amount of memory with which to run.
- programmethod
A program definition from the internal library to run.
- gaussian
Options that control the running of Gaussian calculations to generate NTO cube files from completed calculations. Note that when reports are created automatically following calculation completion these options will be overridden with the specifics of that calculation.
- num_cpuint[1]
The number of CPUs with which to run.
- memoryMemory[1GB]
The amount of memory with which to run.
- programmethod
A program definition from the internal library to run.
- scratch_path[/tmp/$USER]
Path to the top of the scratch directory.
- orca
Options that control the running of orca_plot to generate cube files from completed calculations. Note that when reports are created automatically following calculation completion these options will be overridden with the specifics of that calculation.
- memoryMemory
The amount of memory with which to run. If left blank, no maximum will be specified.
- programmethod
A program definition from the internal library to run.
- keep_cubesbool[False]
Whether to keep cube files
- cleanupbool[True]
Whether to delete intermediate files that are written during the report generation process. Intermediate files include: - .cube files. - .fchk files. - .html files. - .css files. Note that this option will only delete new files written by the program; existing files given by the user are never deleted.
- orbital_table
Options which control how many orbitals to print in the MO table. These numbers are relative to the HOMO for both the min and max. null can be specified for either/both the min/max to print all available orbitals in that direction. If both alpha and beta orbitals are available (for unrestricted calculations, for example), then additional orbitals may be printed outside of the given min/max to ensure the given value is met for both sets of orbitals. This is common for triplet calculations, where the alpha and beta frontier MOs are at different levels. Examples: min: -10, max: 16: From HOMO-10 to LUMO+15 inclusive (total of 27 orbitals). min: null, max: 11: All orbitals with energy less than or equal to LUMO+10. min: 0, max: 1: HOMO and LUMO only.
- maxint[16]
The highest orbital to show in the molecular orbital table.
- minint[-15]
The lowest orbital to show in the molecular orbital table.
- orbital_image
Options which specify which orbitals to render 3D images of. The default is the HOMO and LUMO. Orbitals can be specified by level (an index starting at 1 for the most negative orbital, useful if you want images of a particular orbital) and/or by distance from the HOMO (useful for more day-to-day operation. In addition, excited_state_transition_threshold: can be used to add orbitals that are involved in an excited state transition with a probability above a certain threshold. Duplicates will be automatically ignored, as will orbitals specified here that are not actually available in the calculation result file. Alpha and beta are set separately. Beta will be ignored if there are no beta orbitals available. Example: orbital_levels: - 5 orbital_distance: - -1 - 0 - 1 excited_state_transition_threshold: 0.1 Would render orbital 5, HOMO-1, HOMO, LUMO and any orbitals involved in an excited state transition with a probability 0.1 or greater.
- et_transition_thresholdfloat[0.1]
Include orbitals involved in an excited state transition with a probability of this value or greater.
- orbital_levelsint[[]]
Include normal/alpha orbitals by level.
- beta_levelsint[[]]
Include beta orbitals by level.
- orbital_distancesint[[0, 1]]
Include normal/alpha orbitals by distance from the HOMO.
- beta_distancesint[[0, 1]]
Include beta orbitals by distance from the HOMO.
- frequency_table
Options that control how many vibrational frequencies to list in the frequencies table.
- min_frequencyfloat
The most negative frequency to show in the table (remember that frequencies can be negative). ‘null’ is for no limit. Units are cm-1.
- max_frequencyfloat
The most positive frequency to show in the table. ‘null’ is for no limit. Units are cm-1.
- max_numint
The maximum number of frequencies to show in the table.
- nmr_image
Options which specify which NMR spectra to render.
- autobool[True]
If True, at least one experiment will be included for each element and isotope pair (for which NMR data is available). If no expt is explicitly requested (via codes), then the spectra will be the one with the least decoupling.
- codesstr[[‘13C{1H}’]]
Explicitly include certain NMR experiments.
- skeletal_image
Options for controlling the rendering of 2D skeletal images.
- resolution
The resolution for rendered images
- absoluteint
The output resolution (x and y) in pixels
- relativeint[100]
The output resolution (x and y) in multiples of the length of the molecule