Chapter 2. Installation

Table of Contents

2.1. Installing binary packages of OVITO
2.1.1. Linux
2.1.2. Windows
2.1.3. MacOS
2.2. Command line options
2.3. Configuring OpenGL
2.4. Building OVITO from source
2.4.1. Linux platform
2.4.2. System requirements
2.4.3. Downloading the source code
2.4.4. Build instructions

2.1. Installing binary packages of OVITO

Binary program packages can be downloaded from the official OVITO website for the Linux, Windows, and MacOS X platforms. After extracting the archives, OVITO should run out of the box.

2.1.1. Linux

Extract the downloaded .tar.gz archive using the command:

					tar xzf ovito-0.9.4-i386.tar.gz
				

Replace the filename above with the one that you actually downloaded from the website. This will create a new directory that contains the extracted program files.

Run OVITO by invoking the command

					bin/ovito
				

inside the extracted program directory. Several command line options can be passed to OVITO, which are described here.

2.1.2. Windows

Extract the downloaded .zip archive to a directory of your choice using the built-in archive extractor of Windows. Then run OVITO by double-clicking the file ovito.exe.

2.1.3. MacOS

Extract the downloaded .zip archive to a directory of your choice. Then run OVITO by double-clicking the extracted application.

2.2. Command line options

The following command line options can be passed to the ovito executable:

Table 2.1. OVITO command line options

Command line optionDescription
--verboseEnables the output of additional program information to the console. This can be useful for debugging purposes.
--nobannerSuppresses the license notice printed to the console at startup.
--helpShows information about the available command line options and exits.
--experimentalEnables experimental program features that are still in development.
--script scriptfile.py ...Executes the given Python script file after startup. This option is only available when OVITO has been built with scripting support enabled. Please note that all command line options following the script filename will be passed directly to the Python script and will therefore be ignored by OVITO.
--noguiStarts OVITO in console mode and does not show the main window (no graphical user interface). This option only makes sense in conjunction with the --script option to process script files without user interaction. OVITO terminates after executing the script.


2.3. Configuring OpenGL

OVITO utilizes the OpenGL libraries installed on your system to render a large number of atoms in realtime. Depending on the configuration of your system the OpenGL calls made by OVITO are either executed by a software driver implementation or are passed to the graphics card, which performs high-speed hardware rendering. The latter is highly recommended, as only hardware rendering enables the display of millions of atoms in realtime. Thus, you should make sure that you have a reasonable graphics card installed, and make sure that its OpenGL graphics driver is properly installed! On a Linux machine you can check this by running the command glxinfo in a console window. It gives a lot of information on the installed OpenGL driver. Check the OpenGL vendor and renderer strings. They should match the installed graphics hardware.

Only newer graphics cards fully support the newest functions of the OpenGL standard. That is why OVITO provides several ways of rendering atoms in the viewports. Some of them are supported by older cards providing only a subset of the OpenGL functions. You can configure the rendering method in the OVITO settings dialog (choose OptionsSettings from the main menu). In the Utilities tab of the command panel, you find the OpenGL Test Utility, which lets you check the capabilities of your graphics card.

2.4. Building OVITO from source

2.4.1. Linux platform

OVITO has been developed on Linux systems, and building it on this platform is the easiest. In the following you will find instructions on how to compile OVITO from the source code yourself. In the future, I will try to provide build instructions for the Windows and MacOS platforms as well.

OVITO requires several third-party libraries, and depending on your Linux distribution the compilation of the source code can be more or less work. Recent versions of Linux already provide everything you need. They provide the development packages of the required libraries, which can be installed through the appropriate administrative tools of your Linux distribution. Note that, to be able to install all required packages, you might need superuser privileges or ask your administrator to do it for you.

In case you have an older version of Linux installed on your computer you'll probably have to download and manually build the missing libraries before you can start building the OVITO source code. You will find a detailed list of required packages below.

2.4.2. System requirements

