Plotting Absorbance Spectra
===========================


``orto`` can plot absorbance spectra, with similar features to `orca_mapspc`.


Usage
*****

To plot an absorbance spectrum run

.. code-block:: console

    orto plot abs <output_file>

where ``<output_file>`` is the path to your ORCA output file containing at least one 
``ABSORPTION SPECTRUM VIA ...`` table.

The plot will be displayed on screen, and will be saved as a PNG file in the current
working directory - both of these features can be disabled using optional arguments.

The plot data (spectrum and individual transitions) can also be saved as CSV files
using the equivalent ``orto gen abs`` command - this has exactly the same 
functionality as ``orto plot abs``, but saves the data instead of plotting it.

Intensities
***********

Several different intensity types can be plotted, controlled using the ``--intensities``
optional argument. The available intensity types are:

- ``velocity`` - Velocity Electric Dipole Strength
- ``electric`` - Length Electric Dipole Strength
- ``semi-classical`` - Oscillator Strength

Font and Figure Size
********************

``orto plot abs`` prints the figure width to the terminal in both inches and centimetres, to help
with inclusion in documents - simply set the size of the figure in your document to match
the printed width to ensure the figure is not resized and the font sizes remain correct.

The default font is `DejaVu Sans <https://dejavu-fonts.github.io/>`_, which is
a free, open-source font with good Unicode support. This can be changed 
using the environment variable ``orto_fontname``.

The default font size is 10 points, with 9 points for legend entries. This cannot be changed
by users at present.

Optional Arguments
******************

Additional command line arguments for ``orto plot abs`` can be listed by running

.. code-block:: console

    orto plot abs -h

Example
*******

The following example `orca` input file contains a TDDFT calculation for the 50 lowest
electronic excited states of a Pt(dcbpy)Cl2 complex, using the CAM-B3LYP functional
and the def2-TZVP basis set. The geometry is read from an external XYZ file.

.. tabs::

   .. tab:: `pt_dcbpy_cl2.inp`

        .. code-block::

            !cam-b3lyp def2-tzvp rijcosx def2/j verytightscf defgrid3

            %tddft
            DoNTO true
            nroots 50
            tda false
            end

            %maxcore 4000
            %pal nprocs <NUMBER_OF_CORES> end

            *xyzfile 0 1 pt_dcbpy_cl2.xyz

   .. tab:: `pt_dcbpy_cl2.xyz`

        .. code-block::

            29
            B3LYP/def2-svp optimised Pt(dcbpy)Cl2
            Pt         -2.10603723309141     -1.76139999377800      0.32205362234843
            Cl         -4.41146227455970     -1.74669241619429      0.59697475529693
            Cl         -2.10502179010104     -4.07582785465096      0.13756110796290
            C          -2.92456217882701      1.13988690089701      0.65062207372897
            C          -0.63244000642289      0.73989264236506      0.34551474696291
            C          -2.71401174780175      2.51294008880245      0.73472938758467
            H          -3.91318337839179      0.67851052162085      0.73175739192977
            C          -0.36073666450322      2.10693050213438      0.42179521760283
            C          -1.40917027638643      3.00949437876495      0.61858971113023
            H          -3.55847109644971      3.18495505823491      0.88885539548731
            H           0.65432836027357      2.49419182748761      0.33159492915462
            C           0.77883299892454     -2.60066522154205     -0.08790595343008
            C           0.39419252942759     -0.29704233435440      0.14077405262814
            C           2.14768217690127     -2.39755277969848     -0.23510866447774
            H           0.31334496812201     -3.59042133658750     -0.11094267016631
            C           1.75742601245953     -0.03249617221899     -0.00082029308278
            C           2.65009790957734     -1.09052050048040     -0.19131688315613
            H           2.81194252190957     -3.24940530712368     -0.38198971711096
            H           2.14924382000374      0.98425712170685      0.03317701336020
            N          -0.07582640025161     -1.57715423222968      0.09523034774620
            N          -1.91028163996228      0.27569810380746      0.46093974683498
            C          -1.07834619448940      4.46892909009037      0.69525373896754
            O           0.04082816748130      4.90968614676852      0.59668424345169
            O          -2.16492863365871      5.23430307880316      0.88597304353264
            H          -1.86568467867244      6.15929105898222      0.92393557221495
            C           4.10571488906422     -0.76716565695724     -0.33927290512918
            O           4.55146554538252      0.35377948418698     -0.30287927045076
            O           4.86147128139122     -1.86262870731143     -0.51709958926730
            H           5.78459301265098     -1.56777348652571     -0.60368014865466

The output of this calculation can be used with ``orto plot abs`` to generate an
absorbance spectrum

.. code-block:: console

    orto plot abs pt_dcbpy_cl2.out

By default, ``orto`` will use an x-axis with units of electron volt (eV), but this can be changed
using the ``--x_unit`` optional argument - for example, to plot the spectrum with an x-axis
in nanometers (nm), run

.. code-block:: console

    orto plot abs pt_dcbpy_cl2.out --x_unit wavelength

or to plot with wavenumbers (cm⁻¹) on the x-axis, run

.. code-block:: console

    orto plot abs pt_dcbpy_cl2.out --x_unit wavenumber

Additional optional arguments for ``orto plot abs`` can be listed by running

.. code-block:: console

    orto plot abs -h