.. _digichem_report:

Digichem Report
===============

``digichem report`` is used to generate compiled PDF reports (and associated images) from completed calculation results:

.. code-block:: console

    $ 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).

.. _report_input_files:

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.

.. tab-set::

    .. tab-item:: Gaussian

        Digichem accepts both the formatted (.fchk) and unformatted (.chk) checkpoint files:

        .. code-block:: console

            $ 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).

    .. tab-item:: Orca

        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:

        .. code-block:: console

            $ digichem report -C Benzene.log gbw:C6H6.gbw density:C6H6.densities
    
    .. tab-item:: Turbomole

        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:

        .. code-block:: console

            $ 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:

.. code-block:: console

    $ 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:

.. code-block:: console

    $ 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:

.. code-block:: console

    $ 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`` :ref:`command<digichem_image>`.

Combined calculations
---------------------

Just like the ``silico result`` :ref:`command<digichem_result>`, ``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):

.. code-block:: console

    $ 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):

.. code-block:: console

    $ 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:

.. code-block:: console

    $ 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:

.. code-block:: console

    $ 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:

    .. code-block:: console

        $ 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:

.. code-block:: console

    $ digichem report Benzene.log -S "render: {orbital: {isovalue: 0.04}}"


The full list of available report options is provided below.

Render options
______________

.. configurable:: silico.config Silico_options:render

Report options
______________

.. configurable:: silico.config Silico_options:report

----

.. configurable:: silico.config Silico_options:skeletal_image

Graph related options
_____________________

.. configurable:: silico.config Silico_options:excited_states_diagram

----

.. configurable:: silico.config Silico_options:orbital_diagram

Simulated spectra related options
_________________________________

.. configurable:: silico.config Silico_options:absorption_spectrum

----

.. configurable:: silico.config Silico_options:emission_spectrum

----

.. configurable:: silico.config Silico_options:IR_spectrum