escher: A MATLAB repository from aoterodelaroza

Overview
--------

Escher is a collection of octave routines for the visualization and
plotting of molecules and crystals. The emphasis in escher is in i)
making the plots as pretty and artsy as possible and, ii) providing a
very flexible framework to create plots that are outside the
capacities that traditional GUIs provide.

The original idea in escher was to modernize tessel
(http://azufre.quimica.uniovi.es/software.html#tessel), a program for
the representation of crystal structures (and more). Via an interface
to povray (http://www.povray.org/), tessel is able to generate very
high quality representations of periodic and finite molecular
structures, which is good, because we are not particularly satisfied
with the state of (free) visualization software at the moment.

We now know, however, that tessel has some annoying drawbacks: i) for
most condensed matter applications it is difficult to set the camera
in the orientation that generates a clear plot, ii) it is
time-consuming to write an input for every single graphical
representation, and iii) when we have a problem that exceeds the
possibilities of the implemented keyword list, it is necessary to
reprogram part of the code.

So, because efficiency is almost never an issue with plots, we decided
to port tessel into a more flexible language: a scripting language
like octave. The first part of escher is a collection of octave
routines that read molecular or crystal information from a variety of
sources (gaussian, Quantum ESPRESSO, VASP), and generates
'representations' (balls, sticks, surfaces,...)  that are written to a
graphical output format. For best results, this output format is
POV-Ray, but it can be wavefront obj, geomview off, etc. The scene
contained in the representation is then rendered to generate the
plot. Consequently, in order to create a figure, one has to write a
script using the functions in the escher library.

The perceptive reader will have noticed that instead of solving the
problems in tessel we have made two of them worse: you now have to
write a script instead of an input file and there is still no way of
setting the camera orientation. These things tend to happen to the
authors when they get carried away. This time, however, it is not as
bad as it sounds. A few octave lines are usually enough to generate a
very reasonable plot with current default options and we provide
routines that make placing the camera very easy using programs like
view3dscene.

Escher is still experimental. The syntax may change at any time, and
it's probably riddled with bugs and inconsistencies. So beware.  We
usually implement new features as requests for plots come up in our
everyday work (which is computational chemistry, and in no way related
to software development itself), so escher naturally reflects these
inclinations.  Contributions in any other direction, comments and
suggestions are greatly appreciated.

Installation
------------

In order to use escher, you will need octave
(http://www.gnu.org/software/octave/), which these days comes in the
package distribution system of most linux distros. To install escher,
clone the repository from:

https://github.com/aoterodelaroza/escher

or uncompress the package:

    tar xjvf escher.tar.bz2

and then add the following line to your .octaverc:

    addpath("~/path/to/escher/src")

replacing the string with your particular path. Once this is done, you
can check that your installation is working by opening octave and
trying to call some of the functions in escher (e.g. molecule_()).

Documentation
-------------

The only valid documentation file is doc/devs.org, which contains a
list of all the routines with an apropos entry. The documentation
inside each m script should also be up to date. 

Use
---

Escher is a collection of octave functions to manipulate crystal and
molecular geometries, so this software can be used in two ways: i)
writing an octave script, or ii) using the functions directly in an
octave interactive session.

There are three basic objects in escher: crystals, molecules, and
representations. By 'object' we mean an octave cell array that
contains a collection of data for one of the types above. For
instance, the crystal object contains the cell parameters, the atomic
positions, atomic types, and much more. 

A crystal represents a periodic solid and can be generated by reading,
for instance, the output from a solid-state electronic-structure
code. A molecule represent a gas-phase molecular structure: it
contains atomic coordinates, atomic types, etc. It can be read, say,
from an xyz file. A molecule can also be generated from a crystal
object by taking a piece from it, which is the usual procedure in the
creation of plot for a crystal. A representation is a scene that is
meant to be plotted. Instead of atoms and bonds, there are balls,
sticks, cameras and lights. The representation can be obtained from a
crystal or a molecule object, and it is usually written to a graphical
file format, such as a POV-Ray file (pov) or an obj.

A simple example of usage is:

    #! /usr/bin/octave -q

    cr = cr_read_espresso("crystal.scf.out");
    mol = cr_crystalbox(cr);
    rep = mol_ball(mol);
    rep = mol_stick(mol,rep);
    rep = rep_setdefaultscene(rep);
    rep_write_pov(rep,"crystal.pov");

A crystal object is created by reading the output of a Quantum
ESPRESSO calculation (crystal.scf.out). Then, a molecule is generated
by taking a unit cell (with a little border) from the crystal. A
representation is obtained from the molecule by representing the atoms
as spheres (mol_ball), the bonds as sticks (mol_stick) and by setting
the default parameters for the camera and lights
(rep_setdefaultscene). The scene is written to a POV-Ray file
(crystal.pov) using rep_write_pov. This file can be rendered doing:

    povray -D -UV +Icrystal.pov +Ocrystal.png +W1000 +H1000 +A

Examples
--------

You can find several examples of escher plots in the examples
directory (escher_data), which can be downloaded from:

https://github.com/aoterodelaroza/escher_examples

Copyright notice
----------------

Copyright (c) 2013-2015 Alberto Otero de la Roza, and Víctor Luaña Cabal. 

escher is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.