Binary Installation Instructions v2.99

Choices

There are three ways to install EMAN2:

1. Traditional Binary Installation (includes Anaconda/Miniconda install)

   • Linux

   • Mac

   • Windows (WSL)

   • Windows (Legacy, partial functionality)

2. NEW: Install into an existing Anaconda install

3. Install from GitHub (source build)

If you are already an active Anaconda user, you may prefer approach 2 or 3, above, since it will install within your existing Anaconda system (in its own environment). Having 2 separate Anaconda installs in the same account can be a problem. We like to encourage people to use approach 3 when possible, because A) It can also use an existing Anaconda install, it will optimize the binary for the specific CPU you have and C) updating to our current development version becomes a very simple/quick process (if you run into a problem it becomes trivial to check if we have already fixed it). It does require that you have a C compiler installed on your machine, but otherwise requires little other knowledge. If you have built other scientific software from source in the past, we strongly encourage you to try method 3. Method 1 is the same method we have used to distribute EMAN2 binaries for the last several years. It includes a copy of Miniconda (a small version of Anaconda), with EMAN2 installed into an environment. Again, method 1 is NOT recommended if you already have Anaconda on your machine.

Option 2: Install into an existing Anaconda setup (all platforms, experimental)

To use this approach, you must already have Miniconda or Anaconda installed. This method is still experimental. On Windows 11 machines, this must not be a native Windows Anaconda install, but a Linux Anaconda install within a WSL environment!

You may wish to consider updating Anaconda before installing with:

conda update --all

but consider possible impact on other Anaconda environments you may have configured.

We strongly recommend installing EMAN2 within its own Anaconda/Miniconda environement:

conda create -n eman2 eman-dev -c cryoem -c conda-forge

Option 1 (Linux): Standard Binary Install

1. Cleanup: Only if you have a pre-Anaconda install of EMAN2 on your machine:

   • Please remove or rename any existing installed EMAN2 folder you might have.
   • Please remove any existing EMAN2 entries from PATH.
   • LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PYTHONPATH and PYTHONHOME are NO LONGER USED, and should be removed if you have them set.
   • If you have any of these shell variables set for use with other software, it may be necessary to remove those settings as well. If the tests below fail after installation, this is the first thing to check.

2. Download: Download EMAN2.99

3. Install:

      1 bash <path-to-EMAN2-installer>
   

   • You will be prompted for a location to install EMAN2. Note that you cannot rename this folder after installation! You must reinstall if you wish to move the installation.
   • You will be asked if you want to initialize EMAN2.

   • EMAN2 initialization will add a block of code to your .profile/.bashrc/.zshrc file. You may check this file after installation to make sure an Anaconda block exists.

4. Close Shell After installation, close your current terminal window/tab, and open a new one. The new terminal should have access to the 'conda' command. Depending on your Anaconda settings, you may need to run conda activate before using EMAN2 commands and conda deactivate to return to your normal shell settings.

5. Test: Run these programs to see if the install worked:

      1 # This will display the exact version you have installed. If you ask for help, provide the full output of this command.
      2 e2version.py
      3 # Relative speed factor of a single core on your computer, 2-3 typ.
      4 e2speedtest.py
      5 # Opens a browser window you can use to view any EMAN2 compatible file in various ways
      6 e2display.py
      7 # Creates a small image with a circle in the middle of it
      8 e2proc2d.py :64:64:1 test.hdf --process mask.sharp:outer_radius=24
      9 # Displays the file you just created
     10 e2display.py test.hdf
   

Troubleshooting and Tips

• If you have an NVidia graphics card, see ''Using the GPU'' section below.

• If you receive an "Illegal Instruction" crash, this usually means your CPU isn't compatible with the binaries. You can try a snapshot version instead of the release and see if that helps, but if still having issues, we suggest you build from source. It's a lot easier than it sounds, and will produce binaries optimized for your specific computer.

• If you get an error like the one below, dependency installation step might have failed.

  Traceback (most recent call last):
    File "/.../.../eman2/bin/e2proc3d.py", line 35, in <module>
      from past.utils import old_div
  ModuleNotFoundError: No module named 'past'

  In this case try running the dependency installation manually.

  conda install eman-deps=33.1 -c cryoem -c defaults -c conda-forge

• If you have problems with any of the test programs, the first thing to check is whether you have PYTHONPATH, PYTHONHOME, LD_LIBRARY_PATH or DYLD_LIBRARY_PATH set in your shell. While used in previous versions of EMAN, and sometimes required by other software still, they may interfere with Anaconda. If they are set to make some other software package work, but they interfere with EMAN2, you will have to unset them, and set them again only when you need the other software.

• If only the GUI fails and you are using an Nvidia graphics card, it is likely caused by a graphics card driver incompatibility. Updating the Nvidia driver usually fixes the problem. On recent Ubuntu systems, running apt-get install nvidia-current works. On other systems, you may need to follow the installation guide from Nvidia.

