Introduction

The SPARX source installer installs SPARX, EMAN2 and the SPARX gui, along with all third-party programs they require. Everything is put into a user-chosen directory; the installer does NOT require administrator (root) privileges, does not touch anything outside that directory, and it does not interfere with other installed libraries.

The list of third-party programs included is found here. The third-party programs are all open source/free software released under various licences.

The idea behind the installer is that third-party programs are updated infrequently, while SPARX / EMAN2 are updated frequently. The first time the source installer is used, all packages are compiled, which can take several hours. Updating SPARX / EMAN2 from this first installation takes much less time, typically minutes.

Instructions for the first (full) installation are found below, followed by instructions for updating SPARX/EMAN2 .

Platform Notes

linux

sparx is developed on various linux systems, and the installer should work on these:

• Fedora Core 5/6
• Mandriva 2006/2007
• SuSE 10.1
• Centos 4.2
• Debian (testing/unstable)

Fedora Core 4 has some problems with EMAN2. There are many unit test failures, so Fedora Core 4 is not recommended as a platform for sparx/eman2.

macos x

The macos port is incomplete.

windows

The windows port is incomplete.

Overview

The SPARX installer lives in a single subdirectory chosen by the user; in the following instructions, we assume you put it under directory 'installer' under your home directory. In this directory, all needed packages are built.

The packages are installed under another user-chosen directory, we suggest you install it at directory 'sparxroot' under your home directory.

The following paragraph is prepared for those who are not familiar with unix/linux to help them figure out what is "home directory". Feel free to skip it if you know unix/linux well.

Open a terminal, type in the following command

    cd

you are then back to your home directory. now type the following command

    pwd

you will see a line pops out, which shows your home directory. Which is usually '/home/xxxx' or '/usr/people/xxxx', here xxxx is your user name.

The installer does NOT touch anything outside those two directories, and it does not interfere with other installed libraries. It only uses basic system libraries, so it should work on any Linux system. If it fails to build, let me (mhhohn@lbl.gov) know.

Requirements

The installer checks for required packages when it is run and reports missing ones. For reference, the currently needed packages include:

• gnu make
• a C/C++ compiler
• the subversion revision control system (command svn, this is optional)

For full installation including the graphical parts, you must also have

• an X installation including header files

Installation from source

This takes substantially longer than a binary installation would, but

• it is fully compatible with your system
• you can make additions to the installer itself if you need more packages (and send the additions back to make them permanent in the installer).
• updating packages is straightforward. As sparx changes heavily, this is critical.

First do the following to make a directory for your installer:

    cd
    mkdir installer
    cd installer

by "cd" you are back to your home directory, by "mkdir installer" you created a new directory name "installer" under your home directory, then "cd installer" brings you into the new directory you just created.

Then, you need download the sparx-installer. There are two ways to do this. The first one and the more preferable one, is via subversion. First you need make sure subversion has been installed on your platform, if you do not know how to install subversion, contact your system administrator. As soon as you are sure you have subversion installed, run the following command:

    svn co svn://cci.lbl.gov/sparx-installer/branches/linux-release-1 sparx-installer

which should download and create a new directory sparx-installer under your current directory, which should be 'installer' under your home directory.

If you do not have subversion, and don't want to install it, you can use wget to get the installer, the downside is you might need reinstall everything occasionally. Try:

    wget http://cci.lbl.gov/~hohn/sparx-installer.tar.gz
    tar zxvf sparx-installer.tar.gz

If you don't have wget, try curl instead:

curl http://cci.lbl.gov/~hohn/sparx-installer.tar.gz -o sparx-installer.tar.gz

Then:

    cd sparx-installer
    ./configure $HOME/sparxroot

which instruct the installer to install everything in directory "sparxroot" under your home directory. The last step (./configure) will print a summary. If there is any error, your system is missing the listed prerequisite(s).

Now you can start installing. For a full installation with GUI, please type:

    ./install

If you do not intend to use GUI, you can use

    ./install-no-gui

which is a much smaller build that doesn't require X11. (WARNING: if you use this option, you will not be able to use an important feature of SPARX: e2display.)

