Skip to content

installAMUSE.md

Jump to bottom
Gijs Vermariën edited this page Sep 7, 2023 · 15 revisions

Installing AMUSE

Why even install AMUSE?

AMUSE encapsulates over 50 codes and allows you to combine many of them to simulate scenarios that could easily take years of custom integration were you to combine the codes by hand. Compiling all 50 packages combined in AMUSE separately would take a considerable effort, so AMUSE definitely improves on the user experience (not to speak about the joy of interacting directly with fortran code!). Still, choosing the right path to installing AMUSE can save you a headache. This guide is tailored towards Leiden observatory graduate students, so maybe not all codes will compile, but enough will compile to get your started on a trajectory of computational astrophysics. Below I will briefly outline my installation recommendations for your own laptop and a common usage scenario of using the university workstations or local clusters like ALICE. Read briefly the outline of the use cases and the recommended installation instructions and then proceed to the corresponding section.

Choosing a path of least resistance.

Leiden Observatory student/staff

You might be taking the course "Simulation and Modeling in Astrophysics", this means you are a student at the Leiden observatory, and IT will have provided you with an install of AMUSE. You can use the Leiden workstations (pczaalXX, studentXX, or any "staff" workstation with the name of a Dutch lake, with permission of the user!), the virtual desktop or the ALICE tier 2 cluster. Please go here

MacOS (arm64/Intel)

Being the owner of a Macbook you can successfully use a portion of the AMUSE pacakges. You can either install AMUSE with macports from scratch with the following instructions. However this requires you to not use conda and homebrew for any other compilers, so your milage may vary. Alternatively you can try to see which codes do compile with the clang compiler (not officially supported) to get used to AMUSE and then move to an observatory system/cluster as you get more familiar.

Windows

In this case I recommend to use the Windows Subsystem for Linux to install AMUSE in. You can either use pip install to install all packages, or compile from source. Link

More to follow

Linux

You can just follow the instructions for installing your dependencies and then install everything via pip / compile from scratch. Ensure you have the right dependencies, and then install with either pip or compile from source. Link

On conda and virtual environments:

First of all, let me advice you to always use virtual environments. It costs you only one command every time you open the terminal to activate the right environment, but breaking your installation (without any noticeable errors!) because you are doing 2-3-4-...-N projects with your one golden Python install is just bad practice and easy to avoid!

Conda

Conda is an excellent tool when you work on your local system, especially since it provides a graphical user interface for their package manger for novice users. Please actually make sure you make a new environment for this course though! Conda however is less than ideal however on institute workstations and high performance compute, this is because it will bring all its own binaries (eating up your valuable home disk space unless configured correctly) and it will not use any of the excellent packages the IT already installed for you (probably with a better idea of which optimizations and versions you need!)

On non unix operating systems (macOS and Windows) primarily, it is a really good tool and I would advice you to use it. A tutorial on using conda

Virtualenv

Virtual environment are the Python native solution to managing many different environments. One of the primary benefits on observatory systems is that you can load a good version of Python on your observatory system with the command module load Python. This will load the default version of Python for your system that the IT already installed. This ensure you always know what version of Python you are using (check: module list). After doing so, you can create a virtual environment in your project directory with the following command:

python -m venv name_of_this_virtual_environment

After creating this a name_of_this_virtual_environment directory is created with a virtual environment in it, how convenient! Now activate it:

source name_of_this_virtual_environment/bin/activate

The primary benefit of this is that now your virtual environment is in the same directory as your project (if you ran the command in the right spot). Now you can continue to install things, don't forget to load Python and the virtual environment on every reopening of your terminal!

Installation with pip

This is preferable if you have a personal system that you want to use AMUSE on. Pip installation is great for linux as many wheels are built for this target, in the case of MacOS you can try pip, but you might get more success with compilation from source.

Notes on installation from pypi

Sometimes the installer of the default amuse package will fail to install some packages and not install everything, in this case you can always install AMUSE by just installing each package you need:

pip install amuse-framework
pip install amuse-$(community_code_name)

Installation from source

You will only succesfully install packages you have the right dependencies for, make sure you have gcc, fortran, nvidia installed correctly before attempting this. At the end, verify that the codes that you need are in the succesfully installed list. If not they are not, check out the error for the specific code.

In order to install from the source you first need to clone amuse from github:

git clone https://github.com/amusecode/amuse.git

After that you need to go into the directory, pip install the package and run the develop_build (which actually tries to compile all packages!):

cd amuse
pip install -r requirements.txt
pip install -e .
python setup.py develop_build

Using AMUSE on vdesk or a strw system (NOVICE)

**Since the module uses conda already, do not use virtualenv, rather use python directly. If you need to install packages, create a conda environent with the site-packages: conda create --name myenv --system-site-packages. **

You can follow these instructions from your Leiden strw desktop or from the vdesk.

At the Leiden observatory, most scientific software is available via the module system. To see which software you can access on the pc, use the following command:

module available

During this course you will need the most recent version of AMUSE, so please find the module AMUSE/2023.5.1 in the list. We will try to load this module with the load command:

module load AMUSE/2023.5.1

Now, we need to check it actually did something, by checking what is loaded with:

module list

You will now probably see a whole bunch of packages show up! On my system I get:

→ module list

