Anaconda based Build, All Platforms (except Windows)

EMAN2 source lives on GitHub, downloading the source is part of the instructions below. Do not check it out yet.

EMAN2 has a number of dependencies, the most important of which is Python, and some of these dependencies require specific versions. Rather than struggling with system library incompatibilities and other issues, EMAN2 has adopted Anaconda as its install environment. This (FOSS) system provides a cross-platform compatible environment in which specific library versions can be installed without interfering with anything else on the system, and can support multiple such environments within one Anaconda installation. While it may still be possible to compile EMAN2 without Anaoconda, this is an unsupported approach, and you should anticipate a fair amount of effort. If you follow the instructions below, you should have a painless source build (Linux/Mac only) very quickly.

Note that even with a source build it may be difficult to get this working on systems with very old operating system installs. We normally try to support OS versions as much as 5-7 years old. Please report any problems.

GPU Support

For features which support the GPU, please complete the standard source install instructions below, then follow the GPU instructions from the binary installation page.

Installing EMAN2/SPHIRE/SPARX from source

Anaconda comes in two flavors Anaconda which is a full featured system with many libraries and capabilities built in, and Miniconda which is a stripped down version of the system. Both systems are the same, it is just a question of which packages come preinstalled. These instructions are based on the smaller Miniconda install. You may also have success with Anaconda, but a better approach may be to install Miniconda, then add in any extra packages you actually need.

We make use of the environment system in Anaconda to isolate EMAN2 dependencies from other Anaconda packages you may have installed. If you need to install other packages you wish to use in concert with EMAN2, you will need to install them within the EMAN2 environment. Be warned that sometimes installing another package may trigger a version change in one of EMAN2's dependencies, which may or may not be a problem, depending on which dependency it is. We strongly suggest getting the base EMAN2 installed and working first, before trying to install any additional packages within the same Anaconda environment.

Initial Setup

1. If you do not have Anaconda/Miniconda (or another copy of EMAN2/SPARX/SPHIRE) already installed in your account, skip to the next step. If you DO have Anaconda or Miniconda installed in your account, these instructions will be installing a new complete copy of Miniconda, so you must insure that any existing install you have is not active in your shell (not in PATH, no LD_LIBRARY_PATH or PYTHONPATH set). While it may also be possible to set up an environment for EMAN2 in your existing install, you would need to adapt these instructions to your own situation yourself to do that.

      1 echo $PATH
      2 # make sure no Anaconda/Miniconda/EMAN2 entries
      3 echo $LD_LIBRARY_PATH
      4 echo $PYTHONPATH
      5 # ideally, both return nothing. If it set to something it is possible that it may interfere with Anaconda
      6 # strongly suggest at least during the install, ''unset'' both of these. After installation you can test
      7 # to see if they cause any issues
      8 
   

2. Download and install this version of Miniconda for Linux or MacOSX.

      1 bash <Miniconda-installer>
      2 
      3 # There are a variety of options you can use, but the default command above is sufficient in most cases
      4 bash <Miniconda-installer> --help
   

   and follow the prompts. When you see Do you wish the installer to initialize Miniconda3 by running conda init?, say no, then move on to the next step.

3. Initialize conda for shell interaction. These instructions will depend on what shell you use. The default on most systems is bash. If you use a different shell ( tsch, zsh, ... ), you will need to take this into account:

      1 # for bash-like shells, such as bash and zsh
      2 source <miniconda-path>/etc/profile.d/conda.sh
      3 
      4 # for csh-like shells, such as csh and tcsh:
      5 source <miniconda-path>/etc/profile.d/conda.csh
      6 
      7 # <shell-name> is bash, fish, powershell, tcsh, xonsh or zsh
      8 conda init <shell-name>
      9 
     10 # we suggest the following, meaning you will need to use ''conda activate'' after logging in before using EMAN2
     11 conda config --set auto_activate_base False
   

   As it says after you run this command, you will need to close and reopen your shell/terminal for it to take effect. This command modified your shell initialization so the conda activate command can be used properly. For more information on conda-init and activation, see Environment Activation.

   MacOS Users (bash only)

   On MacOS, this modifies ~/.bash_profile. If you have a ~/.profile startup file, creation of ~/.bash_profile will prevent ~/.profile from being read. A simple solution is to source .profile within .bash_profile.

   For differences between login- and non-login shells and order of reading the startup files on Mac OSX, see, https://www.anintegratedworld.com/basics-of-osx-bashrc-v-profile-v-bash_profile/.

4. Configure conda.

      1 # Automatic Anaconda/Miniconda updates may cause things to break, so we suggest making all package upgrades explicitly
      2 # The current version verified to work with EMAN is '''conda 4.6.14'''
      3 conda config --set auto_update_conda False
   

5. Create a new environment with EMAN2 dependencies.

      1 conda create -n eman eman-deps=15.1 cmake=3.14 -c cryoem -c defaults -c conda-forge
   

   If you wish to see the list of conda dependencies that eman-deps is built from, look here.

6. Get EMAN code from GitHub:cryoem/eman2.

      1 cd <path-where-you-want-eman2-source>   # eg - $HOME/src
      2 git clone https://github.com/cryoem/eman2.git # this will create an eman2 folder containing the current source code from the master branch
      3 
   

7. Create a build directory (out-of-source builds are recommended).

      1 mkdir <build-directory> # eg- $HOME/src/eman2-build
      2 
   

EMAN Daily Development

1. Activate your environment.

      1 conda activate eman
   

2. Checkout source code and pull from the remote.

      1 cd <source-directory>  # <path-where-you-want-eman2-source>/eman2
      2 git checkout <branch>
      3 git pull --rebase
   

3. Build EMAN

      1 cd <build-directory>
      2 cmake <source-directory>   # - eg $HOME/src/eman2. On linux, also add -DENABLE_OPTIMIZE_MACHINE=ON
      3 
   

   • If you use cmake-gui, since conda is not in PATH anymore, cmake will fail to find the environment directory. In that case set CONDA_PREFIX to your conda environment directory manually.

   • Make sure to delete any cmake variables that cmake already found, variables like *_LIBRARY or similar, *_INCLUDE_PATH or similar, CONDA_EXECUTABLE, CMAKE_INSTALL_PREFIX and any variables that are expected to contain conda environment related values.
   • Configure and generate in cmake.

      1 make -j
      2 make install
   

4. You may also wish to run

      1 make test          # if everything passes you are fine, if there are failures, you are welcome to ask
      2 make test-verbose  # verbose test output to help to identify specific failures
      3 
   

5. To switch to another conda environment, first deactivate your current environment.

      1 conda deactivate
   

Linux Clusters

The approach above will install EMAN with a precompiled version of OpenMPI, which may or may not work with the batch queuing system on your cluster. If it does not work, the symptom will be that MPI parallel jobs will use only a single node, no matter how many you have allocated in your job. If this happens please see the linux cluster installations on the binary install page. Those instructions should also work with either of the source-based installations below.