====== Installation ======
\\
===== Quick start =====

  * Download the latest version from the website
  * Uncompress the archive downloaded
  * Move the directory to the directory where you want to install the programs
  * Open a terminal and launch the installation script <code>
./auto3dem_install
</code>
  * The script will detect the platform and by default will build all the applications, including those based on a graphical user interface (GUI), assuming the GNU compilers are available. The computing-intensive codes are parallelized using MPI, and the parallel version is compiled by default. You can change the default settings by adding specific options. For a complete list of them type ''./auto3dem_install --help''
 
  * Provide path information for binaries and perl scripts. For example, C shell users should add the following to your .cshrc file, where x.xx is the auto3dem version. <code>
set path = (/path_to_auto3dem/auto3dem_vx.xx/bin $path)
</code> Of course, it's probably more convenient to create a symbolic link named auto3dem that points to the latest version.

===== Compilers =====
The installation script assumes that GNU compilers are available on the computer and will try to compile the programs using those. If you want to use different compilers, you can specify them with the option //--compiler//. The settings for some compilers are already available, and the option //--help// provides a list of them. You can add the settings for a compiler that is not listed by adding a file for the specific combination you intend to use (platform, compiler, parallel or serial) in the //Make// directory, using the ones already present as templates. 

===== Library dependencies =====

AUTO3DEM does not depend on external programs, but relies on libraries of the operating system that are not necessarily present by default.
  * [[auto3dem:installation:linux_libraries|Linux]]
  * [[auto3dem:installation:macosx_libraries|Mac OSX]]

===== Python requirements =====

The python programs provided should run on Python version 2.3 and older.
The program to plot one or multiple FSC curves, //a3dm_plot_fsc.py//, requires the modules //Numpy// and //Matplotlib//, which usually are not installed by default but are available from the package manager of most Linux distributions.  

===== Perl requirements =====

//auto3dem// and the auxilliary routines //setup_rmc//, //handflip//,
//remove_useless//, and //findbest// were developed using Perl version 5.8.5,
but will probably run using slightly older versions. It is expected
that you have the standard set of CPAN modules, including Cwd,
File::Copy, and Math::Trig.

In order to generate graphical representations of the FSC curves, you
will also need the GD library and GD::Graph module. If you don't have
this module, auto3dem will run just fine, but won't produce graphs of
FSC curves.

===== Running parallel jobs =====

AUTO3DEM currently is capable to run under the PBS and SGE batch schedulers. In
your job script, you will need to include the flag (-V) that exports
all environment variables to the job. Do not explicitly include a
nodefile in the auto3dem command since it is automatically passed
through the Perl %ENV hash.

If you are running on a system that is not under control of a batch
scheduler, you can specify that particular nodes be used with the
-nodefile flag. Depending on your computing environment, specification
of a nodefile may not be necessary.

===== Email notification =====

auto3dem has the capability to send email notifications at the end of
each iteration. Add the following line to your auto3dem input file <code>
auto recipient address1 [address2 ...]
</code>
In order for this to work correctly, you will need to have the mutt
email program installed and properly configured.


===== Additional notes =====
==== Compiling image reconstruction codes ====


The programs POR, PCTFR, P3DR, PCUT, PSF, and PPFT called by auto3dem
are parallel applications that have been developed using the MPI
library. The codes contain preprocessor directives that isolate the
parallel content thereby allowing compilation in serial mode.

In order to build the executables, you will need the following

  Fortran 90 compiler
  ANSI C compiler
  MPI libraries (parallel mode only)

Our codes have been successfully compiled and run using the gfortran
and ifort Fortran compilers, the icc and gcc C compilers, and
the MPICH2 and openMPI libraies. That said, we expect that any standard compilers and MPI
implementation will work.

To create binaries of the image reconstruction codes, simply launch the installation script. This
script sets symbolic links to the appropriate make include and perl
module files, enters each of the program and library directories, and
executes the local Makefile. The binaries are then copied into the bin
directory.

==== Programs providing a graphical user interface ====

//RobEM//, //fixpif//, //oned//, and //ctfdisp// all make use of the **Motif** graphical
user interface toolkit. You will need to install the appropriate
library if you wish to use these programs.

One problem commonly encountered with robem is an inability to modify
the contents of text boxes. This can occur even when all other GUI
components (arrows, pulldown menus, buttons, etc.) are working
properly. This can often be fixed by taking the following steps

  32-bit systems
  cd /usr/X11R6/lib/X11 (or /usr/lib/X11 depending on the linux flavor)
  ln -s /usr/share/X11/XKeysymDB XKeysymDB

  64-bit systems
  cd /usr/X11R6/lib/X11 (or /usr/lib64/X11 depending on the linux flavor)
  ln -s /usr/share/X11/XKeysymDB XKeysymDB

Another potential problem is that the value of the $LANG variable may
cause problems when trying to build robem. An error message like the
following may be produced

  uil new_robem.uil -o new_robem.uid
  Error: $LANG contains an unknown character set
  Info: no UID file was produced

To get around this, try unsetting the variable and rebuilding. For
example, in C shell

  % unsetenv LANG