Differences between revisions 41 and 83 (spanning 42 versions)
Revision 41 as of 2013-01-15 14:50:17
Size: 8188
Editor: SteveLudtke
Comment:
Revision 83 as of 2017-12-27 01:56:26
Size: 17063
Editor: RJEdwards
Comment: spelling
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
When upgrading to a newer version, BEFORE downloading/untaring the new version, you MUST run

e2bdb.py -c

This will clean up the cache and make sure you don't have any running EMAN2 jobs while you do the upgrade. While unlikely, failing to do this could result in corruption of some files. If you do forget, and don't want to reinstall the old version, you will need to 'rm -rf /tmp/eman2db-*' to remove all old cache files. Normally this will be safe as long as no EMAN2 programs are actively running, and nothing crashed.
Line 11: Line 5:
After installing on any of the systems below, you should test to make sure it's working. While we have unit testing, it is mainly for those compiling from source. Instead, we suggest just running the following 3 basic tests: '''After''' installing on any of the systems below, you should test to make sure it's working. While we have unit testing, it is mainly for developers. Instead, we suggest just running the following 4 basic tests:
Line 13: Line 7:
 * e2version.py (make sure the displayed version is what you expect, including the timestamp. If you have any problems we need you to include the output from this command in your message)
Line 14: Line 9:
 * e2workflow.py (if the GUI pops up, it's working)  * e2projectmanager.py (if the GUI pops up, it's working)
Line 18: Line 13:
Mac OS X 10.5 and 10.6 are supported for EMAN2 nightly builds. The build is fully 64 bit on 10.6, and this package is recommended and tested more regularly. Download the appropriate dmg from the nightly build page, copy "EMAN2" to your "/Applications" folder. Instructions on loading the environment variable init script are included in the README.txt file. Mac OS X versions 10.7 and higher are supported for EMAN2 nightly builds (10.6 is only supported in older, pre 2.1 releases). To install:
Line 20: Line 15:
There is a [[EMAN2/Install/BinaryInstall_OSXVisualGuide|visual installation guide]] that explains the process with screenshots.  1. Download the appropriate '.dmg' file from the nightly build page and copy the "EMAN2" folder into "/Applications".

 1. If you use the bash shell, add the following line to your ".profile" file:
 {{{
test -r /Applications/EMAN2/eman2.bashrc && source /Applications/EMAN2/eman2.bashrc
}}}
 Similarly, if you use the csh or tcsh shell, add the following line to ".cshrc":
 {{{
test -r /Applications/EMAN2/eman2.cshrc && source /Applications/EMAN2/eman2.cshrc
}}}

 1. Restart your terminal program for a fresh shell. EMAN2 should now be installed and function properly.

''Notes:''

 * The EMAN2.1 binaries MUST use the OSX-provided Python distribution. If you type 'which python', you should see '/usr/bin/python'. If you see something else, like '/usr/local/bin/python', you will have problems. In this situation there are two choices:
  * Set up a shell script to alter your PATH and PYTHONPATH shell variables to exclude the other python when you wish to use EMAN2.1 '''or'''
  * Install EMAN2.1 from source (in which case you can use whatever Python 2.7.X you like).
 * There has been a report of an out of date NumPy version causing some issues. You may need to use ''pip'' or ''easy_install'' to update NumPy if you get errors about this.
Line 23: Line 36:
Note: In the following installation instruction, I assume you are installing EMAN2 in your home directory. So I use my home directory "/home/gtang" as an example. EMAN2 provides four nightly builds for Linux: eman2.nightly.linux.tar.bz2 and eman2.daily.linux.tar.bz2 are for 32 bit Linux (i386). eman2.daily.linux64.tar.bz2 and eman2.daily.linux64.gcc4.tar.bz2 are for 64 bit Linux (x86_64). The gcc4 version requires glibc version at least 2.5. We recommend you install the gcc4 version of EMAN2 unless your linux release is several years out of date. If you are not sure, you can check your glibc version by typing '/sbin/ldconfig -V'. If you are not sure if your linux is 32 bit or 64 bit. You can check with command 'uname -r'. If you see x86_64 that means your linux is 64 bit. Otherwise it's 32 bit linux. To install this binary release, for example, on 64 bit Linux: download eman2.daily.linux64.gcc4.tar.bz2 to your home directory. In the following installation instruction, we assume you are installing EMAN2 in your home directory (no root privileges required), it can also be installed system-wide, in which case each user needs to source the eman2.bashrc file.

There are 2 Linux binaries:

 * eman2.daily.linux64.tar.gz - 64 bit binary
 * eman2.daily.linux.tar.gz - 32 bit binary (for very old computers, or those with 32 bit linux. Not recommended)

If you are upgrading from a previous version of EMAN2, please rename or completely remove the old EMAN2 directory before installing the new version. Unpacking the new version on top of an older version can sometimes cause problems. It is critical that you re-run the installer after unpacking the new version, and insure that your .bashrc or other login file is updated. This is the suggested sequence:
Line 26: Line 46:
$tar xvjf eman2.daily.linux64.gcc4.tar.bz2
$cd EMAN2
$./eman2-installer
rm -rf EMAN2.old
mv EMAN2 EMAN2.old
tar xvzf eman2.daily.linux64.tar.gz
cd EMAN2
./eman2-installer
Line 30: Line 52:
When the installer is done (takes only a few seconds): When the installer is done (takes only a few seconds), it will display an instruction to add eman2.bashrc to your login script (or similar, depending on what shell you use).

If you are familiar with Linux, this instruction should be clear. Just make sure you open a new terminal window to test the installation.

'''If you are a Linux novice''', you need to understand that there are several different 'shells' you can use within your terminal window. The 'shell' is what provides the terminal prompt and what interprets the commands you type. Why there are different ones is a long story, but the default shell for most linux installations is called BASH. Every time you open a new terminal window or log in to the computer with something like SSH, the shell initializes itself by reading a file called .bashrc. EMAN2 has some additions to this file to tell the shell where you installed it, so it can find all of the e2* commands when you run them. You also need to know that on Linux, files starting with '.' are considered hidden files, so if you do an 'ls' you won't see this file, and it may be hidden in your file browser. If you do an 'ls -al', you will see the hidden files too. An easy way to add a line of text to the end of a file, is to (replace text with the line you need to add):
Line 33: Line 59:
Please add the following line to the end of your /home/gtang/.bashrc
source /home/gtang/EMAN2/eman2.bashrc
echo text >>.bashrc
Line 36: Line 61:
This eman2.bashrc just provides some environment variables for EMAN2 and sparx. You can either add the source line to your .bashrc, or copy all the environment variable setting in eman2.bashrc into your.bashrc file: If you see an error like: ''Cannot mix incompatible Qt library (version 0x40806) with this library (version 0x40804)''. This means the Qt installed on your computer is conflicting with the Qt distributed with EMAN2. In most cases, if you just remove the Qt that comes with EMAN2 from extlib/lib, eg - ''rm -rf EMAN2/extlib/lib/libQt*''. If this doesn't solve the problem, take note of the new error message, and ask for help!

This completes the installation. Follow the testing instructions above. If there are problems, please use [[https://groups.google.com/forum/?hl=en#!forum/eman2|EMAN2 Google Group]]. If you cannot use the Google Group for some reason, please feel free to email sludtke@bcm.edu .

=== Additional tips: ===
 * '''If you are also using EMAN1''', you should put the EMAN2 'source' after the EMAN1 'source' in your .bashrc file.
 * '''Ubuntu users''': A package called 'freeglut' is not always installed on Ubuntu machines, and may be required for 2-D plots (such as interactive CTF tuning). If you see blank windows when you expect to see plots, please use the package manager to install freeglut.
 * '''For SUSE users''' and users of some other KDE based platforms which refuse to work properly after installing EMAN2. EMAN2 ships with its own copy of the Qt libraries. If your distribution uses EXACTLY the same version of Qt that we provide, there may be a conflict which prevents KDE from working. Despite the version numbers being the same, Qt can be compiled with many different options, and if the options we used don't exactly match the options your OS used, then the EMAN2 libraries will conflict. There are two possible ways to resolve this: 1) remove all of the Qt libraries from EMAN2/extlib, which will force EMAN2 to use the system libraries (there is a chance that EMAN2 will not work with the system libraries). 2) Remove the EMAN2 bashrc file from your .bashrc file, and when you want to use EMAN2, set up an alias to source the bashrc from the shell you want to run EMAN2 from. This will make it so only those shells will use EMAN2's libraries, and it won't interfere with the rest of your system.
 * EMAN2 on Linux ships with its own Python interpreter, which will be used for all e2* and sx* programs. However, if you run 'python' you will use your system default python interpreter, not the one that ships with EMAN2. If you wish to write your own EMAN2 python scripts, you need to copy the first line from e2speedtest.py and put it in your python script so the correct interpreter is used.

=== Conflicts between software packages: ===
In a perfect world no software would interfere with each other and the world would be a happy place. When things are distributed as source, and compiled on your computer, or similarly if they come with the package manager on your computer, then all of the different software share access to a common set of dependencies (shared libraries). For example, FFTW, Qt, libGSL, etc. However, if you are a developer and want to distribute a single binary package that will run on any version of linux from the last 5 years, you pretty much have to include one specific version of each library along with the binary package. This is a pretty common practice. While it's inefficient, most scientific software projects simply lack the manpower to compile different binary packages for every different linux distribution. Unfortunately that means that, for example, if you install EMAN2 and IMOD in the same account and the two packages use different versions of some specific libraries, you can get conflicts and one of the two packages will not work properly. Here is an example:
Line 39: Line 75:
$gedit /home/gtang/.bashrc Traceback (most recent call last):
  File "/t2/home/EMAN2/bin/e2projectmanager.py", line 34, in <module>
    from PyQt4 import QtCore, QtGui
ImportError:
/t2/home/EMAN2/extlib/lib/python2.7/site-packages/PyQt4/QtCore.so:
undefined symbol: _ZN7QLocale14scriptToStringENS_6ScriptE
Line 41: Line 82:
Then add the given source line to the file. Note: if you are using some kind of c shell, you will see the eman2.chsrc file. In this example, there is a problem with conflicting Qt libraries from two different sources. The most common way for a binary package to find the libraries distributed with it is via the LD_LIBRARY_PATH shell variable. Unfortunately, this is the root of the problem, because the path gets used in-order, so whatever appears first is what will be used. EMAN2 recently switched to the more modern approach, where the relative library paths are compiled into the programs/libraries themselves, so LD_LIBRARY_PATH isn't required, and EMAN2 should not interfere with any of your other software. However, if you have other software which uses LD_LIBRARY_PATH, it CAN interfere with EMAN2, but only if it uses exactly the same library version EMAN2 does and it was compiled with different options.
Line 43: Line 84:
'''NOTE:''' If you are also using EMAN1, you should put the EMAN2 'source' after the EMAN1 'source' in your .bashrc file. If you see an error like the one above, the first thing is to "unset LD_LIBRARY_PATH" (unsetenv in csh), and see if your EMAN2 programs start working. If they do, then there is some conflicting library somewhere in your path, and you should probably go back and re-add the LD_LIBRARY_PATH elements one at a time until it stops working again. This will tell you which package is conflicting, and you can then arrange to avoid the conflict (perhaps with a shell script to only add the offending path element when you need that particular package). You could also complain to the developer of the other package, and ask if they could switch to a distribution scheme which doesn't require LD_LIBRARY_PATH.
Line 45: Line 86:
This completes the installation. You can try running 'e2speedtest.py' and 'e2display.py' in a new terminal window. If they both work, everything should be installed properly.
If they do not work, please report the problem either to sludtke@bcm.edu, or check the [[https://groups.google.com/forum/?hl=en#!forum/eman2|EMAN2 Google Group]].
The alternative solution is to go through the modest pain of building from source. Packages built from source generally will never conflict with one another in this way.
Line 48: Line 88:
'''NOTE:''' EMAN2 on Linux ships with its own Python interpreter. The eman2-installer will automatically change the python interpreter in the EMAN2 python files to use this version of Python. For example:

{{{#!/home/username/EMAN2/python/Python-2.6.5-ucs4/bin/python}}}

If you wish to write your own EMAN2 scripts, you will need to use this same Python interpreter, or 'import EMAN2' will fail !

'''NOTE:''' Ubuntu users
A package called 'freeglut' is not always installed on Ubuntu machines, and may be required for 2-D plots (such as interactive CTF tuning). If you see blank windows when you expect to see plots, please use the package manager to install freeglut.
=== NoMachine remote desktops ===
Some versions of NoMachine's remote desktop solution has significant OpenGL bugs which can cause a variety of annoying and odd artifacts. These are particularly noticeable in e2boxer, but may be seen in other programs as well. As far as we are aware, there is no good solution for this problem within that ecosystem. We have started using TurboVNC/VirtualGL for remote Linux desktop display instead. We have found no display glitches at all with this system, and due to the way it handles remote rendering, it is much faster for many operations as well.
Line 58: Line 92:
Please note that EMAN2's Windows support is the "poor cousin" of the distributions. Like most open-source software EMAN2 was designed primarily for Unix-like environments (Mac/Linux) we expend substantial human effort to keep EMAN2 working on windows, and even with these efforts, some things still do not work optimally. If you have any other choice (Linux/Mac) you will generally have a much better experience on those platforms.

Here is a simple example: on windows 7 and above, the OS puts a priority on user interactivity, to the extent that if it detects a user event (mouse click, etc.) which isn't handled by the software within a second or two, it immediately kills the program. While clearly we strive for a good interactive user-experience, there are occasional places in EMAN2 where there may be a few second delay after you tell the program to do something before it will respond again (while it does what you asked it to do). If you happen to click on a window during this time, Win7+ will kill the program, often corrupting any files being processed at the time. Windows is the only platform with this issue. While we have tried to improve this issue in various places in EMAN2 it simply isn't practical to redesign the entire system around this arbitrary constraint, so the user has to be careful.

Anyway, if you're not deterred by my doom and gloom, we do try to make installation as simple as possible, and it IS possible to use EMAN2 effectively on Windows:
Line 59: Line 99:
 * If you plan to install both EMAN1 and EMAN2, EMAN1 must be installed FIRST.
 * For windows(XP/Vista/7 32/64), EMAN2 comes with it's own Python2.7, with preinstalled site-packages like PyQt4, PyOpenGL etc., So if you have your own Python installed, you may need uninstall it IF there is a conflict.
 * After installation, you can open a command prompt and type e2.py.
  * If you get error like:
   . {{{
 * For windows(XP/Vista/7 32/64), EMAN2 comes with it's own Python2.7, with preinstalled site-packages like PyQt4, PyOpenGL etc., So if you have your own Python installed, you may need uninstall it IF there is a conflict. If you need this other Python, in some cases setting up a separate account for EMAN2 can solve the problem, but there may be some software which simply cannot reasonably coexist on the same Windows machine.
 * (NOT RECOMMENDED: If you plan to install both EMAN1 and EMAN2, EMAN1 must be installed FIRST.
 * After installation, try running:
  * e2version.py
  * e2speedtest.py
  * e2display.py
 * If you get an error like:

{{{
Line 65: Line 109:
}}}
   {{{

or
Line 69: Line 114:
   please install Visual C++ 2008 Redistributable downloaded from Microsoft or from here [[attachment:vcredist_x86.exe|Download Visual C++ 2008 redistributable runtime library here]]..
  * If you get a python prompt successfully, try typing 'display(test_image())'. You should see an s-shaped image appear on the screen. If so, EMAN2 is working.
 * If you double click on one of the icons, and the application doesn't open properly, please try running it from the command-line instead. This will give better error information.
 . please install Visual C++ 2008 Redistributable downloaded from Microsoft or from here [[attachment:vcredist_x86.exe|Download Visual C++ 2008 redistributable runtime library here]]..

 * Do not try to run EMAN2 programs using desktop Icons. You need to open a command prompt and run the commands from there. Even the GUI tools should be launched this way.
Line 75: Line 120:
 * There may be conflicts with EMAN2 and other software packages which also use python. On Linux/Mac, there are mechanisms for dealing with this, but windows lacks this. Most problems with Windows installations relate to conflicts with other software.
Line 76: Line 122:
== Environement Variable Setting For EMAN2 (All platforms)==
In some rare cases, the EMAN2 installer will not be able to update your environment variables properly. In such cases, we need set up environment variables like PATH, LD_LIBRARY_PATH and PYTHONPATH for EMAN2 to work correctly.
These environment variables should be automatically set when you run eman-installer script when you install binary EMAN release.
== Environment Variable Setting For EMAN2 (All platforms) ==
In some rare cases, the EMAN2 installer will not be able to update your environment variables properly. In such cases, we need set up environment variables like PATH, LD_LIBRARY_PATH and PYTHONPATH for EMAN2 to work correctly. These environment variables should be automatically set when you run eman-installer script when you install binary EMAN release.
Line 85: Line 130:
export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${EMAN2DIR}/lib
Line 87: Line 131:
# export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${EMAN2DIR}/lib # This line should no longer be used (with releases after 2.06)
Line 93: Line 138:
setenv LD_LIBRARY_PATH ${EMAN2DIR}/lib #setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:${EMAN2DIR}/lib if you have LD_LIBRARY_PATH set
Line 95: Line 139:
#setenv LD_LIBRARY_PATH ${EMAN2DIR}/lib # This line should no longer be used (with releases after 2.06)
Line 99: Line 144:
right click "my computer"->properties->Advanced->Environment Variables, in "system variables"edit the "path" entry,
-> then add following value into it:
C:\EMAN2\bin;C:\EMAN2\lib;C:\EMAN2\python\Python27;C:\EMAN2\python\Python27\Lib\site-packages\PyQt4\bin.
Create a new system variable PYTHONPATH, add following value into it: C:\EMAN2\lib;C:\EMAN2\bin. (note: In the example I suppose you install
EMAN2 into C:\ directory, change it accordingly if you install EMAN2 in other directory.)
right click "my computer"->properties->Advanced->Environment Variables
in "system variables"edit the "path" entry
, and add:
C:\EMAN2\bin;C:\EMAN2\lib;C:\EMAN2\python\Python27;C:\EMAN2\python\Python27\Lib\site-packages\PyQt4\bin.

Create a new system variable PYTHONPATH, add:
C:\EMAN2\lib;C:\EMAN2\bin.
(note: In the example I s
uppose you installed EMAN2 into C:\ directory, change it accordingly if you install EMAN2 in other directory.)
Line 104: Line 152:
Note that some windows machines may have so much software installed on them that the PATH and/or PYTHONPATH may exceed their maximum length. The only real solution to this that I'm aware of is to write little shell-scripts to adjust your environment for specific uses. This should be a very unusual situation, though.

 * Sometimes international users will have issues with images not displaying correctly. This can be due to internationalization settings causing the operating system to expect "," to be the decimal separator, instead of ".". Alas only "." is compatible with pretty much all conventions in the Cyro-EM community. Setting these shell variables may help:
  * LC_CTYPE=en_US.utf8
  * LC_ALL=en_US.utf8

All platforms

Note for International use - We lack sufficient manpower at present for any real internationalization support. In particular some users have reported problems with the use of ',' rather than '.' in numbers. The only known solution at present is to set English to your language.

Testing

After installing on any of the systems below, you should test to make sure it's working. While we have unit testing, it is mainly for developers. Instead, we suggest just running the following 4 basic tests:

  • e2version.py (make sure the displayed version is what you expect, including the timestamp. If you have any problems we need you to include the output from this command in your message)
  • e2speedtest.py (will also give you the relative speed to expect from your machine)
  • e2projectmanager.py (if the GUI pops up, it's working)
  • e2proc2d.py anyimagefile bdb:test (anyimagefile is any 2d image or stack supported by eman2, this will make sure the database works)

Mac OS X

Mac OS X versions 10.7 and higher are supported for EMAN2 nightly builds (10.6 is only supported in older, pre 2.1 releases). To install:

  1. Download the appropriate '.dmg' file from the nightly build page and copy the "EMAN2" folder into "/Applications".
  2. If you use the bash shell, add the following line to your ".profile" file:
    test -r /Applications/EMAN2/eman2.bashrc && source /Applications/EMAN2/eman2.bashrc
    Similarly, if you use the csh or tcsh shell, add the following line to ".cshrc":
    test -r /Applications/EMAN2/eman2.cshrc && source /Applications/EMAN2/eman2.cshrc
  3. Restart your terminal program for a fresh shell. EMAN2 should now be installed and function properly.

Notes:

  • The EMAN2.1 binaries MUST use the OSX-provided Python distribution. If you type 'which python', you should see '/usr/bin/python'. If you see something else, like '/usr/local/bin/python', you will have problems. In this situation there are two choices:
    • Set up a shell script to alter your PATH and PYTHONPATH shell variables to exclude the other python when you wish to use EMAN2.1 or

    • Install EMAN2.1 from source (in which case you can use whatever Python 2.7.X you like).
  • There has been a report of an out of date NumPy version causing some issues. You may need to use pip or easy_install to update NumPy if you get errors about this.

Linux

In the following installation instruction, we assume you are installing EMAN2 in your home directory (no root privileges required), it can also be installed system-wide, in which case each user needs to source the eman2.bashrc file.

There are 2 Linux binaries:

  • eman2.daily.linux64.tar.gz - 64 bit binary
  • eman2.daily.linux.tar.gz - 32 bit binary (for very old computers, or those with 32 bit linux. Not recommended)

If you are upgrading from a previous version of EMAN2, please rename or completely remove the old EMAN2 directory before installing the new version. Unpacking the new version on top of an older version can sometimes cause problems. It is critical that you re-run the installer after unpacking the new version, and insure that your .bashrc or other login file is updated. This is the suggested sequence:

rm -rf EMAN2.old
mv EMAN2 EMAN2.old
tar xvzf eman2.daily.linux64.tar.gz
cd EMAN2
./eman2-installer

When the installer is done (takes only a few seconds), it will display an instruction to add eman2.bashrc to your login script (or similar, depending on what shell you use).

If you are familiar with Linux, this instruction should be clear. Just make sure you open a new terminal window to test the installation.

If you are a Linux novice, you need to understand that there are several different 'shells' you can use within your terminal window. The 'shell' is what provides the terminal prompt and what interprets the commands you type. Why there are different ones is a long story, but the default shell for most linux installations is called BASH. Every time you open a new terminal window or log in to the computer with something like SSH, the shell initializes itself by reading a file called .bashrc. EMAN2 has some additions to this file to tell the shell where you installed it, so it can find all of the e2* commands when you run them. You also need to know that on Linux, files starting with '.' are considered hidden files, so if you do an 'ls' you won't see this file, and it may be hidden in your file browser. If you do an 'ls -al', you will see the hidden files too. An easy way to add a line of text to the end of a file, is to (replace text with the line you need to add):

echo text >>.bashrc

If you see an error like: Cannot mix incompatible Qt library (version 0x40806) with this library (version 0x40804). This means the Qt installed on your computer is conflicting with the Qt distributed with EMAN2. In most cases, if you just remove the Qt that comes with EMAN2 from extlib/lib, eg - rm -rf EMAN2/extlib/lib/libQt*. If this doesn't solve the problem, take note of the new error message, and ask for help!

This completes the installation. Follow the testing instructions above. If there are problems, please use EMAN2 Google Group. If you cannot use the Google Group for some reason, please feel free to email sludtke@bcm.edu .

Additional tips:

  • If you are also using EMAN1, you should put the EMAN2 'source' after the EMAN1 'source' in your .bashrc file.

  • Ubuntu users: A package called 'freeglut' is not always installed on Ubuntu machines, and may be required for 2-D plots (such as interactive CTF tuning). If you see blank windows when you expect to see plots, please use the package manager to install freeglut.

  • For SUSE users and users of some other KDE based platforms which refuse to work properly after installing EMAN2. EMAN2 ships with its own copy of the Qt libraries. If your distribution uses EXACTLY the same version of Qt that we provide, there may be a conflict which prevents KDE from working. Despite the version numbers being the same, Qt can be compiled with many different options, and if the options we used don't exactly match the options your OS used, then the EMAN2 libraries will conflict. There are two possible ways to resolve this: 1) remove all of the Qt libraries from EMAN2/extlib, which will force EMAN2 to use the system libraries (there is a chance that EMAN2 will not work with the system libraries). 2) Remove the EMAN2 bashrc file from your .bashrc file, and when you want to use EMAN2, set up an alias to source the bashrc from the shell you want to run EMAN2 from. This will make it so only those shells will use EMAN2's libraries, and it won't interfere with the rest of your system.

  • EMAN2 on Linux ships with its own Python interpreter, which will be used for all e2* and sx* programs. However, if you run 'python' you will use your system default python interpreter, not the one that ships with EMAN2. If you wish to write your own EMAN2 python scripts, you need to copy the first line from e2speedtest.py and put it in your python script so the correct interpreter is used.

Conflicts between software packages:

In a perfect world no software would interfere with each other and the world would be a happy place. When things are distributed as source, and compiled on your computer, or similarly if they come with the package manager on your computer, then all of the different software share access to a common set of dependencies (shared libraries). For example, FFTW, Qt, libGSL, etc. However, if you are a developer and want to distribute a single binary package that will run on any version of linux from the last 5 years, you pretty much have to include one specific version of each library along with the binary package. This is a pretty common practice. While it's inefficient, most scientific software projects simply lack the manpower to compile different binary packages for every different linux distribution. Unfortunately that means that, for example, if you install EMAN2 and IMOD in the same account and the two packages use different versions of some specific libraries, you can get conflicts and one of the two packages will not work properly. Here is an example:

Traceback (most recent call last):
  File "/t2/home/EMAN2/bin/e2projectmanager.py", line 34, in <module>
    from PyQt4 import QtCore, QtGui
ImportError:
/t2/home/EMAN2/extlib/lib/python2.7/site-packages/PyQt4/QtCore.so:
undefined symbol: _ZN7QLocale14scriptToStringENS_6ScriptE

In this example, there is a problem with conflicting Qt libraries from two different sources. The most common way for a binary package to find the libraries distributed with it is via the LD_LIBRARY_PATH shell variable. Unfortunately, this is the root of the problem, because the path gets used in-order, so whatever appears first is what will be used. EMAN2 recently switched to the more modern approach, where the relative library paths are compiled into the programs/libraries themselves, so LD_LIBRARY_PATH isn't required, and EMAN2 should not interfere with any of your other software. However, if you have other software which uses LD_LIBRARY_PATH, it CAN interfere with EMAN2, but only if it uses exactly the same library version EMAN2 does and it was compiled with different options.

If you see an error like the one above, the first thing is to "unset LD_LIBRARY_PATH" (unsetenv in csh), and see if your EMAN2 programs start working. If they do, then there is some conflicting library somewhere in your path, and you should probably go back and re-add the LD_LIBRARY_PATH elements one at a time until it stops working again. This will tell you which package is conflicting, and you can then arrange to avoid the conflict (perhaps with a shell script to only add the offending path element when you need that particular package). You could also complain to the developer of the other package, and ask if they could switch to a distribution scheme which doesn't require LD_LIBRARY_PATH.

The alternative solution is to go through the modest pain of building from source. Packages built from source generally will never conflict with one another in this way.

NoMachine remote desktops

Some versions of NoMachine's remote desktop solution has significant OpenGL bugs which can cause a variety of annoying and odd artifacts. These are particularly noticeable in e2boxer, but may be seen in other programs as well. As far as we are aware, there is no good solution for this problem within that ecosystem. We have started using TurboVNC/VirtualGL for remote Linux desktop display instead. We have found no display glitches at all with this system, and due to the way it handles remote rendering, it is much faster for many operations as well.

Windows

Please note that EMAN2's Windows support is the "poor cousin" of the distributions. Like most open-source software EMAN2 was designed primarily for Unix-like environments (Mac/Linux) we expend substantial human effort to keep EMAN2 working on windows, and even with these efforts, some things still do not work optimally. If you have any other choice (Linux/Mac) you will generally have a much better experience on those platforms.

Here is a simple example: on windows 7 and above, the OS puts a priority on user interactivity, to the extent that if it detects a user event (mouse click, etc.) which isn't handled by the software within a second or two, it immediately kills the program. While clearly we strive for a good interactive user-experience, there are occasional places in EMAN2 where there may be a few second delay after you tell the program to do something before it will respond again (while it does what you asked it to do). If you happen to click on a window during this time, Win7+ will kill the program, often corrupting any files being processed at the time. Windows is the only platform with this issue. While we have tried to improve this issue in various places in EMAN2 it simply isn't practical to redesign the entire system around this arbitrary constraint, so the user has to be careful.

Anyway, if you're not deterred by my doom and gloom, we do try to make installation as simple as possible, and it IS possible to use EMAN2 effectively on Windows:

  • If you have installed previous version of EMAN2. Please uninstall it and remove a directory called c:\tmp\eman2db-***.
  • For windows(XP/Vista/7 32/64), EMAN2 comes with it's own Python2.7, with preinstalled site-packages like PyQt4, PyOpenGL etc., So if you have your own Python installed, you may need uninstall it IF there is a conflict. If you need this other Python, in some cases setting up a separate account for EMAN2 can solve the problem, but there may be some software which simply cannot reasonably coexist on the same Windows machine.

  • (NOT RECOMMENDED: If you plan to install both EMAN1 and EMAN2, EMAN1 must be installed FIRST.
  • After installation, try running:
    • e2version.py
    • e2speedtest.py
    • e2display.py
  • If you get an error like:

ImportError: DLL load failed: The application has failed to start because its side-by-side configuration is incorrect.

or

ImportError: DLL load failed: This application has failed to start because the application configuration is incorrect. Reinstalling the application may fix this problem.
  • please install Visual C++ 2008 Redistributable downloaded from Microsoft or from here Download Visual C++ 2008 redistributable runtime library here..

  • Do not try to run EMAN2 programs using desktop Icons. You need to open a command prompt and run the commands from there. Even the GUI tools should be launched this way.
  • EMAN2 uses PyQt4 as GUI toolkit. It has conflict with Matlab R2007b, you need uninstall Matlab or install it in a different account, i.e. not system wide install.

  • Windows user please ignore this warning message, "WARNING: Using the out of date 'bsddb' module instead of bsddb3. Consider installing newer berkeleydb and bsddb3."
  • EMAN2 may still have problems on specific windows machines. If you run into any, please report them to sludtke@bcm.edu

  • There may be conflicts with EMAN2 and other software packages which also use python. On Linux/Mac, there are mechanisms for dealing with this, but windows lacks this. Most problems with Windows installations relate to conflicts with other software.

Environment Variable Setting For EMAN2 (All platforms)

In some rare cases, the EMAN2 installer will not be able to update your environment variables properly. In such cases, we need set up environment variables like PATH, LD_LIBRARY_PATH and PYTHONPATH for EMAN2 to work correctly. These environment variables should be automatically set when you run eman-installer script when you install binary EMAN release.

  • For sh/bash like shells on Linux/UNIX system (suppose you install EMAN2 under your home directory):

export EMAN2DIR=${HOME}/EMAN2
export PATH=${PATH}:${EMAN2DIR}/bin
export PYTHONPATH=${PYTHON_PATH}:${EMAN2DIR}/lib
# export LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:${EMAN2DIR}/lib    # This line should no longer be used (with releases after 2.06)
  • For csh/tcsh like shell on Linux/UNIX system (suppose you install EMAN under your home directory):

setenv EMAN2DIR ${HOME}/EMAN2
setenv PATH ${PATH}:${EMAN2DIR}/bin
setenv PYTHONPATH ${EMAN2DIR}/lib         #setenv PYTHONPATH ${PYTHONPATH}:${EMAN2DIR}/lib  if you have PYTHONPATH set
#setenv LD_LIBRARY_PATH ${EMAN2DIR}/lib    # This line should no longer be used (with releases after 2.06)
  • For windows users (suppose you install EMAN2 under C:\):

right click "my computer"->properties->Advanced->Environment Variables
in "system variables"edit the "path" entry, and add:
C:\EMAN2\bin;C:\EMAN2\lib;C:\EMAN2\python\Python27;C:\EMAN2\python\Python27\Lib\site-packages\PyQt4\bin.

Create a new system variable PYTHONPATH, add:
C:\EMAN2\lib;C:\EMAN2\bin.
(note: In the example I suppose you installed EMAN2 into C:\ directory, change it accordingly if you install EMAN2 in other directory.)

Note that some windows machines may have so much software installed on them that the PATH and/or PYTHONPATH may exceed their maximum length. The only real solution to this that I'm aware of is to write little shell-scripts to adjust your environment for specific uses. This should be a very unusual situation, though.

  • Sometimes international users will have issues with images not displaying correctly. This can be due to internationalization settings causing the operating system to expect "," to be the decimal separator, instead of ".". Alas only "." is compatible with pretty much all conventions in the Cyro-EM community. Setting these shell variables may help:
    • LC_CTYPE=en_US.utf8
    • LC_ALL=en_US.utf8

EMAN2/Install/BinaryInstall (last edited 2017-12-27 01:56:26 by RJEdwards)