OVITO is a complex software package that makes use of several functions provided by third-party libraries. These libraries (and the corresponding header files) must be available on your computer to successfully build and run OVITO. Also note that OVITO is a modular software. During the build process you can choose which parts of the package should be built. Accordingly, only those third-party libraries need to be available on your system that are required by the modules of OVITO you intend to build. Here is the complete list of things you will need to build OVITO:

  • A C++ compiler, e.g. GNU g++ for Linux.
  • CMake v2.6 or newer (Website)
  • Qt library v4.4 or newer including development files (Website)
  • Boost libraries v1.34 or newer including development files (Website)
  • OpenGL libraries and development files
  • Optional: The Python interpreter (v2.4 or higher) and development files, only required for scripting support (Website)
  • Optional: The QScintilla2 component. Only required for visual scripting support in the Ovito application (Website)
  • Optional: The POV-Ray renderer (Website)
  • Optional: Docbook, only required for building the documentation files
  • Optional: xsltproc, only required for building the documentation files
  • Optional: GNU Scientific Library (GSL) and development files (Website)

2.4.2.1. Ubuntu Linux

These are the repository packages that must be installed on Ubuntu Linux (10.04 or newer) to build OVITO from source:

subversion cmake cmake-curses-gui g++ libboost-dev libboost-iostreams-dev libboost-python-dev povray libqt4-opengl-dev qt4-dev-tools libgsl0-dev xsltproc docbook-xml docbook-xsl docbook-xsl-doc-html libqscintilla2-dev python-dev

Use the command sudo apt-get install followed by the above list of packages to install them.

2.4.3. Downloading the source code

The newest source code for OVITO can be obtained from the SourceForge repository. To this end, you need a Subversion client program (usually called svn) to download the code to a local directory on your computer. The Subversion client svn is included in most Linux distributions. Before you retrieve the source code, you should create an empty parent directory:

					mkdir ovito
					cd ovito
				

Use the following command line to download the source code from the repository for the first time:

					svn checkout http://ovito.svn.sourceforge.net/svnroot/ovito/trunk/ source
				

This command creates a new subdirectory named source and downloads the complete source code including all auxiliary files to this directory.

New features and bug fixes will be added to the source code in the Subversion repository from time to time. You can update your local copy of the source code to the newest version at any time by running the command

					svn update
				

in the source directory. This will replace only those local files with new versions from the server that have been changed since the last download.

The following section describes how to build the executable from the source code.

2.4.4. Build instructions

The CMake build tool is required to compile OVITO. CMake is a platform and compiler-independent makefile generator that comes with many Linux distributions. The OVITO source package includes a project file for CMake, which is used to generate the actual platform-dependent makefile that can then be compiled using the standard GNU make tool.

The first step is to create a second directory in addition to the source directory. This will be the build directory:

					mkdir build
					cd build
				

From inside the newly created build directory run the following command:

					ccmake ../source
				

The ccmake command expects the path to the source directory into which you have downloaded the OVITO source files in the previous step. ccmake is the CMake configuration program that lets you configure the build settings for the OVITO project. This introduction provides a brief description of this tool.

The configuration of the build options in the ccmake program is an iterative process. You first press the c key to let CMake parse the project file. After this first configuration pass ccmake will present you a list of build settings that you can change.

CMake tries to automatically locate all libraries on your computer that are required to build OVITO. If it is not able to find any of them (either because it's missing or maybe because it has not been installed in a default directory, so ccmake can't find them) CMake will print an error message and you will have to enter the path to the library manually in the ccmake configuration program. Note that only those libraries must be present which are required by the OVITO program components you have activated.

The OVITO project file defines several options that can be changed in the ccmake configuration program to customize the build process and the program components (plug-ins) to be built:

Table 2.2. CMake project configuration options

