The Python Script "PLOT-multitask.py"

by Ronaldo Rodrigues Pela

Purpose: The script PLOT-multitask.py is employed in all tutorials with real-time TDDFT calculations [1] to post-process outputs and produce relevant plots. Here, we detail how this script works.

General description:

PLOT-multitask.py can be used basically to process and to plot data from one or more files. The first case is tagged in the script as a preprocess mode, because it is intended to work as a previous step followed by a new call to plot what has been processed.

Considering these two functionalities, the arguments taken by PLOT-multitask.py can be classified in 4 groups:

  • mandatory arguments;
  • general optional arguments, common for plotting and preprocessing;
  • optional arguments for preprocessing;
  • optional arguments for plotting.

Mandatory arguments:

Argument Shortcut Description
--files -f name of input files

General optional arguments:

Argument Shortcut Default Description
--columns -k 0 1 (for each file given) columns to read in each file (x and y). A pair of integers must be given for each file. It is overwritten by options like: --x, or --xy
--skip -s 0 (for each file given) number of lines to skip (ignore), before reading the data (must be given for each file)
--scale 1.0 1.0 two floats with a scaling factor for the data read (x and y from all files are scaled with these factors)
--handle_complex 'no' if/how to treat the complex numbers (only for y-data). Possible choices are 'no', 'full', 'imag', 'real', and 'abs'. This can be useful e.g. when plotting the imaginary part of the dielectric function.

Optional arguments for preprocessing:

Argument Shortcut Default Description
--preprocess triggers the preprocessing mode. A maximum of one of the following options can be provided: --fourier, --get_efield, --get_eps, --add, --sub. The argument --scale can also be employed
--output -o output.txt name of output
--add adds the data read from two files (only the columns treated as y are added)
--sub same as add, but subtracts, first y minus second y
--get_efield calculates the electric field, given a file containing the vector potential
--fourier obtains the fast fourier transform applying, if requested, a smoothing filter
--wcut 0.0 broadening used for the smoothing filter
--get_eps obtains the dielectric function, using the first file with the vector potential and the second file with the current density. One of the following options can be given: --xx, --xy, …, --zz. Default is --xx.
--ab --xx ab component of the dielectric function. a and b must be x, y or z. To be used together with --get_eps.

Optional arguments for plotting:

Argument Shortcut Default Description
--jind intended to be used when plotting the current density. It triggers the y-label as 'Current Density [a.u.]' and considers --x (see next option) as default
--x, --y, --z tag for the component to be plotted. The meaning is to set --columns to 0 1, 0 2, or 0 3, respectively. If --get_efield is used, then these numbers are 0 2, 0 4, and 0 6.
--nexc intended to be used when plotting the number of excitations. It triggers the y-label as '$N_{exc}(t)$', considers the default of 0 2 for --columns and 1 for --skip.
--imag_eps intended to be used when plotting the imaginary part of the dielectric function. It triggers the x- and y-labels, and multiplies the x-data by 27.211396132 (conversion factor: Ha to eV)
--real_eps same as before, but for the real part of the dielectric function.
--xlim two floats as limits for the x-axes
--ylim two floats as limits for the y-axes
--xlabel 'Time [a.u.]' label for the x axis
--ylabel label for the y axis
--caption -c name of files caption to be shown in the legend box (one for each file)
--legend_position 'upper right' defines the position of the legend. Options are: 'upper right', 'lower right', 'upper left', 'lower left'
--hide_legend prevents the legend to be shown. Automatically set when only one file is used for plotting
--semilog triggers a semilog plot

Examples:

☛ Tutorial: Real-time TDDFT

Here, we recheck the usage of PLOT-multitask.py in the tutorial Real-time TDDFT, starting with

$ PLOT-multitask.py --jind -f JIND.OUT --x

This plots the data corresponding to the columns 0 and 1 of the file JIND.OUT. Also --jind triggers 'Current Density [a.u.]' as label for the y-axis. The label for the is considered the default one: 'Time [a.u.]'. The same effect can be reached by:

$ PLOT-multitask.py -f JIND.OUT -k 0 1 --ylabel 'Current Density [a.u.]'

Similarly, the command

$ PLOT-multitask.py --nexc -f NEXC.OUT

plots the data from columns 0 and 2 of the input NEXC.OUT skipping the first line. The label of the y-axis is $N_\textrm{exc}(t)$. This command could be replaced by

$ PLOT-multitask.py -f NEXC.OUT -k 0 2 -s 1 --ylabel '$N_\textrm{exc}(t)$'

The last command in this tutorial

$ PLOT-multitask.py --jind -f test1/JIND.OUT kpt16/JIND.OUT --x -c '4x4x4' '16x16x16'

is equivalent to

$ PLOT-multitask.py -f test1/JIND.OUT -k 0 1 -f kpt16/JIND.OUT -k 0 1 -c '4x4x4' '16x16x16' --ylabel 'Current Density [a.u.]'

or

$ PLOT-multitask.py -f test1/JIND.OUT kpt16/JIND.OUT -k 0 1 -k 0 1 -c '4x4x4' '16x16x16' --ylabel 'Current Density [a.u.]'

Note that, when used, -k needs to be provided as many times as the number of files.

☛ Tutorial: Simulating pump-probe spectroscopy with RT-TDDFT

