-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Updated installation instrctions to use Conda
- Loading branch information
1 parent
5eb53db
commit d734ee0
Showing
2 changed files
with
114 additions
and
119 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,87 +3,146 @@ | |
| Installation | ||
| ============ | ||
|
|
||
| Clone the repository: | ||
| Full installation | ||
| ***************** | ||
|
|
||
| The most convenient way to install ASCOT5 is to use Conda: | ||
|
|
||
| .. code-block:: bash | ||
| git clone https://github.com/ascot4fusion/ascot5.git | ||
| cd ascot5 | ||
| conda env create -f environment.yaml | ||
| conda activate ascot-env | ||
| make libascot -j | ||
| make ascot5_main -j # Also bbnbi5 if needed | ||
| pip install -e . | ||
| .. rubric:: Requirements | ||
|
|
||
| - C compiler | ||
| - HDF5 | ||
| - OpenMP | ||
| - Python3.10 (pre- and postprocessing) | ||
| - MPI (optional) | ||
| - VTK (optional, for 3D wall visualization) | ||
| To use the Conda environment in your batch script, add the following lines: | ||
|
|
||
| See :ref:`here<Compiling>` for tips on how to compile the code on different platforms. | ||
| .. code-block:: bash | ||
| Minimal Installation | ||
| ******************** | ||
| eval "$(conda shell.bash hook)" | ||
| conda activate ascot-env | ||
| For running ASCOT5 on this platform and performing pre- and post-processing on another platform: | ||
| The simulation options are edited with the local text editor, which usually happens to be ``vim``. | ||
| Consider adding the following line to your ``.bashrc`` (or ``.bash_profile`` if working locally): | ||
|
|
||
| .. code-block:: bash | ||
| cd ascot5 | ||
| make ascot5_main | ||
| export EDITOR=/usr/bin/emacs | ||
| The binary is located at ``build/ascot5_main``. | ||
| .. note:: | ||
| Whenever there is a new release, you can update the code as: | ||
|
|
||
| Full Installation | ||
| ***************** | ||
| .. code-block:: bash | ||
| For full installation both ascot5_main and libascot.so are needed: | ||
| git pull | ||
| make clean | ||
| make ascot5_main -j | ||
| make libascot -j | ||
| .. code-block:: bash | ||
| Always use the ``main`` branch when running simulations unless you specifically need something from a feature branch. | ||
|
|
||
| cd ascot5 | ||
| make ascot5_main | ||
| make libascot | ||
| Test that ASCOT5 was properly installed by running the :ref:`introduction<Tutorial>`. | ||
|
|
||
| Python Library (a5py) | ||
| ********************* | ||
| .. note:: | ||
| The default instructions install ASCOT5 without MPI, but MPI is recommended for running simulations on multiple nodes. | ||
|
|
||
| Useful even for minimal installation; it provides command-line tools for updating simulation options. | ||
| You can use either MPI packaged with Conda (``openmpi`` or ``mpich``): | ||
|
|
||
| Create a virtual environment (optional but recommended), activate it, and install ``a5py``: | ||
| .. code-block:: bash | ||
| .. code-block:: bash | ||
| conda install hdf5=*=*openmpi* mpi=*=*openmpi* | ||
| cd .. | ||
| virtualenv -p python3 --system-site-packages ascotenv | ||
| source ascotenv/bin/activate | ||
| pip install -e ascot5/ | ||
| or the native MPI library: | ||
|
|
||
| .. note:: | ||
| Whenever there is a new release, you can update the code as: | ||
| .. code-block:: bash | ||
| module load <local-mpi-library> | ||
| mpirun -V # Prints the version of the MPI library to be used in the next line | ||
| conda install "<local-mpi-library>=x.y.z=external_*" | ||
| which mpicc # Copy this path to the following commands | ||
| export HDF5_CC=path_to_mpicc | ||
| export HDF5_CLINKER=path_to_mpicc | ||
| Conda does not have all versions of MPI libraries available, so one might have to use asterix in minor version number, e.g. | ||
|
|
||
| .. code-block:: bash | ||
| cd ascot5 | ||
| git pull | ||
| git checkout main | ||
| make clean | ||
| make ascot5_main | ||
| make libascot | ||
| conda install "openmpi=4.*=external_*" | ||
| .. admonition:: Troubleshooting | ||
|
|
||
| Conda complains that ``freeqdsk`` was not found or could not be installed. | ||
|
|
||
| - Remove ``freeqdsk`` from ``environment.yaml`` and install it with ``pip`` once the environment is activated. | ||
| The cause of this error is unknown. | ||
|
|
||
| Make stops since ``libhdf5*.a`` could not be located. | ||
|
|
||
| Always use the branch ``main`` when running simulations unless you specifically need something from a feature branch. | ||
| - The compiler should be using shared libraries, not static. | ||
| Add the following flag for the compiler: ``make ascot5_main FLAGS="-shlib"`` | ||
|
|
||
| .. rubric:: (Optional) | ||
| Minimal installation (for HPC usage) | ||
| ************************************ | ||
|
|
||
| Add the following lines to your `.bashrc` and/or `.bash_profile`: | ||
| A typical way to use ASCOT5 is to run simulations on a computing cluster and carry out pre- and postprocessing on a home cluster or a workstation. | ||
| Building the code from the source (without Conda) provides a light installation with the capability to run simulations using native libraries and perform limited pre- and post-processing. | ||
|
|
||
| .. rubric:: Requirements | ||
|
|
||
| - C compiler | ||
| - HDF5 | ||
| - OpenMP | ||
| - MPI | ||
| - Python3.10 | ||
|
|
||
| 1. Install the requirements or use the module system. | ||
|
|
||
| 2. Download the source and set up the virtual environment: | ||
|
|
||
| .. code-block:: bash | ||
| git clone https://github.com/ascot4fusion/ascot5.git | ||
| python -m venv ascot-env | ||
| source activate ascot-env/bin/activate | ||
| 3. Install ``a5py`` and compile the executables which will be located at ``build/``: | ||
|
|
||
| .. code-block:: bash | ||
| cd ascot5 | ||
| pip install -e . | ||
| make ascot5_main -j # Also bbnbi5 if needed | ||
| See :ref:`here<Compiling>` for tips on how to compile the code on different platforms. | ||
|
|
||
| (**Optional**) Add the following lines to your `.bashrc`: | ||
|
|
||
| .. code-block:: | ||
| <module loads and exports here> | ||
| export EDITOR=/usr/bin/emacs # To use emacs when editing options | ||
| source activate /path/to/ascot5env | ||
| This will automatically activate ASCOT5 environment each time you open a terminal or login. | ||
|
|
||
| Test that ASCOT5 is working by running the :ref:`introduction<Tutorial>`. | ||
|
|
||
| For Developers | ||
| ************** | ||
|
|
||
| This is a full installation from the source (using Conda) and with the optional packages present that are required to build ``ascot2py.py`` and the documentation. | ||
| Note that the first step requires you to add SSH keys on GitHub whenever on a new machine. | ||
|
|
||
| .. code-block:: bash | ||
| git clone [email protected]:ascot4fusion/ascot5.git | ||
| cd ascot5 | ||
| conda env create -f environment-dev.yaml | ||
| conda activate ascot-dev | ||
| make libascot -j | ||
| make ascot5_main -j | ||
| pip install -e . | ||
| .. _Compiling: | ||
|
|
||
|
|
@@ -93,16 +152,6 @@ Compiling on different platforms | |
| ASCOT5 doesn't support CMake (yet) so it is up for the user to provide the required libraries. | ||
| Here we have listed some platforms where ASCOT5 has been used and how it was compiled. | ||
|
|
||
| Aalto desktops | ||
| ************** | ||
|
|
||
| .. code-block:: bash | ||
| pkcon install hdf5-helpers | ||
| pkcon install libhdf5-dev | ||
| pkcon install hdf5-tools | ||
| make -j ascot5_main FLAGS="-foffload=disable" | ||
| CSC.fi puhti | ||
| ************ | ||
|
|
||
|
|
@@ -287,23 +336,6 @@ For Intel: | |
| (Add -xcommon-avx512 to optimize for skl/csl nodes) | ||
|
|
||
| Vdiubuntu.aalto.fi | ||
| ****************** | ||
|
|
||
| Compiling libascot.so requires that you change Makefile as | ||
|
|
||
| .. code-block:: | ||
| libascot.so: libascot.o $(OBJS) | ||
| - $(CC) $(CFLAGS) -o $@ $^ | ||
| + $(CC) $(CFLAGS) -o $@ $^ -lhdf5_hl -lhdf5 | ||
| .. code-block:: bash | ||
| module load hdf5 | ||
| make MPI=0 libascot.so CC=gcc FLAGS="-foffload=disable" -j | ||
| .. _Compilerflags: | ||
|
|
||
| EUROfusion gateway | ||
|
|
||