After running the install script, you must follow the update instructions below before running sparx.

Type ./configure -h for help.

Some compilation times

Current version, ./install-no-gui.

Current version, ./install.

Previously.

Running sparx

Assuming the ./install command finished successfully, you still need to setup environment before you can actually run sparx.

First you need to figure out what kind of shell you are using. Please try the following command

    ps

which will show a list of currently active process. Look at the last column entitled "CMD", you will see a command end with "sh", that is your shell name. Usually it should be one the following: "sh", "bash", "ksh", "csh", "tcsh".

if you are using "sh", "ksh" or "bash", please run the following command to setup your environment:

    source $HOME/sparxroot/sparx.setpath

otherwise, use the following command:

    source $HOME/sparxroot/sparx.setpath.csh

OK, now you should be able to run sparx by typing

    sparx

Remember, every time you want to run sparx, you will need to redo this environment setting process. It is advised that you modify your login setting such that every you logged into the system, the environment was set automatically. To archive this, you will need modify a specific file under your home directory. If you are using sh, this file would will be ".profile", for bash, it is ".bashrc", and for csh or tcsh, it is ".cshrc". Please keep in mind that there is a "." at the beginning of the file name, and these file will not shown up under regular "ls" command, you need use "ls -a".

Load the file in your favorite editor (vi, emacs, nedit, etc.), add the command line to the end of it. Again for sh, ksh and bash, it is

    source $HOME/sparxroot/sparx.setpath

for csh and tcsh, it is

    source $HOME/sparxroot/sparx.setpath.csh

OK. Now log out and log in again, you should be able to run "sparx" without setting environment

To run python program

As we have mentioned in the introduction section, you should be able to write your own python programs under sparx. The following is an example of python program, which load a volume file, multiply it with a spherical mask and save the result to disk:

from EMAN2 import *
from sparx import *

v = getImage( "sparx/test/model001.tcp" )
nx = v.get_xsize()
ny = v.get_ysize()
nz = v.get_zsize()
m = model_circle( 28, nx, ny, nz )
v *= m
dropImage( v, 'result.spi', 's' )

The code is self-explained. Unfortunately, due to some install procedures, some setup need to be done before you can run this program. Under csh, you need to run the following script:

source /xxx/sparxroot/sparx.setpath.csh

if (! -e $HOME/bin) then
    mkdir $HOME/bin
endif

if (! -e $HOME/bin/python) then
    ln -s `which sparx.python` $HOME/bin/python
endif

set path = ($HOME/bin . $path)

we strongly suggest you add it your .cshrc file. so you do not need to run it every time you login to your account. After run this script, you should be able to run your own python script and also the run though example.

Other tests

the following tests make sure you can write and run python scripts using sparx library. Before running these tests, you need also setup your environment as described in last section:

Firstly, try

    sparx.python -c '"import EMAN2"'

if this works, means you can import EMAN2 library properly.

Secondly, try

    cd $HOME/sparxroot/eman2/install/test/rt
    sparx.python test_emdata.py 

if this works (i.e. no error pops up), means you can run your own python script which uses EMAN2 and sparx.

now test iotbx

    iotbx.pdb.hierarchy 

now test the 2-D image viewer

    sparx.python $SPXROOT/eman2/install/bin/e2display.py  <image_name.hdf> &

To update SPARX and EMAN2

To update date your sparx and EMAN2, you also need setup environment first.

Developers with access to the sources can update as described here.

Others can use the following scripts to get the morning snapshot. (make sure you have setup your environment)

sparx.update-sparx
sparx.update-eman2

Typical output should look like this:

$ sparx.update-sparx 
* Archive old install
  at 
  .../sparx-bin/archive/sparx-05.02.07-4622.tar.gz
* Get new sources.
* Remove old source.
* Extract.
* Post-install.
* Done.

The archive is formed in case the update fails, or in case the updated package produces odd results. For sparx, restoring an old version could be done via e.g.

cd $SPXROOT 
\rm -fR sparx
tar zxf archive/sparx-05.02.07-4312.tar.gz