Version 0.2, October 2021
Created by David Sousa
Inspired by G. N. Freitas' DENSPLOT (non-published).
Also inspired by Brett Bode's wxMacMolPlt
Powered by Python / NumPy / MatPlotLib
GPFPlot is a Python script which generates 2D plots of orbitals, electronic densities and GPF density partitioning associated to VB2000 output files.
- Minor changes for adjusting to VB2000 3.0 / GAMESS 2021 R2 versions.
- Fixed error in normalization formula.
- Fixed parse_overlaps when there is more than 10 groups.
- Fixed parse_gpf when SPHER keyword is on.
- Added feature to save EPS file and customize Figure DPI resolution.
- Fixed parse colormap in DENS mode.
- Allowed changing plot settings during the PROMPT session.
- Allowed gpfplot_figure.py to work outside the GPFPlot parent directory.
- Added option to set plot title.
- Uploaded project to GitHub.
- Initial release.
GPFPlot uses Python 3.x, so it needs to be installed in your machine. Additional requirements are the NumPy and MatPlotLib libraries. The current version of GPFPlot (0.2) was tested with Python 3.8.2, NumPy 1.17.4, and MatPlotLib 3.1.2.
If the above dependencies are installed, you should be able to run GPFPlot by entering the following command in your terminal (you must be in the directory which contains the script):
python3 gpfplot.py INPUTFILE
where INPUTFILE is a *.gpfplot valid input file.
Alternatively, you can create a link to the gpfplot.py script to your $PATH and run it directly. For example, on Linux:
chmod +x gpfplot.py
ln -s gpfplot.py ~/bin/gpfplot(assuming that the directory ~/bin is in your $PATH. Then you can run gpfplot from any directory by typing:
gpfplot INPUTFILE
in the terminal.
Currently, GPFPlot has 6 program modes: ORB, HFORB, QC, INT, TOT, and PROMPT.
ORB and HFORB are respectively for plotting VB2000 and GAMESS output orbitals.
QC, INT, and TOT are for plotting the total electronic density (TOT) or its quasi-classical (QC) or interference (INT) densities, for a given set of orbitals.
PROMPT is an interactive prompt mode, in which you can ask for the program to plot orbitals and/or densities.
For more instructions about the modes, please see the TUTORIAL.md file.
Although INPUTFILE must have the *.gpfplot extension, it is just a plain text in which INPUT VARIABLES are set.
In order to set variables, type the name of the variable, followed immediately by an equal sign =, followed immediately by the variable value. Do not use spaces before or after the equal sign. Each line must contain only 1 variable (or none). Variables can be defined in any order. If a variable is defined more than once in the INPUTFILE, the program reads ONLY the FIRST definition and ignore the rest. Lines starting with # are comments (ignored by the program).
| VARIABLE | DEFAULT VALUE | DESCRIPTION |
|---|---|---|
out_file |
- | Name of GAMESS/VB2000 output file with extension. |
dens_file |
- | Name of the density matrix file generated by VB2000. |
mode |
PROMPT |
Action which the program will perform. Possible values: PROMPT: interactive prompt.ORB N: plot Nth VB orbital.HFORB N: plot Nth HF orbital.QC X Y Z: plot quasi-classical density of orbitals X, Y, Z, ...INT X Y Z: plot interference density of orbitals X, Y, Z, ... (minimum of 2 orbitals).TOT X Y Z: plot total density of orbitals X, Y, Z, ... |
| VARIABLE | DEFAULT VALUE | DESCRIPTION |
|---|---|---|
plane |
xy |
Spatial plane where densities will be evaluated (options: xy, xz, yz, yx, zx, zy). |
gridp |
50 |
Number of points of the generated grid in each dimension (2D plot). |
xlim |
-1,1 |
Range for horizontal axis of the plot (Å). |
ylim |
-1,1 |
Range for vertical axis of the plot (Å). |
offset |
0.0 |
Value of the coordinate parallel to cartesian plane chosen for plotting. |
| VARIABLE | DEFAULT VALUE | DESCRIPTION |
|---|---|---|
c_lines |
yes |
Option for plotting isovalue lines (yes/no). |
c_fill |
yes |
Apply filled contour plot (yes/no). |
c_label |
no |
Include labels int the isovalue lines (yes/no). |
color_f |
coolwarm (mode = ORB, HFORB or PROMPT)seismic_r(mode = QC, INT or TOT) |
Colormap for filled contour plot. See section [6.1] for available colormaps. |
color_l |
- | Colormap for isovalue lines. If not set, lines will be plotted in black. See section [6.1] for available colormaps. |
nconts |
10 |
Number of contour isolines and/or color changes in filled contour plot. |
min_c |
-1.0(mode = ORB, HFORB or PROMPT)-0.1(mode = QC, INT or TOT) |
Minimum value for contour isovalue lines. |
max_c |
1.0(mode = ORB, HFORB or PROMPT)-0.1(mode = QC, INT or TOT) |
Minimum value for contour isovalue lines. |
auto_c |
no |
If set yes, it defines min_c and max_c automatically according to the range of grid values. |
p_unit |
angs |
Length unity in the plot axes. If not set angs (Å), plot will be shown in atomic units (Bohr radius). |
draw_atom |
plane |
Which atoms will be shown on the plot. Possible values: all: All atoms are projected on the plotted plane and shown on the plot.plane: Only atoms on the plotted plane and 0.1 Å or less away from the plotted plane are shown on the plot.none: No atom is shown on the plot. |
draw_name |
yes |
Whether atoms are represented on the plot by name (the labels given in $DATA section from GAMESS). If "no", atoms are represented by a black dot. |
title |
"" |
Title of the plot. |
| VARIABLE | DEFAULT VALUE | DESCRIPTION |
|---|---|---|
save_png |
- (300) | File name for saving the plot as a *.png image. The variable is optional and is not used if mode = PROMPT. The second argument must be separated by a blankspace and corresponds to the figure resolution in DPI (dots per inch). The default value is 300. |
save_eps |
- (300) | File name for saving the plot as a *.eps image. The variable is optional and is not used if mode = PROMPT. The second argument must be separated by a blankspace and corresponds to the figure resolution in DPI (dots per inch). The default value is 300. |
save_txt |
- | File name for saving the grid points of the plot in a text file (*.txt). The variable is optional and is not used if mode = PROMPT. The format specification is quite intuitive and can be seen in the tutorial example. |
Please check the file TUTORIAL.md for further information.
Matplotlib provides a huge number of colormaps. They can be checked out here.
The recommended colormaps for using in GPFPlot are shown in the image examples/useful_colormaps.png. My personal favorite is coolwarm for plotting orbitals and seismic_r for plotting densities. These are the default colormaps mentioned above.
Hint: all colormaps can be reversed by adding _r at the end of its name.
This script is an extra resource, used for generating high-quality figures intended for publishing in papers or books. The figure may contain more than one orbital or density plot.
Check TUTORIAL.md for information about how to use it.
I intend to work on improvements every time I manage to have time for work on it (which probably is not very often). Although, any suggestions are welcome.
Since the program has not been fully tested, it probably may have bugs.
You can send questions and suggestions to Dr. David Sousa. I will be glad to answer any questions and receive any suggestions on improving the program.