* Updates & Information
   - For updates and information, see http://www.iboview.org

* Prerequisites
   - OpenGL 4.0 drivers (due to system-specific hacks it might work on
     Intel integrated graphics from Sandy Bridge systems onwards, which,
     in the year of 2014, still are restricted to OpenGL 3.3 on linux.
     But no guarantee.)
   - qt4-devel (QT4 development libraries) or
     qt5-devel (QT5 development libraries)
   - Intel Math Kernel library (MKL) or other working 64bit BLAS/LAPACK
     (we recommend OpenBLAS if Intel MKL is not available. The program
     will work with netlib reference blas, but be very slow in
     computations)

* How to compile
   - setup the linker line for MKL (or OpenBLAS) in main.pro (line 1 of
     main.pro). Needs adjustments of path of MKL libraries unless a
     correct MKLROOT environment variable is set.

   - run: /usr/bin/qmake-qt4 -o Makefile main.pro && make -j 4
     (or run the corresponding qmake from qt5 or qmake without any
     qualifiers (qt4 or qt5) if available)

   - if this worked, try
      'cd examples && ../iboview feco3no_ibos_exp2.js'
     to test.

* Known problems
  - On Mac, the alpha channel has to be disabled completely because
    MacOS uses it for blending the view itself (?!). Run iboview with
    -disable-alpha and -disable-backfaces commandline arguments for
    workarounds.

  - The embedded MicroScf program is still quite limited (no open-shell,
    no ECPs, no semi-direct SCF, no convergence stabilizers beyond DIIS,
    only PW91 and PBE functionals). Will be fixed later.
    It is good at tracing simple organic compounds, however.



