Molekel version 5.0.0
---------------------

Molekel is a free, open-source molecular visualization program distributed
under the terms of the GNU General Public License as published by
the Free Software Foundation version 2 of the license.
You should have received a copy of the GNU General Public License
along with this program (look for the file 'license'); if not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA  02110-1301, USA.

History
-------

The first version of Molekel, based on IRIX GL, was developed at the
University of Geneva and ETH Zurich by Peter F. Flkiger.
The program was then further developed (releases 3.0 to 4.3) by
Stefan Portmann using GLUT and Glui for the UI.

In 2005 John Biddiscombe at CSCS started to work on the first open
source version (4.6) of the program rewriting part on the code in C++
and using Trolltech Qt libraries to achieve native look and feel on
Linux, Mac and Windows.

In June 2006 Ugo Varetto at CSCS took over the responsibility for
Molekel and started to write the code for version 5.0 at the end
of July 2006.
Given the availability of several opensource C++ toolkits for 3D
visualization and import/export of molecular data it was decided
to use some of these toolkits within molekel to access additional
functionality and avoid maintaining portions of the code.

The current version of Molekel has a dependency on the following
tookits:

- Qt (GUI)
- VTK (high level 3D graphics tasks and 3D widgets)
- OpenBabel (I/O)
- OpenInventor & MolecularInventor (lower level 3d rendering)

Since no opensource C++ library was found to extract electronic
structure information from the output of Gaussian, GAMESS
and other programs, the current version of Molekel is
using the original code (with minor changes/fixes) to read some file
formats.
The mid/long term plan is to move all the I/O code into OpenBabel
OBConversion objects and store the read information into instances
of classes derived from OBGenericaData.

Main Features
-------------

Import/export of molecular data using OpenBabel, refer to the OpenBabel
website for a complete list of supported formats.

Export snapshots as tiff/jpg/png images or animations in MPEG/AVI format.

Display of any number of molecules with different rendering styles
for atoms, bonds and residues.

Animation of vibration modes and trajectories.

Generation of isosurfaces from grid data with user defined values for
bounding box and sampling step; orbitals and density matrices currently
supported.

Generation of Connolly dot and Van der Waals surfaces.

UI features to interact with atoms, bonds, residues and surfaces; ability
to compute angles and distances.

Export to POV for off-line rendering.

Export geometry to postscript and PDF.


System Requirements
-------------------

The binary distributions of Molekel are being tested on SuSE linux 10.x
x86, Fedora Core 5 x86, Mac OS X 10.4 and Windows XP and 2000.

Building Molekel from source requires the following tools/libraries.

- CMake: http://www.cmake.org
- VTK 5.x: http://www.vtk.org
- Trolltech Qt 4.x: http://www.trolltech.com/products/qt
- OpenBabel 2.x: http://openbabel.sourceforge.net
- Open Inventor: e.g. http://www.coin3d.org
- OpenMOIV (Molecular Inventor): http://www.tecn.upf.es/openMOIV
- MinGW/MSYS/latest binutils (Windows only)

Molekel should compile without problem on any system for which the
above libraries/tools are available.

On Windows compilation has been tested only wih MinGW since the
opensource version of Qt is only available for MinGW on this platform.

Please refer to the build.txt file for detailed information on the
build process. Note that some precompiled libraries might be available
on the Molekel website.


Roadmap
-------

The following features are currently being considered for inclusion
in future versions of Molekel.

- Full integration with OpenBabel i.e. no more legacy I/O code
  and creation of Molecular Inventor data from OpenBabel data.
- Plugin architecture and in general complete decoupling between
  GUI and rendering/analysis/IO engine: UI won't have any direct
  reference to a particualr engine implementation.
- Viewer for calculated vibration spectrum with ability to export
  the displayed diagram as an image, PostScript or text
  (in e.g. GNUPlot format)
  
Refer to Molekel's Website for up to date information.  


Support/Contribution
--------------------

You are more than welcome to use Molekel and provide feedback,
report bugs and ask for new features.

Several tools accessible through the main Molekel development
website (http://bioinformatics.org/molekel) are available.

- Bug Tracker: when you submit a bug please make sure you
               also write your operating system information
               and Molekel version.
               When submitting a compilation bug please include:
               - Operating System (e.g. Mac OS X 10.4.7)
               - Hardware Info (e.g. Intel Core Duo)
               - Molekel version
               - Detailed information on the versions of each
                 tool/library used

- Mailing Lists: some mailing lists are available:
                 - announce: information about new releases and updates
                 - users: users of Molekel can use this list
                          for anything they want, from reporting
                          problems to asking for new features.

- Forums: forums are available for online discussion of any
          Molekel related topic.

- Email: plese use the form on the website to send messages


Issues
------

Data formats: given the amount of available resources and sample data
              extensive testing in being performed mainly on the
              following data formats:
              Gaussian log/out, PDB, XYZ, MOL.

Performance: reading PDB molecules is currently slow and it seems
             there are issues with the OpenBabel PDB reader; a new
             custom PDB reader is in development
             (try to e.g. convert 1AON.pdb to mol and read the converted
             file with any molecular visualization program).

Memory Management: no issues to report at this time but a move to smart pointers
                   (both intrusive and non-intrusive) is required to simplify
                   several parts of the code; a custom implementation of
                   std::tr1::shared_ptr and boost::intrusive_ptr will be
                   provided.
                   Note that it is not possible to provide thread safe access
                   to the reference counter without a multiplatform thread
                   library.

Multithreading: Qt provided classes are being used for thread management.
                We need to look at using a multiplatform threading library.
                VTK is not thread safe and it doesn't look it's possible to
                perform operations (e.g. generate surfaces) in a separate thread
                and interrupt the operation without stopping the thread
                explicitly.

UI: a few things need to be changed in the UI, some windows displayed
    as modal dialogs should have the option to be displayed as
    non-modal windows and/or docking widgets; this will be possible only after
    smart pointers are introduced to avoid complex clean-up and notification tasks
    each time a molecule is deleted.
    To make the Mac GUI more Mac-like no docking widget should be used, widgets
    currently displayed  as docking widgets should be displayed in the drawer.
    On Mac the brushed metal style seems to have some problems since sometimes
    the central widget is painted with a white border and the toolbar always
    shows a white line on the top.

