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 as 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 currently
using the original code 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.

Lengthy operations (e.g. grida data generation for orbitals) are performed
in separate threads and can be interrupted by the user at any time.

Export to POV for off-line rendering.


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

The binary distributions of Molekel are being tested on SuSE linux 10.x,
Mac OS X 10.4 (Intel) 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.
- PostScript export
- Viewer for calculated vibration spectrum with ability to export
  the displayed diagram as an image, PostScript or text
  (in e.g. GNUPlot format)


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 molecules with thousands of atoms is currently
             very slow; this is due to the fact that data are usually
             read more than once and in same case an internal conversion
             is required e.g. xyz --> mol.
             The reason for this behavior is that currently three data
             structure  holding information about molecular data cohexist
             in the MolekelMolecule class, and each of this structure
             is filled with data read from file:

             - Old Molekel's Molecule struct: used by the code that computes
                                              molecular orbitals.

             - OpenBabel OBMol class: main data type for storing molecular
                                      data; will hold all the information
                                      currently stored into the Molecule struct.

             - Molecular Inventor' ChemData: used for rendering; has to be
                                             filled with data read from a mol
                                             or pdb file, will eventually be
                                             created directly from OBMol instead
                                             of re-reading data from file

             Also, not only the data are read but some processing is required to
             compute bonds and other information and this happens twice:
             one for ChemData and another for OBMol.

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 the central
    widget is painted with a white border.
    On Mac the Animation-Preferences menu item is displayed under
    System Menu - Preferences;  this is a default behavior for Qt based
    applications on Mac, it wil be fixed by changing the text 'Preferences'
    in the animation menu.