* Input & Notes
  * The program can read the following file types:
    - .xyz files (with one or multiple geometries, with or without
       energy and gradient information)
    - molden files
      (one geometry only)
    - Molpro xml files (.xml) from Molpro 2012 and Molpro 2015
      (one geometry only)
    - Its own script files (.js)
  * Using with Molpro:
    - Do a regular calculation.
    - Molpro 2015: Export last orbital set to xml files via

        {put,xml,filename.xml; nosort; keepspherical}

    - Molpro 2012: Export xml files via

        {put,xml,filename.xml; nosort}

    - Complete example inputs are provided in the examples directory.
      (see, e.g. trans_b_SN2_intermediate.inp).
  * Using with Turbomole:
    - Run your calculation, and export its results to molden format
      via Turbomole's tm2molden program.
    - Read the Molden files with iboview.
    - You can also use t2x to just export geometry data to .xyz file
      format (for example, to track geometry optimization progress)
  * Using with Orca:
    - Use "orca_2mkl <basename> -molden" to export your computation
      result to molden format (e.g., if you have a wave function file
      called "wheee.gbw", you would call "orca_2mkl wheee -molden". Note
      that the .gbw file extension is not given to orca_2mkl.
      orca_2mkl then generates a file called wheee.molden.input)
    - Read the Molden files with iboview.
  * Using with Molcas:
    - Import of .molden files generated by Molcas should now work.
  * The program can read multiple input files at once. If invoked via

         iboview file000.xml file001.xml file002.xml ...

    (or iboview dir/*.xml) it will load the given files and attempt
    to sort the contained orbitals by overlap, possibly flipping their
    phase as required. Properties (e.g., color) of associated orbitals
    will also be linked.
    The different files can then viewed by changing the frame number
    in the "Data Sets" page. Pressing Ctrl+T will render iso surfaces
    for the selected orbitals in all frames at once (instead of on
    demand).
  * Other input methods:
    - The program accepts all supported types of files via drag & drop
      (e.g., drag files from your file browser into an open IboView
      window to open them)
    - The state of the visualization can be copied to clipboard via
      Ctrl+Shift+C, and later restored via Ctrl+Shift+V (Hotkeys for
      Edit/Copy State and Edit/Exec Script). The states take the form of
      .js scripts and can be saved, edited, or combined externally in a
      text editor if desired. For example, it is possible to only
      restore the viewing angle or orbital colors by removing all
      unrelated commands from the script before executing it via
      Ctrl+Shift+V.
    - .xyz Files can also be pasted from Clipboard and need not be
      saved to disk: If the text of an .xyz file is in the clipboard,
      Pressing Ctrl+Shift+V in IboView (Edit/Exec Script) will
      load it.

* Notes on security:
   - Do not load data files from people you do not trust. The program has
     not undergone ANY security-related code-review and may contain bugs
     which can be exploited to execute arbitrary code.

   - In particular, you should UNDER NO CIRCUMSTANCES execute state
     scripts (via loading .js/.chai files or using "Exec Script
     (Clipboard)") from people you do not trust or which you have
     not yourself determined to be safe.
     State scripts are PROGRAMS, and could do dangerous things. The
     authors take no responsibility for what happens when they are
     executed, and in particular DO NOT guarantee that the scripts are
     sufficiently sandboxed to prevent them from affecting your system
     or data. You have been warned.

* Controls: Data sets
   - Double-click on an orbital in the "Data Sets"-page or
     "Find Orbitals"-dialog to toggle rendering it
   - Single click on a /visible/ orbital in either the "Data Sets" page
     or the 3d-view in order to change its properties in the "Render:
     Orbital" page.
   - Right-clicking on an object (orbital, atom, or bond) in the
     3d-view brings up a context menu for this object.

* Controls: Finding orbitals
   - For getting an overview of the orbitals, it may be helpful to
     reduce the iso resolution to 10 pt/A. This speeds up surface
     construction by approximately a factor of 5...10.

   - To find orbitals localized on specific atoms, select one or more
     atoms (by clicking them and holding Shift), then right click on one
     of the selected atoms, and select "Find Orbitals..." in the context
     menu.

   - In reaction mechanisms: In DataSets/Frames, you can get an idea of
     which orbitals *change* along the currently loaded frames by
     turning the "Track Orbital" dial. The white dotted line in the
     curve view will then adjust to show how the current orbital number
     changes along the reaction path (it shows the root mean square
     change of the orbital's atomic charges compared with the first
     frame).

     If the line stays flat, it means that the orbital's charge does not
     move between atoms. If it goes up along the reaction path, it means
     that the orbital is distorted during the reaction, possibly
     breaking or forming new bonds.

     If you find an orbital which changes, press the "Show #.." button
     to toggle rendering it, and press Ctrl+T, to render its iso-
     surfaces for all frames. Afterwards, you can use the "current
     frame" dial to see how the orbital transforms during the reaction.

* Controls: Moving and selecting in 3D view
   - Hold right mouse button and move mouse: rotate camera
     ...do so while holding the Shift key: rotate around current
        position instead of coordinate origin.
   - Hold right mouse button and turn wheel: zoom in/out
   - Hold right+left mouse button and move: translate (move picture)
   - Hold right+left mouse button and turn wheel: rotate view around mouse
   - Just turn wheel: Currently do nothing.

   - Atoms can be selected by single-clicking them. Multiple atoms
     can be selected by holding Shift while selecting them (this
     toggles their selection status).

* Scripts
  - The program can be controlled by scripts of Javascript format, but
    the documentation is not written yet.

* Rendering Orbitals & Iso-Surfaces
  - If you see artifacts in places where many orbitals intersect,
    increase the number under "Depth Layers" in Render: Orbitals/Surfaces.
    This specifies the maximum depth complexity of transparent surfaces
    in the program (increasing this number will slow down interactive
    rendering, but not iso-surface tracing).
  - To speed up the construction of iso-surfaces, decrease the number
    in Render: Orbital / Surfaces / Resolution (1/A). Iso-surface time
    scales with r^3. The default setting of 20/A is recommended for
    publication quality graphics (although other programs tend to use
    much smaller resolutions), for survey studies 10/A is sufficient.



* Other used software libraries
  The following software is distributed in source form together with
  iboview:
   - glew: The OpenGL Extension Wrangler Library, libGLEW.
     iboview employs GLEW in order to access OpenGL functions.
     See http://glew.sourceforge.net/ and
     http://glew.sourceforge.net/credits.html for credits.
     GLEW is licensed under the Modified BSD License, the Mesa 3-D License
     (MIT License), and the Khronos License (MIT License).

   - pugixml:
     iboview employs the pugixml library (http://pugixml.org),
     pugixml is Copyright (C) 2006-2014 Arseny Kapoulkine.
     pugixml is distributed under a MIT license. See pugixml/pugixml_readme.txt

   - QPropertyModel.h/.cpp:
     A class for easily turning any QObject-derived subclass with
     properties into a one-row model (cgk: i.e., a QAbstractItemModel/
     QDataWidgetMapper interface for QT properties, which allows
     easy syncing of UI controls with data. It's pretty neat.
     Look it up.).
     Copyright 2013 - Harvey Chapman <hchapman@3gfp.com>
     See https://gist.github.com/sr105/7955969

     QPropertyModel is licensed under the Creative Commons Attribution-
     ShareAlike 4.0 International License. To view a copy of this
     license, visit
     http://creativecommons.org/licenses/by-sa/4.0/deed.en_US.

   - shader/pixel5_fakeAA2.glsl:
     This is a FXAA ("fast approximate anti-aliasing") filter. The
     version here is a slightly modified version (added alpha channels)
     of the GLSL version ported by Sebastian F. Mazza
     (http://code.google.com/p/blubbengine2/) from Timothy Lottes'
     (http://timothylottes.blogspot.de/) original HLSL version. My
     understanding is that the original HLSL FXAA code was made public
     domain by nvidia (an earlier blog post of Lottes said so), the port
     of Sebastian F. Mazza seems to be released under "other open source
     license" according to http://code.google.com/p/blubbengine2/ (the
     actual license was not included).

   - A distance-field pixelized version of the Liberation Sans font is
     embedded into the program. Liberation Sans is released under the
     SIL Open Font License.
     See https://fedorahosted.org/liberation-fonts/

   - fn_LiberationSans.h and shader/pixel_text.glsl:
     The former is an interface file for the Liberation Sans
     font as generated with a modified version of makefont of
     Freetype GL (http://code.google.com/p/freetype-gl/).
     The pixel shader pixel_text.glsl is a modified version
     of the shader distance-field.frag employed in freetype-gl's
     demo-distance-field.c.

   - vector_math.h:
     A modified version of vector_math.h, Copyright (c) 2007,
     Markus Trenkwalden, from http://www.trenki.net/files/vector_math.h

* On Forking and Contributing
  - Do not fork the program. Doing so will invoke my wrath.

    You can freely adjust the program to your own/own group's/own
    institute's needs, but please do not distribute the modified
    program. Especially not via freely accessible web pages.

  - I am ready to accept contributions to the main code base.
    Particularly helpful would be contributions which improve the user
    experience, e.g., support for additional import formats.

    However, there are restrictions to code contributions:
    - Changes will only be incorporated into the main code base if you
      grant me, Gerald Knizia, an unrestricted and unconditional license
      to use, modify, distribute, and re-license the contributed code.
      (in short: if the contributed code will create potential legal
      problems in the future I do not want it).
    - If you make changes which you wish to incorporate into
      the main code base, these /#have to be coordinated with me#/.
    - Changes are unlikely to be accepted if they involve serious
      maintanance- or deployment burdens (e.g., by introducing 3rd party
      libraries with license problems or which are painful to build on
      MSVC), go against the program's agenda (promoting and making
      acceccible the IAO and IBO techniques to computational and organic
      chemists), or involve methods I do not like (e.g., AIM).
    - Changes which are developed or published without coordination
      with me will /*DEFINITELY*/ not be accepted[1]

    [1] The development and maintanance of IboView was and is highly
    non-trivial. Please consider that whatever you are currently doing
    might also have been sitting on my todo list long before I ever
    heard of your publication. However, my resources are limited; I
    am thus reserved about possibily promoting other people's work via
    IboView which I could not do myself solely because I spent the
    resources on IboView itself. For this reason developments should be
    coordinated with me, and some of them might be acceptable only if
    done in cooperation.

* Change History:
   * v20150427:
     - Fix a problem with Windows vs Unix line endings, which prevented
       IboView from reading Unix-generated .molden-Files in the Windows
       version.
     - Changed default IBO exponent from 4 to 2.

   * v20150424:
     - .molden files from Orca and Molcas are now supported.
       A sanity check was added to IBBA, to diagnose broken imports
       (via non-orthogonal occupied orbitals)
     - Fixed a problem with .molden files from Turbomole, which could
       lead to an application freeze.
     - Settings regarding window sizes and file histories are now remembered
       across application starts.
     - Added support for automatic execution of a specified script file
       on startup.
     - Properties of elements and atoms (e.g., colors, sizes, covalent radii,
       etc) can now be changed via scripts.

   * v20150214:
     - Initial public release



-- Gerald Knizia, 2015-02-13
