=========
CCWatcher
=========

This is the README file of the python application ``ccwatcher``. The complete documentation can be found in the "docs" folder.

ccwatcher is a program to monitor the progress of computational chemistry calculations. It is (C) 2009-2013 Xaver Wurzenberger and free software under the terms of the GNU GPL V2 or later. Documentation and further information can be found int the "docs/" folder and on http://ccwatcher.sourceforge.net .

Use it like
    python ccwatcher.py [logfilename]
to parse and monitor a file or
    python ccwatcher.py -g [logfilename]
for the GUI, respectively.

This is version 1.3.


Dependencies
============
Mandatory:
* ``Python`` 2, ``Gnuplot`` 4
Optional:
* ``PyQt`` 4
* ``Avogadro``
* ``PyQwt``5

They have to be in the python path, except ``Gnuplot`` and ``Avogadro`` which's location has to be given to the ccw_setup tool.


Installing and Running CCWatcher
================================

For all OSs:
------------
There are basically three ways of getting ``ccwatcher`` to work on your machine. If neccessary, install ``Python`` 2.X from python.org, then:

1. Use packages or installers (like RPM, EXE, MSI, DEB, ...). You can check if they exist for your operating system on www.sourceforge.net/projects/ccwatcher. This is the most simple way.
2. Get an archive file from sourceforge (named sth like ccwatcher-XXX-src.tar.bz2), extract it to where you want it and use it 'as is'. This is the most reliable way if you care to install ``Python`` and Gnuplot (and probably ``PyQt`` and ``PyQwt``) yourself.
3. Get the same archive as in way 2, extract it and use the command
    python setup-all.py install
to build and install ccwatcher in your system. Make sure ``Python`` ``Gnuplot`` (and if you want the GUI also ``PyQt`` and ``PyQwt``) are installed previousely. Run ccw_setup.py from the installed location (/usr/bin in Linux, $PYTHON/Scripts in Win32) and enter Gnuplot path. Afterwards, you should be able to run ccwatcher.py or ccwacher-gui.py from the same folder.


Windows
-------
- If you use the EXE installer, make sure you have a 32bit Python 2.7.x installed - even on 64bit machines, I have not found 64bit Python to be working.
- If you need to install ``PyQt`` yourself, you can get it from http://www.riverbankcomputing.co.uk/software/pyqt/download or via PyPI (using ``setuptools`` or ``pip`` or ``ActivePython``s pypm). Unfortunately, there is no precompiled PyQwt for Py27, so you'd need to compile that yourself or email me for a copy. Please mind that I can't offer a lot of support for Windows as I don't own a copy.
-Run ccw_setup.py once after install.


Linux
-----
Linux users: The cleanest way to install the dependencies manually is your package manager. Use a command like "apt-get install python python-qt gnuplot avogadro" or "zypper install python python-qt gnuplot avogadro" or a graphic tool loke synaptic or YAST to install dependencies.
The rest should be no problem. You can simply copy everything to /usr/local/ and symlink to /usr/local/bin if there is no package for your distribution or use way 3 (setup-all.py install). In the latter case calling a command like update-desktop-database and update-menus (depends on your distro) to add ccwatcher (GUI) to your menu.


Mac OS X
--------
I don't own a mac, and don't know how ccwatcher or distutils behave on OS X at all, so unfortunately I can't offer a lot of help. Recently I have learned that it is not exactly a pleasure to get ``PyQt`` working on OS X. The best way may be to get it from PyPI (using setuptools/easy_install or pypm or so). Otherwise, please google how to do that; maybe this will help: http://code.activestate.com/pypm/pyqt4/. I'm not sure I can actually ever offer a .dmg or sth. Feedback is very welcome on this.


Post-installation/Running
-------------------------
Everyone: Please run ccw_setup.py in any case with a new ccwatcher version/copy/install, so the .ini file is updated too! You should be able to start ccwatcher by typing
    python ccwatcher.py
on some command line (if python is in your PATH). Mind that ccwatcher is not Python3(k) ready yet. If after installation you do not get a plot picture (but the message "No Plot yet" stays there), try choosing another scaling mode after parsing (i.e., select anything else from the drop-down-menubox): I've seen this to be necessary in rare cases.
CCWatcher offers several run-modes for single- and multifile cases. See the docs or type
    python ccwatcher.py -h
for help.




