This is the temporary documentation of the ccwatcher program. Expect this to be incomplete.
---


Introduction
CCWatcher is a program to monitor the progress of computational chemistry calculations during their runtime, to parse them and plot their energy values. It is free software (GPL).


License and copyright
ccwatcher is Copyright (C) 2009-2012 Xaver Wurzenberger <xaverxn at users.sourceforge.net>.

This program is free software; you can redistribute and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

Toghether with the ccwatcher core application there may be material or code that is differently copyrighted and licensed. All licensing information (including those who do not cover the core application) can be found under doc/, together with copies of the licenses.


Technical properties

ccwatcher is a python 2 program which uses the cclib as parsing backend and gnuplot for plotting energy graphs (mandatory dependencies). Next to the CLI (command line interface) also features a Qt4 GUI (optional dependencies).
Current version is 0.9 (beta state); exact (sub-)version number can be retrieved by starting ccwatcher with the "--version" option.



Dependencies

Mandatory:
    Python > 2.4 (tested: 2.5, 2.6)
    Gnuplot 4 (tested: 4.2 patchlevels 2 and 6)
    which.py (included)
    cclib (included)
    numpy ("numeric python"; packages often named "python-numpy" or "python-numeric"), needed for cclib
Optional:
    Qt 4 (tested: 4.4.3-1, 4.7.0-4)
    PyQt 4 (tested: 4.4.2-4, 4.8.0-1)
    Avogadro

They have to be in the python path (sys.path) so they can be found by the import statements; except Gnuplot and Avogadro which have to be found by ccwatcher (see setup.py; esp. win32 users read below). For Windows users, installing PyQt4 is enough, you don't need the full Qt installation.



Platform independence

CCWatcher can run on most platforms and OSs since python and all of the dependecies are highly platform-independent. However, it is only supported on linux and x86 /x64 since I don't own other architectures or OSs. In fact, I have made some test runs on Windows systems but haven't had a chance to test OS X, BSD, Solaris or other OSs.

Windows users: Since gnuplot can't plot in ascii on the command line in win32, you can only get plots in GUI mode.



Python and starting ccwatcher

ccwatcher is a Python 2 application. It is NOT Python 3(k) ready. So, if you see a Python 3 warning when you type
python ccwatcher.py
you'll need to start ccwatcher probably by sth like
python2 ccwatcher.py
Linux users may of course alter the "magic line" in ccwatcher.py to point to their Python 2 executable and just exec sth like
/path/to/ccwatcher.py



Files

