While the instructions look long, in reality it should only take 10-15 minutes to complete the entire process (with a decent network connection).
WARNING FOR EXISTING USERS of EMAN >2.9 - If your last source build was before 8/21/24, on that date we updated the eman-dev conda-forge dependencies to use Python 3.12. This Python version has some backwards incompatibility, and using it requires setting up a fresh EMAN2 Anaconda environment, or you will get a variety of errors. If you are in this situation:
This section only needs to be completed once. If you have a working EMAN2 source installation and just wish to update, skip ahead to Build and Install.
1. Check your account for possible problems
#!highlight bash echo $PATH # make sure no Anaconda/Miniconda/old EMAN2 entries: echo $LD_LIBRARY_PATH echo $PYTHONPATH # ideally, both return nothing. If it set to something it is possible that it may interfere with Anaconda # strongly suggest at least during the install, //unset// both of these. After installation you can test # to see if they cause any issues
2. Download and install
#!highlight bash bash <MiniForge-installer>
and follow the prompts. When you see Do you wish to update your shell profile to automatically initialize conda?, say yes, then move on to the next step.
Please ignore any references to micromamba in the text displayed by the installer and just follow these instructions.
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 that into account:
##
#!highlight bash ## # for bash-like shells, such as bash and zsh ## source <MiniForge-path>/etc/profile.d/conda.sh ## ## # for csh-like shells, such as csh and tcsh: ## source <MiniForge-path>/etc/profile.d/conda.csh ## ## # <shell-name> is bash, fish, powershell, tcsh, xonsh or zsh ## conda init <shell-name> ##
You will need to close and reopen your shell/terminal for the installation to take effect!.
For more information on conda-init and activation, see Environment Activation.
4. Configure and update conda.
#!highlight bash # We suggest the following, meaning you will need to use //conda activate// after logging in before using EMAN2 conda config --set auto_activate_base False # Automatic conda updates may cause things to break, so we suggest making all package upgrades explicitly conda config --set auto_update_conda False # If you have Anaconda, not miniforge, you may need to install mamba separately. If you used miniforge as described above, you should already have **mamba** # conda install mamba -c conda-forge # Update base environment to get the latest conda mamba update --all -n base # Mac M1/M2/... users, if you get an error in the previous step see Troubleshooting below
5. Create a new environment with EMAN2 dependencies. eman2 below is the name of the environment. You may make this whatever you like, as long as you remember to use the same name when doing conda activate. Note that this name will appear as part of your prompt when activated, so you may want to keep it short.
#!highlight bash mamba create -n eman2 eman-dev --only-deps -c cryoem -c conda-forge
If, and ONLY if, you are installing on a headless machine without graphics, you can alternatively set up the non-GUI variant which will not have pyqt and pyopengl. Doing this will severely limit EMAN2's capabilities:
#!highlight bash mamba create -n eman2 'eman-dev=*=nogui_*' --only-deps -c cryoem -c conda-forge
List of dependencies: If you wish to see the list of conda dependencies that eman-dev is built from, look here. Some of the dependency versions are listed in the appropriate file under .ci_support.
6. Ensure you have OpenGL:
EMAN2 uses OpenGL (via !PyQt) for all of its graphics. OpenGL installation depends on OS variant and, for example, whether you are using proprietary NVidia drivers under Linux. You will need to have OpenGL set up on your machine as a whole before continuing. On Mac, you should already have this with XCode. On Linux with an NVidia driver you will likely also need to install the Mesa header files. If you aren't sure how to set up OpenGL, Google can probably help.
7. Get EMAN code from GitHub:cryoem/eman2.
#!highlight bash cd <path-where-you-want-eman2-source> # eg - $HOME/src git clone https://github.com/cryoem/eman2.git # this will create an eman2 folder containing the current source code from the master branch
8. Create a build directory (out-of-source builds are recommended).
#!highlight bash mkdir <build-directory> # eg- $HOME/src/eman2-build
9. GPU/deep learning Install JAX per the next section for GPU support. JAX is required for virtually all of the new EMAN3 programs
Older EMAN2 programs make use of Tensorflow for Deep Learning/GPU support, but we have been gradually migrating to the new JAX library, so having both installed is strongly suggested.
When you start a new shell, these are the steps you will need to take before running EMAN programs or compiling the system:
10. Activate your environment. If you used a different name above, use it here too.
#!highlight bash conda activate eman2
11. Update and Checkout source code. Periodically you should update your source using standard git techniques.
#!highlight bash cd <source-directory> # <path-where-you-want-eman2-source>/eman2 git fetch --all --prune # get remote branches and cleanup non-existing remote branches from local repo git checkout master # to make sure you are building from the current master build rather than a branch someone is working on git pull # This is what actually updates your local copy of the code
12. CMake
#!highlight bash cd <build-directory> # on Mac: cmake <source-directory> # - eg $HOME/src/eman2, optionally add -DCMAKE_VERBOSE_MAKEFILE # on Linux: cmake <source-directory> -DENABLE_OPTIMIZE_MACHINE=ON # - eg $HOME/src/eman2, optionally add -DCMAKE_VERBOSE_MAKEFILE
13. Make
#!highlight bash make -j 8 make install # To install sphire make install-sphire
Note that the make -j 8 above will compile using 8 threads. On some machines omitting the 8 will compile faster and cause no problems, and if you have more than 8 threads on your machine, you can increase the number.
14. Other Environments. To switch to another conda environment (stop working with EMAN2), first deactivate your current environment.
#!highlight bash conda deactivate
Solutions to potential known problems will be listed here. If these don't help, please report your problem (http://groups.google.com/group/eman2):
/home/steve/miniconda3/envs/eman2/lib/libstdc++.so.6: version `GLIBCXX_3.4.29' not found
Simply removing the offending libstdc++.so file will normally resolve this issue.
If you encounter problems, PLEASE report them, either via direct email to sludtke@bcm.edu or to the Google Group. When doing so:
Please, provide the output of the following commands when reporting a problem. Record the session via script command. This, also, records the commands, and you can just submit the full text file with your problem report.
1.
#!highlight bash script filename.txt conda activate eman2 conda info -a conda list conda list --explicit cd <source-dir> git status git log -1 cd <build-dir> rm CMakeCache.txt cmake <source-dir> cmake . -LA make clean make -j make install make test-verbose conda deactivate exit # or Ctrl+D
2. Send filename.txt.
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. Currently, we do not have alternative OpenMPI installation instructions.