Installation

Prerequisites

Interpreter of the Ruby language is needed to run cuby. Often, it comes as a part of the system, otherwise, it can be installed easily.

Ruby version 1.8 is sufficient to run cuby but it is substantially slower than newer versions.

Installation

The installation can be as simple as just unpacking the archive in a directory of your choice. It creates a directory cuby4 which contains the Cuby framework. To test the installation, go to the cuby4 directory and type

./cuby4 --info

to get some basic information on the current installation. To test whether cuby works, you can run a simple calculation with a command

./cuby4 --test

To run your own calculation, run cuby on an input file:

install_path/cuby4 input_file.yaml

Environment setup

To make cuby accessible from anywhere, add the path to the installation to the PATH environment variable. In bash, use command:

export PATH=your_install_path:$PATH

Add this command to your ~/.bashrc file to make this setup permanent.

Configuration file

The configuration of cuby, most importantly the paths to all the extarnal software it uses, can be stored in a config file (It is not necessary as every calculation can be configured in the input file).

The config file is a list of key-value pairs in YAML format; the value overwrites the default value of the respective keyword. An example of a config file can be found in cuby_directory/config.

Two config files can be used:

• A global one named cuby4_config.yaml, located at the same level as the cuby4 directory (e.g when the cuby4 exacutable is ~/cuby4/cuby4, the config file is ~/cuby4_config.yaml). This location was chosen so that the config file is preserved when the cuby4 directory is overwritten. This configuration applies to all users.
• A local one (named ~/.cuby4). Each user can have its own local config file and it overrides the setup from the global config.

Binary extensions

While Cuby is written in pure ruby, it will run faster when the most demanding tasks are offloaded to binary extensions. There are two of them, one for represetnation of the molecular coordinates and a second one implementing matrix and vector algebra.

To compile the extensions, a C compiler, ruby header files and ruby's mkmf tool are needed. In debian-based Linux distributions, the the headers and mkmf are found in the ruby1.X-dev package.

To compile the linear algebra extension, blas and lapack libraries and their header files have to be present (packages libblas-dev, liblapack-dev on debian-based Linux). Manual installation of the dependencies is described here.

Some advanced optimization algorithms require the UMFPACK library (part of the Suitesparse package) but the extension can be compiled and used without it. This is the only functionality of the extensions that does not have a ruby equivalent because it is intended for applications to large systems where ruby code would be too slow.

Once you have installed all the dependencies, run

./cuby4 --make

to compile the extensions. Sometimes, lapack is not identfied automatically even if it present. To override the autodetection, compile the extensions with:

./cuby4 --make-force

Summary

Provided all the dependencies are available, the following series of commands (bash shell is assumed) installs cuby so that it is ready to use:

tar -xf cuby4.tgz
cd cuby4
export PATH=`pwd`:$PATH
echo "export PATH=`pwd`:\$PATH" >> ~/.bashrc
cp config/keyword_defaults.yaml ../cuby4_config.yaml
cuby4 --make
cuby4 --info
cuby4 --test