Now, we proceed with the tutorial Simulating pump-probe spectroscopy with RT-TDDFT. The command

$ PLOT-multitask.py --preprocess --sub -f pump-probe/JIND.OUT pump/JIND.OUT -o DIFF.OUT

takes the files pump-probe/JIND.OUT and pump/JIND.OUT as input, read the columns 0 1 from both (default of --columns), and subtract the column 1. The convention is "first file" minus "second one". The output, containing the column 0 of pump-probe/JIND.OUT and the result of the subtraction, is stored in DIFF.OUT.

Then, with the command

$ PLOT-multitask.py --jind -f pump/JIND.OUT probe/JIND.OUT pump-probe/JIND.OUT DIFF.OUT --legend 'lower right'

we can plot the the data from the second column vs. the first column from the files: pump/JIND.OUT, probe/JIND.OUT, pump-probe/JIND.OUT, DIFF.OUT. With --legend 'lower right', we place the legend in the lower part of the panel.

When we employ

$ PLOT-multitask.py --preprocess --get_eps --xx -f AVEC.OUT -f JIND.OUT --wcut 0.05 -o EPSILON.OUT

we obtain the xx tensor-component of the dielectric function and output it into EPSILON.OUT, following Eq. (5) of the tutorial Simulating pump-probe spectroscopy with RT-TDDFT. The first input file is expected to contain the vector potential, whereas the second one, the current density. The broadening for the Fourier transform is given by --wcut (in this case, 0.05 Ha).

The following usage of the script

$ PLOT-multitask.py --preprocess --get_eps --xx -f probe/AVEC.OUT -f DIFF.OUT --wcut 0.05 -o EPSILON-DIFF.OUT

is analogous to the one commented before.

Finally, with

$ PLOT-multitask.py --imag_eps -f probe/EPSILON.OUT EPSILON-DIFF.OUT --xlim 5 30 --ylim 0 1

it is possible to use the files as input plot the imaginary part of the dielectric function. assumed to be in the column 1, vs. the energy, assumed to be in the column 0. The first column is multiplied by 27.211396132, because we assume that the energy in the input was given in Ha, and we wish to plot it in eV. The same effect would have been obtained with

$ PLOT-multitask.py --handle_complex imag -f probe/EPSILON.OUT EPSILON-DIFF.OUT --xlim 5 30 --ylim 0 1 --ylabel 'Im($\varepsilon$)' --xlabel 'Energy [eV]' --scale 27.211396132 1

☛ Tutorial: Studying higher-harmonic generation using RT-TDDFT

We detail here the uses of PLOT-multitask.py in the tutorial Studying higher-harmonic generation using RT-TDDFT. The first command:

$ PLOT-multitask.py --preprocess --get_efield -f AVEC.OUT --x -o EFIELD.OUT

is used to obtain the x component of electric field and write it into EFIELD.OUT, taking as input a file with the vector potential AVEC.OUT.

Calling the script as

$ PLOT-multitask.py --preprocess -f EFIELD.OUT --scale 1.0 0.1 -o EFIELD-SCALED.OUT

makes it to read EFIELD.OUT, taking the data from the columns 0 1 (default of --columns), scaling them by 1.0 and 0.1 (columns 0 and 1, respectively), and outputing the result into EFIELD-SCALED.OUT.

With

$ PLOT-multitask.py -f PVEC.OUT EFIELD-SCALED.OUT -c '$P(t)$' '$E(t)/10$' --ylabel 'Field [a.u.]'

we plot columns 0 and 1 (default of --columns) from the files PVEC.OUT and EFIELD-SCALED.OUT. The caption of each curve is provided by -c '$P(t)$' '$E(t)/10$'. And the label of the y-axis is 'Field [a.u.]'

When we employ

$ PLOT-multitask.py --preprocess --fourier -f PVEC.OUT -o P.OUT --wcut 0.025

we obtain the fourier transform, taking as time the column 0 of PVEC.OUT. Column 1 has the data to be transformed, considering a broadening of 0.025 Ha. The output with frequencies and the transform is written into P.OUT.

The command

$ PLOT-multitask.py --preprocess -f P.OUT --scale 4.0 27.52546105147261 --handle_complex abs -o P-SCALED.OUT

scales columns 0 and 1 from P.OUT by 4.0 and 27.52546105147261, respectively. Here the argument --handle_complex abs makes sure that the data from column 1 is complex, and we consider only its absolute value. If we wanted no further treatment of the complex data, we could have used --handle_complex full.

When used as

$ PLOT-multitask.py -f P-SCALED.OUT --xlabel '$\omega/\omega_0$' --ylabel '$P(\omega)/E_m$' --xlim 0 7 --ylim 1e-5 1 --semilog

the scripts provides a semilog plot of the columns 0 and 1 from P-SCALED.OUT. We provide extra information for the panel, such as: the label for the x and y axes, and the limits for both axes.

The last use in this tutorial

$ PLOT-multitask.py -f ampl-1/P-SCALED.OUT ampl-2/P-SCALED.OUT ampl-3/P-SCALED.OUT --xlabel '$\omega/\omega_0$' --ylabel '$P(\omega)/E_m$' --xlim 0 7 --ylim 1e-5 1 --semilog

is similar to the one commented before, with the difference that more data is plotted in the same figure.

Bibliography
1. Tutorials in which this script is used:
Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License