================================================================================ INSTALLATION HINTS: IMAGIC-4D for Linux 14. May 2012 ================================================================================ Part 1 Requirements for the IMAGIC-4D installation Part 2 Update the shell resource script Part 3 IMAGIC-4D shared libraries Part 4 IMAGIC-4D download Part 5 IMAGIC-4D license Part 6 IMAGIC-4D installation Part 7 IMAGIC-4D restrictions Part 8 IMAGIC-4D parallelization Part 9 IMAGIC-4D post-installation Part 10 IMAGIC-4D troubleshooting Part 11 IMAGIC-4D documentation ================================================================================ Part 1 Requirements for the IMAGIC-4D installation ================================================================================ 1. This version of the IMAGIC-4D programs is "ready-to-use". There are no requirements to install and run the IMAGIC-4D programs. ================================================================================ Part 2 Update your shell resource script ================================================================================ 2.1. Before you can start the installation of the IMAGIC-4D package you need to update your shell resource script. 2.1.1. This IMAGIC-4D installation package contains the OpenMPI implementation of the message passing interface (MPI) software which is necessary to run the parallel IMAGIC-4D programs. The OpenMPI environment settings must be present in the shell resource script. 2.1.2. This IMAGIC-4D installation package contains the FFTW fast fourier transformation routines as well as the SINGLETON algorithms. The installation script will ask which one should be used. The FFTW environment settings must be present in the shell resource script. 2.2. Example shell scripts 2.2.1. The following is an example if you are using the C-Shell. Edit the file .cshrc in your default directory: Be sure to replace with the real path. # # IMAGIC-4D setenv IMAGIC_ROOT alias i*magic $IMAGIC_ROOT/imagic.e alias disp $IMAGIC_ROOT/display/display.e alias plot $IMAGIC_ROOT/plot/plotall.e # # OpenMPI setenv MPIHOME $IMAGIC_ROOT/openmpi setenv MPIBIN $MPIHOME/bin setenv OPAL_PREFIX $MPIHOME set path = ($MPIBIN $path) # # FFTW setenv FFTW_IPATH $IMAGIC_ROOT/fftw/include setenv FFTW_LPATH $IMAGIC_ROOT/fftw/lib setenv FFTW_LIB fftw3f Be sure that you have specified the correct directory paths in the above script. Then activate your changes with either re-login or the command: source .cshrc 2.2.2. The following is an example if you are using the Bourne-Again-Shell. Edit the file .bashrc in your default directory. Be sure to replace with the real path. # # IMAGIC-4D export IMAGIC_ROOT= alias i*magic=$IMAGIC_ROOT/imagic.e alias disp=$IMAGIC_ROOT/display/display.e alias plot=$IMAGIC_ROOT/plot/plotall.e # # OpenMPI export MPIHOME=$IMAGIC_ROOT/openmpi export MPIBIN=$MPIHOME/bin export OPAL_PREFIX=$MPIHOME export PATH=$MPIBIN:$PATH # # FFTW export FFTW_IPATH=$IMAGIC_ROOT/fftw/include export FFTW_LPATH=$IMAGIC_ROOT/fftw/lib export FFTW_LIB=fftw3f Be sure that you have specified the correct directory paths in the above script. Then activate your changes with either re-login or the command: source .bashrc ================================================================================ Part 3 IMAGIC-4D shared libraries ================================================================================ 3.1. This IMAGIC-4D installation package is statically compiled. However, some dynamic system libraries like the ones of the GNU C compiler and the X11 stuff must be present to run the programs (use the command "ldd $IMAGIC_ROOT/imagic.e" to get a list of required shared libraries). ================================================================================ Part 4 IMAGIC-4D download ================================================================================ 4.1. Download the IMAGIC-4D installation file for your operating system. For other (unsupported) Linux systems use the installation file for the operation system which is most similar to yours. ================================================================================ Part 5 IMAGIC-4D license ================================================================================ 5.1. To install and use IMAGIC-4D you require a valid license. If you have obtained your license file from Image Science, please store it into the directory where you want to install IMAGIC-4D. ================================================================================ Part 6 IMAGIC-4D installation ================================================================================ 6.1. We highly recommend to create an installation directory which includes the version number in its name, e.g. mkdir imagic_120508 cd imagic_120508 This can be helpful if a program fails or in case of an erroneous installation. You can easily change between different IMAGIC-4D installations by simply changing the setting of the environment variable IMAGIC_ROOT in your shell resource script. 6.2. Uncompress the IMAGIC installation archive, e.g. type FC10 release: tar -zxf imagic_intel_FC10_x86_64_120508E.tar.gz FC16 release: tar -zxf imagic_intel_FC16_x86_64_120508E.tar.gz 6.3. Copy the IMAGIC-4D license file (imagic.lic) into the installation directory. 6.4. Install the IMAGIC-4D programs: ./install.sh ================================================================================ Part 7 IMAGIC-4D restrictions ================================================================================ 7.1. The use of special characters in directory or file names is NOT permitted. ================================================================================ Part 8 IMAGIC-4D parallelization ================================================================================ 8. This IMAGIC-4D installation package contains the OpenMPI implementation of the message passing interface (MPI) software which is necessary to run the parallel IMAGIC-4D programs. The OpenMPI environment settings must be present in the shell resource script. Please refer to the example shell scripts above. 8.1. To run a parallel IMAGIC-4D program you simply need to answer "YES" when prompted for, e.g. when you start the multi-reference-alignment (enter the command M-R-A at the IMAGIC_COMMAND prompt), the first questions will be: Use MPI parallelisation [YES] : If you give a or answer "YES" at the first question, the system will guide you through the user interaction block as usual, but will start the parallel version of the program after the last question has been answered. 8.2 How does the software know about the available nodes to compute on ? This is the only tricky part which can not be answered within the IMAGIC-4D system. You (or your system administrator) need to either configure the OpenMPI hosts files to use the available nodes, or you can edit a file named "hosts.mpi" in your current working directory which holds a list of nodes to be used: hosts.mpi: # This is an example hostfile. Comments begin with # # # The following node is a single processor machine: foo.example.com # The following node is a dual-processor machine: bar.example.com slots=2 # The following node is a quad-processor machine, and we absolutely # want to disallow over-subscribing it: yow.example.com slots=4 max-slots=4 8.3. More information about the OpenMPI software is available on the webpage http://www.open-mpi.org/faq/ 8.4. OpenMPI license Most files in this release are marked with the copyrights of the organizations who have edited them. The copyrights below generally reflect members of the Open MPI core team who have contributed code to this release. The copyrights for code used under license from other parties are included in the corresponding files. Copyright (c) 2004-2008 The Trustees of Indiana University and Indiana University Research and Technology Corporation. All rights reserved. Copyright (c) 2004-2008 The University of Tennessee and The University of Tennessee Research Foundation. All rights reserved. Copyright (c) 2004-2008 High Performance Computing Center Stuttgart, University of Stuttgart. All rights reserved. Copyright (c) 2004-2007 The Regents of the University of California. All rights reserved. Copyright (c) 2006-2008 Los Alamos National Security, LLC. All rights reserved. Copyright (c) 2006-2008 Cisco Systems, Inc. All rights reserved. Copyright (c) 2006-2008 Voltaire, Inc. All rights reserved. Copyright (c) 2006-2008 Sandia National Laboratories. All rights reserved. Copyright (c) 2006-2008 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Copyright (c) 2006-2008 The University of Houston. All rights reserved. Copyright (c) 2006-2008 Myricom, Inc. All rights reserved. Copyright (c) 2007-2008 UT-Battelle, LLC. All rights reserved. Copyright (c) 2007-2008 IBM Corporation. All rights reserved. Copyright (c) 1998-2005 Forschungszentrum Juelich, Juelich Supercomputing Centre, Federal Republic of Germany Copyright (c) 2005-2008 ZIH, TU Dresden, Federal Republic of Germany Copyright (c) 2007 Evergrid, Inc. All rights reserved. Copyright (c) 2008 Institut National de Recherche en Informatique. All rights reserved. Copyright (c) 2007 Lawrence Livermore National Security, LLC. All rights reserved. Copyright (c) 2007-2008 Mellanox Technologies. All rights reserved. Copyright (c) 2006 QLogic Corporation. All rights reserved. $COPYRIGHT$ Additional copyrights may follow $HEADER$ Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. - Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer listed in this license in the documentation and/or other materials provided with the distribution. - Neither the name of the copyright holders nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. The copyright holders provide no reassurances that the source code provided does not infringe any patent, copyright, or any other intellectual property rights of third parties. The copyright holders disclaim any liability to any recipient for claims brought against recipient by any third party for infringement of that parties intellectual property rights. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ================================================================================ Part 9 IMAGIC-4D post-installation ================================================================================ 9.1. Automatic update notification This feature gives information about the availability of a new IMAGIC-4D releases. When calling IMAGIC (the IMAGIC-4D supervisor program) a routine is started which compares the installed version with the one available on the Image Science download webpages. If a new update is available, a message is printed showing the current and new version dates. The routine is only called when the IMAGIC-4D supervisor ("IMAGIC") is started. If no internet connection is available at runtime, the routine may take a while to complete. You can also call this checking routine by using IMAGIC command CHECK-VERSION. The automatic update notification can be disabled in two ways: Remove (or rename) the executable "$IMAGIC_ROOT/misc/check-version.exe" Edit the file "$IMAGIC_ROOT/imagic.drv" and change the value for the entry "CHECK" to "OFF" The automatic update notification program is available for the Linux, Mac and MS Windows operating systems. ================================================================================ Part 10 IMAGIC-4D troubleshooting ================================================================================ 10.1. Runtime problems 10.1.1. C-SHell IMAGIC creates and uses internal scripts which require the C-SHell to be installed. If the command: "which csh" doesn't show anything, please install the csh package for your operating system, e.g. for UBUNTU systems: sudo apt-get install csh 10.1.2. Requirements Note that the latest version of the IMAGIC programs for Linux has been compiled using GCC 4.6.0 on a Fedora 15 operating system. On 32-bit systems, the command "strings /lib/libc.so.6 | grep GLIBC" or on 64-bit systems, the command "strings /lib64/libc.so.6 | grep GLIBC" should show at least the line "GLIBC_2.7" or higher. If your system does not comply with these requirements, please select one of the installation files which were created on an older Fedora 10 system. 10.2. Re-Installation of the OpenMPI software In some rare cases it might happen, that the OpenMPI binaries which are part of the IMAGIC-4D distribution will fail to run. This results in a "floating point exception" message when starting one of the parallel IMAGIC-4D programs. If you encounter this problem, please first make sure, that the problem really is caused by the OpenMPI binaries by entering the following command: $IMAGIC_ROOT/openmpi/bin/ompi_info If the problem remains, please replace the OpenMPI binaries with a locally compiled version. 10.2.1. Download the OpenMPI package Usually the download page for the OpenMPI software is: http://www.open-mpi.org/software/ However it is recommended to download and install the same version as it was used to build the IMAGIC distribution. Get your copy of this OpenMPI package from our webpage: FC10 release: http://www.imagescience.de/download/imagic/openmpi-1.4.3.tar.gz FC16 release: http://www.imagescience.de/download/imagic/openmpi-1.5.4.tar.gz Store the archive file in the IMAGIC-4D installation folder and extract the files with the following command: FC10 release: tar -zxf openmpi-1.4.3.tar.gz FC16 release: tar -zxf openmpi-1.5.4.tar.gz This will create a new subfolder openmpi-1.4.3 (openmpi-1.5.4) 10.2.2. Compilation of the OpenMPI software First rename the original version which came with the IMAGIC-4D distribution: mv openmpi openmpi_imagic Create a new subfolder openmpi mkdir openmpi Change to the openmpi-1.4.3 (openmpi-1.5.4) folder and enter the following commands: ./configure --prefix=$IMAGIC_ROOT/openmpi \ --disable-io-romio \ --enable-static --disable-shared \ --disable-mpi-f77 --disable-mpi-f90 make make install The new binaries should be stored in the $IMAGIC_ROOT/openmpi folder. Check the function with the command: $IMAGIC_ROOT//openmpi/bin/ompi_info 10.3. Tuning the run-time characteristics of MPI communications In IMAGIC, the sm BTL (shared-memory Byte Transfer Layer) is switched off. Specified btl parameters are "btl=tcp,self" If you need to change these values, please edit the file $IMAGIC_ROOT/openmpi/etc/openmpi-mca-params.conf You may wish to check the btl settings with the command: $IMAGIC_ROOT/openmpi/bin/ompi_info | grep btl For more information about the run-time characteristics of MPI communications, please refer to the OpenMPI website: http://www.open-mpi.org/faq/?category=sm ================================================================================ Part 11 IMAGIC-4D documentation ================================================================================ 11.1. Various manuals on how to use and work with IMAGIC-4D are available on the webpage http://www.ImageScience.de/manuals ================================================================================ Image Science Software GmbH Gillweg 3 D-14193 Berlin Germany imagic@ImageScience.de (C) All Rights Reserved Image Science Software GmbH ================================================================================