================================================================================ INSTALLATION HINTS: IMAGIC-4D for MAC OSX (Intel) 14. May 2012 ================================================================================ Part 1 Requirements for the IMAGIC-4D installation Part 2 Update the shell resource script Part 3 IMAGIC-4D shared library 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.1.3. This IMAGIC-4D installation package contains the redistributable shared libraries for the Intel Fortran compiler which was used to built the IMAGIC-4D programs. Please be sure you have read and understand Part 3) of this document. 2.2. Example shell script 2.2.1. The following is an example if you are using the Bourne-Again-Shell. Edit the file .bash_profile in your default directory. Be sure to replace with the real path. # # IMAGIC-4D export IMAGIC_ROOT= export DYLD_LIBRARY_PATH=$IMAGIC_ROOT/lib/:$DYLD_LIBRARY_PATH export PATH=$PATH:. 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 MPILIB=$MPIHOME/lib export PATH=$MPIBIN:$PATH export OPAL_PREFIX=$MPIHOME export DYLD_LIBRARY_PATH=$MPILIB/:$DYLD_LIBRARY_PATH # # FFTW export FFTW_IPATH=$IMAGIC_ROOT/fftw/include export FFTW_LPATH=$IMAGIC_ROOT/fftw/lib export FFTW_LIB=fftw3f export DYLD_LIBRARY_PATH=$FFTW_LPATH/:$DYLD_LIBRARY_PATH 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 .bash_profile ================================================================================ Part 3 IMAGIC-4D shared library ================================================================================ 3.1. This version of IMAGIC-4D for Mac OSX uses a shared library (lib/libim.dylib). Furthermore this IMAGIC-4D installation package contains the redistributable shared libraries for the Intel Fortran compiler which was used to built the IMAGIC-4D programs. The shared libraries are stored in the subfolder "lib" of the IMAGIC-4D installation. The DYLD_LIBRARY_PATH environment variable must be specified and point to this folder. Furthermore, shared libraries for the FFTW and OpenMPI packages are used. There paths also need to be added to the DYLD_LIBRARY_PATH environment variable. Please refer to the example shell scripts above. If the DYLD_LIBRARY_PATH variable is already specified by other applications, please use the following syntax: export DYLD_LIBRARY_PATH=${IMAGIC_ROOT}/lib/:${IMAGIC_ROOT}/openmpi/lib/:${IMAGIC_ROOT}/fftw/lib/:${DYLD_LIBRARY_PATH} ================================================================================ Part 4 IMAGIC-4D download ================================================================================ 4.1. Download the IMAGIC-4D installation file for the Intel-based MAC-OSX This release is intened to be used only on MAC-OSX computers with an Intel chipset. It will NOT run on PowerPCs. ================================================================================ 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. Currently there are 2 IMAGIC packages available for the Mac OSX platform: a) a 32-bit version for the Mac OSX 10.7.x (Lion) b) a 64-bit version for the Mac OSX 10.7.x (Lion) Please select the appropriate package for your operating system. Note, that with the Mac OSX 10.7.x the kernel may boot either as 32- or 64-bit (depending on the drivers available on your machine). Anyway you could run the 64-bit version of the IMAGIC programs on a 32-bit kernel if only your CPU can do it. This is the case for the recent CPU types (i3, i5, i7 ...) 6.2.1. Uncompress the IMAGIC installation archive, on a 32-bit system running OSX 10.7 (Lion), type tar -zxf imagic_intel_OSX_32_120508SE.tar.gz on a 64-bit system running OSX 10.7 (Lion), type tar -zxf imagic_intel_OSX_64_120508SE.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. To disable the automatic update notification you can remove (or rename) the executable "$IMAGIC_ROOT/misc/check-version.exe" The program is available for Linux, Mac and MS Windows operating systems. ================================================================================ Part 10 IMAGIC-4D troubleshooting ================================================================================ 10.1. 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. Re-Installation of the OpenMPI software 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: http://www.imagescience.de/download/imagic/openmpi-1.4.3.tar.gz Store the archive file in the IMAGIC-4D installation folder and extract the files with the following command: tar -zxf openmpi-1.4.3.tar.gz This will create a new subfolder openmpi-1.4.3 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 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 ================================================================================ 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 ================================================================================