EMAN Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Standard instructions for installing EMAN2/3 on Linux, macOS and WSL2 (Windows) ======

----

**While the instructions look long, in reality it should only take 10-15 minutes to complete the entire process (with a decent network connection).**

  * We use [[https://github.com/conda-forge/miniforge/releases|conda-forge]] for a working environment and most of the dependencies. While it may be possible to build the system without using conda-forge, we do not recommend doing this, and cannot provide support for a non-conda approach. If you follow the instructions below, you should have a painless source build very quickly.

  * We make use of the [[https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html|environment]] system in [[https://docs.conda.io/en/latest/|conda]] to separate EMAN2 dependencies from other conda or system 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 conda 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 conda environment. If you don't need to use EMAN2 and the other package in the same environment, we suggest making a separate environment for the other software.

----
**//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**:
  * remove your current EMAN2 build folder (not the source, just the folder where you run make from)
  * conda env remove -n eman2    (remove your existing EMAN2 environment)
  * Follow the instructions below starting with **Make a new Environment**

===== Initial Setup =====
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** 
    * IF you have conda-forge, mini-forge or Anaconda already installed in your account, and wish to try setting up EMAN2 as a new environment skip ahead to //Configure and update conda//. This may or may not work, depending on the age of your previous Anaconda install.
    * Otherwise:
 <code>#!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
</code>

 2. **Download and install** 
    * Note: If your site has an Anaconda license, you are welcome to use the conda provided by a proper Anaconda/MiniConda installation. Using mini-forge, which provides 'conda' and 'mamba' command line tools is completely FOSS. All EMAN2 dependencies are provided by conda-forge and make no use of the Anaconda mainline repository, so require no licensing agreement (as far as we can determine).

    * Download the !MiniForge installer: [[https://github.com/conda-forge/miniforge/releases|Installers]] (for your platform)

    * Install:
 <code>#!highlight bash
bash <MiniForge-installer>
</code>
 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:

## <code>#!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>
## </code>

 **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 [[https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment|Environment Activation]].

 4. **Configure and update conda.**
 <code>#!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
</code>

 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.


 <code>#!highlight bash
mamba create -n eman2 eman-dev --only-deps -c cryoem -c conda-forge
</code>

 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:

 <code>#!highlight bash
mamba create -n eman2 'eman-dev=*=nogui_*' --only-deps -c cryoem -c conda-forge
</code>


 **List of dependencies: **If you wish to see the list of conda dependencies that **eman-dev** is built from, look [[https://github.com/cryoem/eman-feedstock/blob/master/recipe/meta.yaml|here]]. Some of the dependency versions are listed in the appropriate file under [[https://github.com/cryoem/eman-feedstock/tree/master/.ci_support|.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 [[https://github.com/cryoem/eman2|GitHub:cryoem/eman2]].
 <code>#!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
</code>

 8. **Create a build directory** (out-of-source builds are recommended).
 <code>#!highlight bash
mkdir <build-directory> # eg- $HOME/src/eman2-build
</code>
 9. **GPU/deep learning** Install JAX per the next section for GPU support. JAX is required for virtually all of the new EMAN3 programs 

===== GPU Aceleration & Deep Learning =====
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.

  * Tensorflow
    * Should be installed automatically as part of the EMAN2 environment setup above
    * You can check to see what version of Tensorflow and whether it is GPU accelerated with: "conda list|grep tensorflow". On a machine with an NVIDIA GPU and properly configured drivers, you should see a tensorflow version like "2.17.0    cuda120py312h02ad488_203". This says that you are using the CUDA 12.0, Python 3.12 version of tensorflow 2.17.0. If you see "cpu" instead of "cuda" then you do not have GPU acceleration, and you will need to sort that out.

  * JAX
    * While it is possible to install JAX using conda/mamba, it can be difficult to find a version of GPU JAX and a version of GPU Tensorflow which will install properly together this way.
    * Instead, we strongly suggest just installing JAX using pip:
      * conda activate eman2
      * Linux (NVIDIA): pip install "jax[cuda12] optax"     
      * Other (cpu): pip install jax optax
    * see [[https://pypi.org/project/jax/]] for up to date JAX instructions, this may change more frequently than this page is updated

===== Build and Install: Daily development, Update code, etc. =====

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.
 <code>#!highlight bash
conda activate eman2
</code>

 11. **Update and Checkout source code**. Periodically you should update your source using standard git techniques.
 <code>#!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
</code>

 12. **CMake**
 <code>#!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
</code>
    * **cmake-gui**
      * 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.
    * **ccmake**
      * If you use **ccmake**, you may get an error related to OpenGL. If this happens try quitting ccmake and running it again.

 13. **Make**
 <code>#!highlight bash
make -j 8
make install

# To install sphire
make install-sphire  
</code>

 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.

===== Test install =====
  * e2version.py
  * e2speedtest.py
  * e2display.py (not for clusters without GUI environments configured)
  * note: "make test" is not recommended for individual installs, this tool is primarily aimed at developers making changes in the core of the system. It is not uncommon for one or more tests to fail, and there is no need to report such failures. In most cases this is a problem with the test, not a problem with the system.

 14. **Other Environments**. To switch to another conda environment (stop working with EMAN2), first deactivate your current environment.
 <code>#!highlight bash
conda deactivate
</code>

==== Troubleshooting ====
Solutions to potential known problems will be listed here. If these don't help, please report your problem (http://groups.google.com/group/eman2):

  *  **macOS** Users (bash only)
    * On macOS, installation 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 macOS, see, [[https://www.anintegratedworld.com/basics-of-osx-bashrc-v-profile-v-bash_profile/]].

  * If using a newer C compiler on Linux, you may encounter an error like:
 <code>
/home/steve/miniconda3/envs/eman2/lib/libstdc++.so.6: version `GLIBCXX_3.4.29' not found
</code>
 Simply removing the offending libstdc++.so file will normally resolve this issue.

  * Compilers on CentOS 6 and 7, do not support gcc's dual ABI feature which is needed to compile EMAN2's modern C++ code. On our build machine, devtools-7 and devtools-11 have been tested and confirmed to fail to compile EMAN2 code. The only solution to this is to install a compatible C++ compiler. This issue effects many packages in addition to EMAN2, so googling "g++ dual abi centos" will likely yield useful results.

===== Reporting Problems =====

If you encounter problems, PLEASE report them, either via direct email to sludtke@bcm.edu or to the [[https://groups.google.com/group/eman2|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. <code>#!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
</code>

 2. Send **filename.txt**.



===== 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. Currently, we do not have alternative OpenMPI installation instructions.