Currently Loaded Modules:
  1) Miniconda3/4.9.2               6) numactl/2.0.14-GCCcore-11.3.0     11) OpenSSL/1.1                      16) UCC/1.0.0-GCCcore-11.3.0    21) ScaLAPACK/2.2.0-gompi-2022a-fb
  2) GCCcore/11.3.0                 7) XZ/5.2.5-GCCcore-11.3.0           12) libevent/2.1.12-GCCcore-11.3.0   17) OpenMPI/4.1.4-GCC-11.3.0    22) AMUSE/2023.5.1
  3) zlib/1.2.12-GCCcore-11.3.0     8) libxml2/2.9.13-GCCcore-11.3.0     13) UCX/1.12.1-GCCcore-11.3.0        18) gompi/2022a
  4) binutils/2.38-GCCcore-11.3.0   9) libpciaccess/0.16-GCCcore-11.3.0  14) libfabric/1.15.1-GCCcore-11.3.0  19) OpenBLAS/0.3.20-GCC-11.3.0
  5) GCC/11.3.0                    10) hwloc/2.7.1-GCCcore-11.3.0        15) PMIx/4.1.2-GCCcore-11.3.0        20) FlexiBLAS/3.2.0-GCC-11.

This shows that all the dependencies of AMUSE have been loaded correctly. AMUSE requires several pieces of software to work correctly, and this is an efficient way of the observatory IT of making sure we have the correct of everything!

Now we need to make sure that we actually use the correct python (the one that has AMUSE installed!). You can do so using the which command:

→ which python
/easybuild/easybuild/fc37/software/AMUSE/2023.5.1/bin/python

Jupyter is now included in the module for you, you can check this with

-> which jupyter
/easybuild/easybuild/fc37/software/AMUSE/2023.5.1/bin/jupyter

So you can just easily start your notebook/lab and get to work with UCLCHEM.

Using Visual Studio Code to work remotely on observatory systems (ADVANCED)

Here I will briefly schedule a workflow that I personally use to effectively use the observatory systems. You will need to install the following things:

Installing AMUSE with conda on Apple Silicon

Currently clang is not officialy supported by AMUSE. This is just a guide to get it working as best as possible on your local macbook, it will probably carry you through most tutorials, but you will inevitably have to move to a strw system towards the end of the course. Some basic codes like bhtree will not work since they rely on gcc.

Disclaimer: do not upgrade MacOS version during the course! This might break your install.Warning: if you encounter errors at some point, just report them sooner than later. I cannot execute steps 1,2 so it might be I missed a small detail.Step 0: Ensure you don’t use brew python/gcc/fortran as it could interfere with these instructions.
Step 1: Install xcode (might take a while!) https://apps.apple.com/us/app/xcode/id497799835?mt=12
Step 2: Install miniconda: https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
Step 3: Create a new conda environment and use it:

conda create -n amuse
conda activate amuse

Step 4 (Intel): Configure your environment to use the correct AMD64 binaries:

conda config --env --set subdir osx-64

Step 4 (arm): Configure your environment to use the correct arm64 binaries:

conda config --env --set subdir osx-arm64

Step 5: Install most common dependencies (non-exhaustive, there might be other libraries needed to compile some AMUSE packages):

conda install -c conda-forge gfortran clang openmpi fftw cmake openlibm python

Step 6: clone the AMUSE csource code:

git clone https://github.com/amusecode/amuse.git
cd amuse

Step 7 Add all the correct paths for your openmpi installation to the config.mk. These must be the path of you amuse environment! (check which python in case you don't know where your environment is located, mine is /Users/gijsv/opt/miniconda3).

#
# MPI Compilers
#
MPI_ENABLED=yes
MPICXX=/Users/gijsv/opt/miniconda3/envs/amuse/bin/mpicxx
MPICC=/Users/gijsv/opt/miniconda3/envs/amuse/bin/mpicc
MPIFC=/Users/gijsv/opt/miniconda3/envs/amuse/bin/mpif90
MPIEXEC=/Users/gijsv/opt/miniconda3/envs/amuse/bin/mpiexec
And make sure your MPI compiler is set:

And export the correct C compiler for MPI:

export OMPI_CXX=clang++

Step 8:
Go through all the installation steps

pip install -r requirements.txt
pip install .
python setup.py develop_build

In case you encounter issues at any point, walk through these common errors:

  1. ld errors https://stackoverflow.com/questions/69236331/conda-macos-big-sur-ld-unsupported-tapi-file-type-tapi-tbd-in-yaml-file answer by thomaskeefe often fixes it.
  2. fortran 13.0.0 errors This means that you have a version of fortran that doesn’t yet know about the newest version of MacOS (which is the 13.0 it is refering to). Try upgrading to a newer version of fortran, like so: conda install -c conda-forge gfortran=XX.X where XX.X is the latest build you can find for osx-arm64 here: https://anaconda.org/conda-forge/gfortran_osx-arm64/files In case the problem persists, check (with conda list) that you have no permutation of gfortran like libgfortran that is still on the older version (this will still throw errors!) In case of doubt, try restarting with a new environment from step 3.
  3. X86_intel_some_other_strings.gfortran not found. In case you get this error,  you probably had gfortran installed with brew, didn’t install it properly before installing part of AMUSE or some other fortran related problem. which gfortran  should only point to files in your conda directory, if it points to anything else you need to deinstall those versions of fortran. Then repeat from step 3.
  4. If you get error such as: > No such file or directory: ‘arm64-apple-darwin20.0.0-clang++’ Please make sure that you have the binary clang++ in your conda bin. If you have it, but not the version mentioned above. Link the two in this bin via a command ln -s clang++ arm64-apple-darwin20.0.0-clang++. This advice extends to any variations such as clang, gortran etc.

Footnote

Please refer to this page for the complete installation instructions.

Clone this wiki locally