• You will find that when you open a new shell, you will see (base) added to your command prompt. This indicates that Anaconda, the environment EMAN2 now uses for distribution, is active, and you can run EMAN2/SPARX/SPHIRE commands.

  • If this causes issues for other software, you can type conda deactivate and EMAN2 commands will no longer work (but any software that doesn't like Anaconda will work).

  • Alternatively, you can type conda config --set auto_activate_base False, which will prevent Anaconda from being activated automatically when you open new shells. In that case you will need to do a conda activate before running EMAN2/SPARX/SPHIRE commands.

• Check continuous build sections, Notes and Troubleshooting, which may contain more up-to-date info that may be relevant here.

Option 1: Standard Binary Install (Mac)

1. Cleanup: Only if you have a pre-Anaconda install of EMAN2 on your machine:

   • Please remove or rename any existing installed EMAN2 folder you might have.
   • Please remove any existing EMAN2 entries from PATH.
   • LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, PYTHONPATH and PYTHONHOME are NO LONGER USED, and should be removed if you have them set.
   • If you have any of these shell variables set for use with other software, it may be necessary to remove those settings as well. If the tests below fail after installation, this is the first thing to check.

2. Download: Download EMAN2.99

3. Install:

      1 bash <path-to-EMAN2-installer>
   

   • You will be prompted for a location to install EMAN2. Note that you cannot rename this folder after installation! You must reinstall if you wish to move/rename the installation.

   • You will be asked if you want to initialize EMAN2. EMAN2 initialization will add a block of code to your .profile/.bashrc/.zshrc file. You may check this file after installation to make sure an Anaconda block exists.

4. Close your current terminal window (you may actually want to log out completely), then open a new terminal. The new terminal should have access to the 'conda' command. If you see (base) at the beginning of your command line, then Anaconda is active, and the following tests can be run. If you want to stop using EMAN2, you can run conda deactivate.

5. Test: Run these programs to see if the install worked:

      1 # This will display the exact version you have installed. If you ask for help, provide the full output of this command.
      2 e2version.py
      3 # Relative speed factor of a single core on your computer, 2-3 typ.
      4 e2speedtest.py
      5 # Opens a browser window you can use to view any EMAN2 compatible file in various ways
      6 e2display.py
      7 # Creates a small image with a circle in the middle of it
      8 e2proc2d.py :64:64:1 test.hdf --process mask.sharp:outer_radius=24
      9 # Displays the file you just created
     10 e2display.py test.hdf
   

Troubleshooting and Tips

• If you don't understand what the .profile instructions are talking about, this may help: https://stackoverflow.com/questions/7501678/set-environment-variables-on-mac-os-x-lion

• Beginning with Big Sur (MacOS 11) there are new security features which require you to give software permission to access specific folders. This can cause problems for many open-source software packages launched from the command line. The easiest solution is Preferences -> Security & Privacy -> Privacy -> Full Disk Access, and give Terminal full access. This will not solve every problem, and you need to be aware of potential security risks in doing this, but for most scientific users it is a good solution.

• M1/M2 Macs: Anaconda does not yet fully support native M1 software, so you will need to install the normal Mac build. The installer will say that you appear not to be running on a 64 bit machine, and ask if you wish to install anyway. Say YES. Performance is excellent even though it isn't a native build.

• Check continuous build sections, Notes and Troubleshooting, which may contain more up-to-date info that may be relevant here.

• If you receive an "Illegal Instruction" crash, this usually means your CPU isn't compatible with the binaries. If you see this on the 2.99 release and have a newer machine, try a daily snapshot. If still having issues, just build from source. It's a lot easier than it sounds.

  • We try to be as compatible as possible when building the binaries without having a strong negative impact on performance, however, recently Intel has started disabling some of the older features on its newer chips (AVX). This means the 2.99 release binaries may not run on some of the newer intel machines. We have changed the compilation now, so current snapshot versions should be compatible with the latest processors, but will now only be backwards compatible to ~2014 machines.

• If you get an error like the one below, dependency installation step might have failed.

  Traceback (most recent call last):
    File "/.../.../eman2/bin/e2proc3d.py", line 35, in <module>
      from past.utils import old_div
  ModuleNotFoundError: No module named 'past'

  Run the dependency installation manually.

  conda install eman-deps=25 -c cryoem -c defaults -c conda-forge

• If you have problems with any of the test programs, the first thing to check is whether you have PYTHONPATH, PYTHONHOME, LD_LIBRARY_PATH or DYLD_LIBRARY_PATH set in your shell. While used in previous versions of EMAN, variables are no longer used, and in some cases may interfere with Anaconda. If they are set to make some other software package work, but they interfere with the programs above, you will have to unset them, and set them only when you need the other software.

• Specifically, if only the GUI fails and you are using an Nvidia graphics card, it is likely caused by a graphics card driver incompatibility. Updating the Nvidia driver usually fixes the problem. On recent Ubuntu systems, running apt-get install nvidia-current works. On other systems, you may need to follow the installation guide from Nvidia.

• You will find that when you open a new shell, you will see (base) added to your command prompt. This indicates that Anaconda, the environment EMAN2 now uses for distribution, is active, and you can run EMAN2/SPARX/SPHIRE commands.

  • If this causes issues for other software, you can type conda deactivate and EMAN2 commands will no longer work (but any software that doesn't like Anaconda will work).

  • Alternatively, you can type conda config --set auto_activate_base False, which will prevent Anaconda from being activated automatically when you open new shells. In that case you will need to do a conda activate before running EMAN2/SPARX/SPHIRE commands.

• Check continuous build sections, Notes and Troubleshooting, which may contain more up-to-date info that may be relevant here.

Windows

While we do provide 64 bit Windows binaries for EMAN2, some functionality may be broken, so we strongly recommend using the #Windows-WSL option below if at all possible.

Notes for native Windows version:

• SPARX/SPHIRE are not supported.
• EMAN2 functionality may not be complete. You will get more complete functionality using the Linux/Bash shell approach below.
• Even for the main EMAN2 programs, native Windows support remains somewhat marginal, and is provided primarily for utility functions and basic GUI tools, like micrograph evaluation and particle picking. You are welcome to ask questions in the mailing list, but there may be limited help we can provide because we simply don't have Windows machines around for testing.

Native Win7/10 64 bit

1. Download Download EMAN2.99.

2. Launch the installer.

   1. Select Installation Type: Just Me

   2. Choose Installation Location: Select a location with NO space in path

   3. Advanced Installation Options: Don't add EMAN2 to PATH environment variable.

3. Open Anaconda Prompt by clicking Windows Start Menu -> Anaconda3 (64-bit) -> Anaconda Prompt or Start Menu -> Anaconda3 (64-bit) -> Anaconda Prompt(installation-folder-name).

4. In most cases you will want to install: Python Launcher (launchwin-1.0.1.6.msi).

5. Run these programs to see if the install worked:

   e2version.py
   e2speedtest.py
   e2display.py
   e2proc2d.py :64:64:1 test.hdf --process mask.sharp:outer_radius=24

Windows 10 - Linux/Bash shell (As of 12/15/2020)

Windows 10 includes an embedded Ubuntu Linux environment. It is possible to run the EMAN2 Linux binaries within this Win10 environment, but you will need to install some additional dependencies to do so. Also, you will effectively be running at a Linux command prompt, so you will have to become a bit familiar with Linux to do this, but it does avoid installing an additional operating system on your machine.

1. Click "Start" and type "Turn Windows Features on or off".
   • Enable "Windows Subsystem for Linux".
   • Enable "Virtual Machine Platform".

   

2. Install Ubuntu from "Microsoft Store".

   

3. Run "Ubuntu" from Start Menu.
4. Install OpenGL.

      1 sudo apt update
      2 sudo apt install libsm-dev libxrender-dev build-essential libgl1-mesa-dev mesa-utils mesa-common-dev libglu1-mesa libglu1-mesa-dev mesa-utils
      3 sudo apt autoremove
   

5. Install Xming X Server for Windows.

   • Don't forget the fonts and Mesa (OpenGL) modules! If it seems to work, but the letters are black boxes, or you have other visual artifacts, the problem is probably with OpenGL support.

6. Download and install LINUX binary, not windows binary! Download EMAN2.99, #Linux.

   Make sure to follow the instructions for shell initialization using conda-init.

7. Start X Server and set environment variables.

      1 export DISPLAY=:0
      2 glxinfo | grep OpenGL
   

   

8. Run these programs to see if the install worked:

      1 e2version.py
      2 e2speedtest.py
      3 e2display.py
      4 e2proc2d.py :64:64:1 test.hdf --process mask.sharp:outer_radius=24
   

   

Using NVidia GPUs

Currently, GPUs are only used for a few specific programs involving deep learning, such as tomogram annotation, particle picking and GMM variability analysis.

This support is limited to Linux, and (potentially with some extra effort) Win 11 with an LSW2 installation.

Many machines will have CUDA installed already, and if CUDA is an appropriate version, this should work fine with the TensorFlow version shipped with EMAN2. However, if you are running newer versions of CUDA there may be problems. You can test compatibility quickly with:

# Make sure you have your environment set to run EMAN2 programs
e2version.py
# The above command should work and return your current version. If it does, then run:
python -c "import tensorflow"

If this command does not return an error, then you should be able to run deep learning software within EMAN2. If it does raise an error, then you will need to debug the problem:

• If you do not have CUDA installed at all (and you are on a Linux machine with an NVidia GPU):
  • Installation depends on linux distribution, try your package manager for CUDA and/or CUDA-toolkit, for example, on Ubuntu:

    apt-get install nvidia-cuda-toolkit

• If the version of CUDA you have installed is incompatible, then you will need to get a compatible tensorflow installed in your Anaconda environment. Here is one possible suggestion:

  conda remove tensorflow-gpu tensorflow-gpu-base
  pip install tensorflow
  # read any messages carefully, if there are errors you may need other installations

If you have problems you cannot figure out, feel free to post questions to the EMAN2 Google Group.