CMake optionsDescription
CMAKE_BUILD_TYPEThis should be set to the value Release to build the OVITO executable with all speed optimizations turned on.
CMAKE_INSTALL_PREFIXSpecifies the path into which the compiled program will be installed if you run make install.
OVITO_BUILD_DOCUMENTATIONControls the generation of the HTML documentation files. The OVITO manual is written in the Docbook XML format and needs to be translated to the HTML format before it can be viewed in a web browser. You will need special tools as discussed in the prerequisites section to do this.
OVITO_BUILD_PLUGIN_ATOMVIZThis boolean option controls whether the AtomViz plugin is built. This should be set to ON.
OVITO_BUILD_PLUGIN_CRYSTALANALYSISThis option controls whether the CrystalAnalysis plugin is built. It provides specific functions for the analysis of crystal structures.
OVITO_BUILD_PLUGIN_POVRAYThis boolean option controls whether the POV-Ray plugin is built. Setting this option to ON makes only sense when the POV-Ray renderer is available on your computer.
OVITO_BUILD_PLUGIN_SCRIPTINGThis boolean option controls whether the scripting plugin is built. When this option is set to ON then OVITO and all other plugins will be built with scripting support enabled and the Python interpreter and Boost.Python must be present on your computer.
OVITO_BUILD_PLUGIN_SCRIPTING_GUIThis boolean option controls whether the graphical user interface for the scripting plugin is built. This feature is not required to use scripting functions from the console or stand-alone Python scripts. It's in a very initial state, so you probably don't need this component.
OVITO_BUILD_PLUGIN_STDOBJECTSThis boolean option controls whether the plugin that provides the standard object types is built.
OVITO_MONOLITHIC_BUILDTurn this on to build OVITO as a single static executable. By default OVITO is build as a collection of smaller plugin modules (shared libraries) that can be extended. In a monolithic build all plugins and all third-party libraries are linked into a single file that can more easily be transfered to another computer.
OVITO_USE_DOUBLE_PRECISION_FPThis boolean option controls whether 64 bit (ON) or 32 bit (OFF) floating-point numbers should be used for all computations in OVITO. Singe precision numbers (32 bit) are usually sufficient for visualization purposes. They also save a lot of memory when you work with a large number of atoms. Double precision numbers (64 bit) may only be required in some cases for very exact analysis calculations.
OVITO_USE_PRECOMPILED_HEADERSThis controls the generation of precompiled headers when using the GCC compiler. Precompiled headers speed up the compilation process and are turned ON by default.


Do not forget to set the CMAKE_BUILD_TYPE setting to either Release or Debug since it has no valid default value.

After all options have been specified in the CMake configuration program and CMake does not complain about any missing libraries you finally can press the g key to generate the makefile. This will also exit the ccmake program. Now run

					make
				

This will start the build process. If you have a computer with a modern multi-core processor than you can speed up the build process by adding the parameter -j2 to the make command. Then, multiple source files will be compiled in parallel (two files simultaneously in the example; you can specify a higher number if your processor has more cores).

A more detailed description of the ccmake configuration program and the necessary steps to build a CMake project can be found in the CMake documentation or on this page.

Note

On some systems we have observed an incompatibility issue between newer versions of Python and old versions of Boost (before version 1.40) that generated a compiler error. This problem has been fixed in version 1.40 of the Boost library. Please upgrade to the new version if you get a compilation error in the file foreach.hpp of Boost.

After you have successfully compiled OVITO you can start the program with the command bin/ovito. OVITO is constantly being enhanced, new features are made available in the SourceForge repository. To upgrade to a newer version of OVITO you just have to perform two simple steps: First run the command svn update in the OVITO source directory to fetch the newest source code changes from the server. After that, just run make in the build directory to recompile OVITO. Re-running the ccmake program is usually not necessary.

Optionally, you can install OVITO to an installation directory by running make install. The installation directory is set with the CMAKE_INSTALL_PREFIX configuration variable in CMake. The default directory is /usr/local which usually requires superuser priviliges, i.e. you have to run

					sudo make install
				

to install it in this location. For a personal installation in your home directory I would recommend not to install OVITO at all; just leave the compiled executable in the build directory and run it from there.