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).
This is version 1.3.



License and copyright
---------------------
ccwatcher is Copyright (C) 2009-2013 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 gnuplot (CLI, GUI) or (py)qwt (only GUI) for plotting energy graphs. Next to the CLI (command line interface) also features a Qt4 GUI (optional dependency).
Current version is 1.3 (beta state); exact (sub-)version number can be retrieved by starting ccwatcher with the "--version" option.



Dependencies
------------
Mandatory:
    Python 2 (tested: 2.4 - 2.7) - python.org
    Gnuplot 4 (tested: 4.2 patchlevels 2 and 6) - gnuplot.info
Optional:
    Qt 4 (tested: 4.4.3-1, 4.7.0-4) - qt.nokia.com (don't just download - read below)
    PyQt 4 (tested: 4.4.2-4, 4.8.0-1) - http://www.riverbankcomputing.co.uk
    PyQwt 5 - http://pyqwt.sourceforge.net/
    Avogadro - avogadro.openmolecules.net

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 ccw_setup.py; esp. windows users read below). For Windows users, installing PyQt4 is enough, you don't need the full Qt installation.



Platform and architecture (in)dependence
-----------------------------------------
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 or AMD64 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. ccwatcher does run on Windows 7 64bit, but it seems you need the 32bit Python version for that. I do not know about Windows 8.

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



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
For Windows, there are several python "distributions", i.e. software packages with some python version and helper programs. Read the first two paragraphs from http://www.fredshack.com/docs/python.html if you're interested; otherwise just stick to python.org .


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
----------
Please see README.txt.

Also, whenever you install a new(er) version of ccwatcher, make sure to execute ccw_setup.py afterwards! Also, if you do not get a graphical (gnuplot) plot in the GUI right away, change the scaling mode via the drop-menu and change it back again.



Parsing
-------
ccwatcher will read the arguments given and try to open any files given.
- If it is not given any file, it will look for a turbomole 'gradient' file. If it does not find one, it will try to open the most recent .out or .log file. If there is none of them, it will try to guess if it is a Turbomole scan job and look for 'gradient' files in numbered subdirectories.
- If it detects a Gaussian/ORCA/ADF/Jaguar/Molpro/NWChem-type file, ccwatcher will analyze and parse it.
- 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").

Zipped files, BZip2 and GZ files will be read through python interfaces. Remote files (e. g. http) are not supported ATM.

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). Parse the last file only.
 2 Plot just one line, with the SCF energies and cyle numbers added up (for consecutive calculations). Parse the last file only.
 3 Plot just one line, with the SCF energies and cyle numbers added up (for consecutive calculations); really parse every file, i.e. output messages and wait for it to finish.

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!

The criterion to stop parsing is always the file age (ATM 60 minutes without changes), and in the respective computational chemistry package parsing modes also special logfile lines, e. g. "Normal termination" in the case of Gaussian.

Turbomole is a special case because it distributes information over various files and, when scanning, even folders. ccwatcher tries to parse the 'gradient' and 'job.last' files both, and has the special termination criterion of not finding a 'GEO_OPT_RUNNING' file.

CCWatcher can be instructed to not monitor the file, but only parse it once by the '-o' flag. Multifile loads should not be affected by this.


CCLIB 
-------------
cclib originally served ccwatcher as a backend for reading computational chemistry logfiles, at may do so again in future. cclib is a great library to extract information out of these files. 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
--------
There are two plotting systems in ccwatcher: Qwt and Gnuplot. Gnuplot is the only way to do ASCII plotting (at least it can do so on Linux), while the GUI can use either: Qwt gives you free mouse zooming and un-zooming while gnuplot is somewhat static but may be better to produce pictures.

Qwt: Use drag-and-drop to draw a zoom rectangle on the plot and qwt will enlarge the content. The right mouse button zooms step for step out again. Scaling modes are the same as with gnuplot modes 1-5. Please mind that if you call for modes 0 and >= 6 via command line flag you will be redirected to modes 1 and 5, respectively.

Gnuplot: 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 [Hartree] scale 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
    9 Recent points zoom
    10 Last 8 points



Keywords
--------
Some of the keywords are documented in docs/keywords.txt.



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 "ccw_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.

Error messages you can ignore:
    "QInotifyFileSystemWatcherEngine::addPaths: inotify_add_watch failed: Datei oder Verzeichnis nicht gefunden
    QFileSystemWatcher: failed to add paths: (...)/ibus/bus"


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 file; use
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. Even more testfiles can be found on the homepages of cclib, openBabel, BlueObelisk.

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


Known bugs and problems
------------------------
Removing tmpfiles (gnuplot instructions) SOMETIMES does not work on win32. Not even after reboot they're gone - Not sure in which cases that happens.

Unicode filenames are not supported (see Low-Priority ToDo item).