You can find test files in the main directory and some documentation under doc/ (surprising, isn't it?). In the latter you will find also licensing info as well as release-relevant stuff (changelog,todo,...).



Installing

- Windows users: You should just copy the downloaded (unzipped) folder to their "programs" folder (wherever that is)

- Linux users: From version 0.9.4 on, I provide an experimental means of installing ccwatcher by the python module 'distutils'. If that is installed, you may execute "python setup.py install". Mind however that this (still) very basic and in-elegant, and I'm not sure setuptools will ever be really good for this. Please look for distribution packages first (in your package manager or on sourceforge) because that's the much cleaner way.

- Mac users: I don't know how ccwatcher or distutils behave on OS X at all, so unless you know what you are doing, don't try to install ccwatcher.

- All: Whenever you install a new(er) version of ccwatcher, make sure to execute setup.py afterwards! Also, if you do not get a graphical plot in the GUI, choose another scaling mode from the drop-menu after parsing (just once).



Parsing

The cclib backend tries a filetype detection (based on some keywords). 
- If it detects a non-Gaussian/ORCA/GAMESS(US)-type file, it will parse the file itself, putting out just the "SCF Energies".
- If it detects a Gaussian-type file, cclib will put out SCF Energies and ccwatcher will analyze and parse the other parts.
- If it can't detect anything, ccwatcher will terminate. If you want it parsed as a Gaussian-type file, you can use the "-f" switch ("force gaussian").

Mind that this means that some cclib functionality isn't working at the moment, like remote (e. g., http) file parsing.

Multi-file parsing:
Parsing more than one file can be activated via command line or GUI. Modes available:
 1 Plot the SCF energies as seperate lines (for comparison).
 2 Plot just one line, with the SCF energies and cyle numbers added up (for consecutive calculations).
Command line: Start ccwatcher with the flag "-m <mode>", where <mode> is one of the above, and ccwatcher will parse all files you give it. You won't get text output from anyone but the last, but the plot will show all of them.
GUI mode: Just choose several files in the "Open files..." menu. ccwatcher asks for multi-parsing mode (see above) afterwards. Also, you can choose which of them to actually monitor and text-parse.
Please mind that the "GUI way" has the disadvantages of not choosing files from different folders and also not fully controlling the file order, so use the command line if you want the Super Cow Powers!


CCLIB backend

cclib is a great library to extract chemical information from some log files of QM calculation software. See cclib.sourceforge.net for further info.
ccwatcher was intentionally named in analogy to cclib, however there's no overlap between the people behind these two. In "business terms": ccwatcher is not associated with cclib in any way. 



Plotting

ccwatcher uses gnuplot via a small self-written interface. Shell/CLI plots are done using gnuplot's terminal 'dumb', gui plots using terminal 'png' via file. You can save a png file by right-clicking the plot image.

SCALING MODES

ccwatcher currently offers seven modes for scaling the y axis of its plots. The x axis is scaled automatically, either by gnuplot or by ccwatcher algorithms.
0 Gnuplot autoscale
  Just what gnuplot's "set autoscale y" does.
1 Customized scaling acc. to config settings
  The variable num_plot_perc_ysurplus*100% is the surplus added above and below the lowest and highest points.
2 Highest point zeroed [Hartree]
  The highest SCF energy point (i.e., the least negative) is set to zero and all others are given as values relative to that one.
3 [kJ/mole] scale
4 Highest point zeroed [kJ/mole]
  See mode 2
5 First point zeroed [kJ/mole]
  See mode 2, only here is the first point zero'ed and not the highest (reference points are not taken in account)
6 Lowest-points scale [kJ/mole]
  Like 4, but with zooming to the lowest points (lowest num_perc_plot_zoom*100%, but at least two points).
7 Even more zoom
  Like 6, but even more zoomed in
8 Ultra zoom
  Like 6, but much more zoomed in


Keywords
The following messages found in gaussian log files led to the inclusion of the keywords:

termination :                "Normal termination" or "Error termination" marks when Gaussian exits
SCF Done :                   Normal SCF energy parsing
Low frequencies :            Normal check for bad frequencies
Number of steps exceeded :   Abundant error message
Full point group :           Normal point group check
Converged? :                 Special marker for the beginning of the convergence check, not parsed itself
The SCF is confused. :       Standard message for SCF problems
Gaussian 03: :               Write version number
Gaussian 98: :                        "
Rerun with SCF=IntRep. :     Rare message for SCF problems
Warning: :                   Missing basis warning, e. g. "Warning:  center   2 has no basis functions!" (The colon sorts out lots of false positives)
found in this molecule :     Assignment of a basis to a non-existent element sort, like "No Br atoms found in this molecule"
Atomic number out of range : Inapropriate basis chosen: "Atomic number out of range for 6-31G basis set"
run aborted :                Optimisation algorithm can't find its way further: "No lower point found - run aborted."
run terminated :             SCF algorithm didn't converge: "Convergence failure -- run terminated."

Orca:
NOT CONVERGED: As is SCF NOT CONVERGED, LOCALIZATION NOT CONVERGED


Troubleshooting

Possible error messages:

>Traceback (most recent call last):
>  File "ccwatcher.py", line 23, in ?
>    ccwatcher_py.main(__file__)
>  File "/home/klu11/ccwm/ccwatcher_py/__init__.py", line 39, in main
>    logging.basicConfig(level = logging.INFO, format = '%(levelname)s: %(message)s', stream = sys.stderr)
>TypeError: basicConfig() takes no arguments (3 given)

I guess this indicates an outdated python version. I've seen this happen on Python 2.3.5. Please update.

> (...)
> TypeError: eval() arg 1 must be a string or code object

This happens sometimes when you update ccwatcher but do not execute "setup.py" afterwards. Please execute setup on every update/install!

If you do not get a plot in GUI mode ("No plot yet" stays): Choose another scaling mode from the drop-down-menubox after parsing.


Testfiles and testing ccwatcher
Three testfiles are contained in the main directory of ccwatcher. You can use 'testfile.log' or 'testfile2.log' to simulate gaussian file handling in every way you want, and both of them to simulate multifile handling, e.g.:
python ccwatcher.py -m 1 -s 5 -g testfile.log testfile2.log
'testfile3.log' is a special case to test the force-gaussian mode for broken gaussian log files that cclib won't handle:
python ccwatcher.py -f testfile3.log

To test other use cases, there are more testfiles available in the files section of the sourceforge project homepage (like, output from other comp chem software, zipped files, both of which can only be opened by the cclib backend). Even more testfiles can be found on the homepages of cclib, openBabel, BlueObelisk.

Doctest/Unittest:
There are no unittest/doctest methods implemented.