Skip to content

installation.rst

Latest commit

 

History

History
459 lines (310 loc) · 16.6 KB

installation.rst

File metadata and controls

459 lines (310 loc) · 16.6 KB

Installation

Quick Install for Python users

To install IMAS-Core via pip for Python users:

pip install imas-core
python -c "import imas_core"

Requirements

  • Python 3.8+
  • Linux (fully supported)

Binary wheels are provided for all platforms, so you don't need to compile anything.

Still not working?

See :doc:`../troubleshooting` for common issues.

Build and Install from Source

This page describes how to build and install the IMAS-Core from source code.

IMAS-Core

To build the IMAS-Core you need:

  • Git
  • A C++11 compiler (tested with GCC and Intel compilers)
  • CMake (3.16 or newer)
  • Saxon-HE XSLT processor
  • Boost C++ libraries (1.66 or newer)
  • PkgConfig

On Windows - Visual Studio 2022 with:

  • Desktop Development with C++
  • C++ Make Tools for Windows
  • CMake (included with Visual Studio)

The following dependencies are only required for some of the components:

  • Backends
    • HDF5 backend: HDF5 C/C++ libraries (1.8.12 or newer)
    • MDSplus backend: MDSplus libraries (7.84.8 or newer)
    • UDA backend: UDA libraries (2.7.5 or newer) [1]
[1]When installing UDA, make sure you have Cap'n'Proto installed in your system and add its support by adding the CMake switch -DENABLE_CAPNP=ON when configuring UDA.

Standard environments:

.. md-tab-set::

    .. md-tab-item:: Ubuntu 22.04

        The following packages provide most requirements when using Ubuntu 22.04:

        .. code-block:: bash

            apt install git build-essential cmake libsaxonhe-java libboost-all-dev \
                pkg-config libhdf5-dev xsltproc libblitz0-dev gfortran \
                default-jdk-headless python3-dev python3-venv python3-pip

        The following dependencies are not available from the package repository,
        you will need to install them yourself:

        -   MDSplus: see their `GitHub repository
            <https://github.com/MDSplus/mdsplus>`__ or `home page
            <https://mdsplus.org/>`__ for installation instructions.
        -   UDA: see their `GitHub repository <https://github.com/ukaea/UDA>`__ for more
            details.
        -   MATLAB, which is not freely available.

    .. md-tab-item:: Windows with Visual Studio

        First, set up vcpkg:

        .. code-block:: bash

            git clone https://github.com/microsoft/vcpkg.git
            cd vcpkg # VCPKG_INSTALLATION_PATH
            bootstrap-vcpkg.bat

        Then run these commands in PowerShell before building:

        .. code-block:: powershell

            $env:PATH += ";C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin\"
            $env:PATH += ";C:\Program Files\Microsoft Visual Studio\2022\Community\VC\Tools\MSVC\14.44.35207\bin\HostX86\x86"
            $env:PATH += ";<VCPKG_INSTALLATION_PATH>"

Building and installing IMAS-Core

Please make sure you have the :ref:`user build prerequisites` installed.

Clone the repository

First you need to clone the repository of the IMAS-Core you want to build:

# For the IMAS-Core use:
git clone git@github.com:iterorganization/IMAS-Core.git

CMake configuration

Once you have cloned the repository, navigate your shell to the folder and run cmake. You can pass configuration options with -D OPTION=VALUE. See below list for an overview of configuration options.

On Linux

cd IMAS-Core
cmake -B build -D CMAKE_INSTALL_PREFIX=$HOME/install -D OPTION1=VALUE1 -D OPTION2=VALUE2 [...]

On Windows

Debug Build:

cmake -Bbuild -S . -DVCPKG=ON -DCMAKE_INSTALL_PREFIX="<INSTALL_PATH>" -DCMAKE_TOOLCHAIN_FILE="<VCPKG_PATH>/scripts/buildsystems/vcpkg.cmake" -DAL_DOWNLOAD_DEPENDENCIES=ON cmake -B build -DCMAKE_INSTALL_PREFIX="$(pwd)/test-install/" -DAL_BACKEND_HDF5=ON -DAL_BACKEND_MDSPLUS=ON -DAL_BACKEND_UDA=ON -DAL_BUILD_MDSPLUS_MODELS=ON -DAL_PYTHON_BINDINGS=no-build-isolation -DAL_DOWNLOAD_DEPENDENCIES=ON -DDD_GIT_REPOSITORY=https://github.com/iterorganization/IMAS-Data-Dictionary.git -DDD_VERSION=main -DBoost_NO_BOOST_CMAKE=ON -DCMAKE_CXX_STANDARD=17 -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++

Release Build:

cmake -Bbuild -S . -DCMAKE_BUILD_TYPE=Release -DVCPKG=ON -DCMAKE_INSTALL_PREFIX="<INSTALL_PATH>" -DCMAKE_TOOLCHAIN_FILE="<VCPKG_PATH>/scripts/buildsystems/vcpkg.cmake" -DAL_DOWNLOAD_DEPENDENCIES=ON cmake -B build -DCMAKE_INSTALL_PREFIX="$(pwd)/test-install/" -DAL_BACKEND_HDF5=ON -DAL_BACKEND_MDSPLUS=ON -DAL_BACKEND_UDA=ON -DAL_BUILD_MDSPLUS_MODELS=ON -DAL_PYTHON_BINDINGS=no-build-isolation -DAL_DOWNLOAD_DEPENDENCIES=ON -DDD_GIT_REPOSITORY=https://github.com/iterorganization/IMAS-Data-Dictionary.git -DDD_VERSION=main -DBoost_NO_BOOST_CMAKE=ON -DCMAKE_CXX_STANDARD=17 -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++

Note

CMake will automatically fetch dependencies from required repositories for you.

If you need to change the git repositories, for example to point to a mirror of the repository or to use a HTTPS URL instead of the default SSH URLs, you can update the :ref:`configuration options`. For example, add the following options to your cmake command to download the repositories over HTTPS instead of SSH:

cmake -B build \
    -D AL_CORE_GIT_REPOSITORY=https://github.com/iterorganization/IMAS-Core.git \
    -D DD_GIT_REPOSITORY=https://github.com/iterorganization/IMAS-Data-Dictionary.git

If you use CMake 3.21 or newer, you can also use the https preset:

cmake -B build --preset=https

Choosing the compilers

You can instruct CMake to use compilers with the following environment variables:

  • CC: C compiler, for example gcc or icc.
  • CXX: C++ compiler, for example g++ or icpc.
  • FC: Fortran compiler, for example gfortran, ifort or nagfor.

If you don't specify a compiler, CMake will take a default (usually from the Gnu Compiler Collection).

Important

These environment variables must be set before the first time you configure cmake!

If you have an existing build folder and want to use a different compiler, you should delete the build folder first, or use a differently named folder for the build tree.

Configuration options

  • Backend configuration options

    • AL_BACKEND_HDF5, allowed values ON (default) or OFF. Enable/disable the HDF5 backend.
    • AL_BACKEND_MDSPLUS, allowed values ON or OFF (default). Enable/disable the MDSplus backend.
      • AL_BUILD_MDSPLUS_MODELS, allowed values ON (default) or OFF, only available when the MDSplus backend is enabled. Enable building MDSplus models for the selected Data Dictionary version.
    • AL_BACKEND_UDA, allowed values ON or OFF (default). Enable/disable the UDA backend.
    • AL_BACKEND_UDAFAT, allowed values ON or OFF (default). Enable/disable the UDA backend and use FAT UDA instead of the client/server model. See the UDA documentation for more information.

  • Control what to build

    • AL_TESTS, allowed values ON or OFF (default). Enable/disable building the test programs in the tests folder.
    • AL_PLUGINS, allowed values ON (default) or OFF. Enable/disable building the plugins from the al-plugins repository.
    • AL_DOCS_ONLY, allowed values ON or OFF (default). When enabled, ONLY the documentation will be built (needs AL_HLI_DOCS=ON). Regardless of other configuration options, nothing else will be built.
    • AL_PYTHON_BINDINGS, allowed values ON (default when building the Python API) or OFF (default when not building the Python API). When enabled, this builds the Access Layer Python lowlevel bindings.

  • Dependency configuration options

    • AL_DOWNLOAD_DEPENDENCIES, allowed values ON (default) or OFF. Enable or disable the automatic downloading of dependencies. Should be disabled when using a development environment

    Important

    The following environment variables must be set before the first time you configure cmake!

    If you have an existing build folder and want to use a different compiler, you should delete the build folder first, or use a differently named folder for the build tree.

    When AL_DOWNLOAD_DEPENDENCIES is enabled, the following settings can be used to configure the location and/or version of the dependencies that should be used.

    • AL_CORE_GIT_REPOSITORY, , DD_GIT_REPOSITORY. Configure the git URLs where the IMAS-Core c.q. data-dictionary repositories should be fetched from.

    • AL_CORE_VERSION, AL_PLUGINS_VERSION, DD_VERSION. Configure the version of the repository that should be used. This can point to any valid branch name, tag or commit hash.

      This setting can be used to control which version of the Data Dictionary you want to use. For example: -D DD_VERSION=3.38.1 will use DD version 3.38.1 instead of the default.

    AL_CORE_GIT_REPOSITORY:     git@github.com:iterorganization/IMAS-Core.git
AL_CORE_VERSION:            main


DD_GIT_REPOSITORY:          git@github.com:iterorganization/IMAS-Data-Dictionary.git
DD_VERSION:                 main

  • Useful CMake options

    • CMAKE_INSTALL_PREFIX. Configure the path where the Access Layer will be installed, for example -D CMAKE_INSTALL_PREFIX=$HOME/install will install the IMAS-Core inside the install folder in your home directory.
    • CMAKE_BUILD_TYPE. Configure the build type for compiled languages. Supported values (case sensitive):
      • Debug: build with debug symbols and minimal optimizations.
      • Release: build with optimizations enabled, without debug symbols.
      • RelWithDebInfo (default): build with optimizations and debug symbols enabled.
      • MinSizeRel: build optimized for minimizing the size of the resulting binaries.

More advanced options are available as well, these can be used to configure where CMake searches for the prerequisite dependencies (such as the Boost libraries). To show all available configuration options, use the command-line tool ccmake or the gui tool cmake-gui:

# for the CLI tool
ccmake -B build -S .
# for the GUI tool
cmake-gui -B build -S .

Build the IMAS-Core

Use cmake to build as shown below.

# Instruct make to build "all" in the "build" folder, using at most "8" parallel
# processes:
CMAKE_ARGS=(${CMAKE_ARGS[@]}
    -D"CMAKE_INSTALL_PREFIX=$(pwd)/test-install/"
    # Enable all backends
    -DAL_BACKEND_HDF5=ON
    -DAL_BACKEND_MDSPLUS=ON
    -DAL_BACKEND_UDA=ON
    # Build MDSplus models
    -DAL_BUILD_MDSPLUS_MODELS=ON
    # Build Python bindings
    -DAL_PYTHON_BINDINGS=no-build-isolation
    # Download dependencies from HTTPS (using an access token):
    -DAL_DOWNLOAD_DEPENDENCIES=ON
    -DDD_GIT_REPOSITORY=https://github.com/iterorganization/IMAS-Data-Dictionary.git
    # DD version:
    -DDD_VERSION=$DD_VERSION
    # Work around Boost linker issues on 2020b toolchain
    -DBoost_NO_BOOST_CMAKE=ON
)
echo "CMake args:"
echo ${CMAKE_ARGS[@]} | tr ' ' '\n'

# Note: we don't set CC or CXX compiler, so CMake will pick the default (GCC) compilers
cmake -Bbuild -GNinja "${CMAKE_ARGS[@]}"

# Build and install
cmake --build build --target install

Note

By default CMake on Linux will create Unix Makefiles for actually building everything, as assumed in this section.

You can select different generators (such as Ninja) if you prefer, but these are not tested. See the CMake documentation for more details.

Install from source using pip

Alternatively, you can install IMAS-Core from source using pip. This method is useful when you want to install directly from the source code without using CMake directly.

First, clone the repository:

git clone git@github.com:iterorganization/IMAS-Core.git
cd IMAS-Core

Then install using pip:

pip install .

You can pass CMake configuration options to pip using the -C skbuild.cmake.define.OPTION=VALUE syntax. For example:

# Install with UDA backend disabled
pip install . -C skbuild.cmake.define.AL_BACKEND_UDA=OFF

# Install with specific backend configurations
pip install . \
    -C skbuild.cmake.define.AL_BACKEND_HDF5=ON \
    -C skbuild.cmake.define.AL_BACKEND_MDSPLUS=ON \
    -C skbuild.cmake.define.AL_BACKEND_UDA=OFF \
    -C skbuild.cmake.define.AL_PYTHON_BINDINGS=ON

All CMake configuration options described in the :ref:`Configuration options` section can be passed using this method. The option names remain the same, but are prefixed with -C skbuild.cmake.define..

Optional: Test the IMAS-Core

Following snippet shows how to run the test with pytest. Just ensure that you have AL_PYTHON_BINDINGS-ON in cmake configuration. If you set either of the options AL_EXAMPLES or AL_TESTS to ON, you can run the corresponding test programs as follows:

python3 -m venv build/pip_install
source build/pip_install/bin/activate
pip install --upgrade pip wheel
pip install numpy
set -x
pip install --find-links=build/dist imas-core[test,cov]
pytest --junitxml results.xml --cov imas_core --cov-report xml --cov-report html
coverage2clover -i coverage.xml -o clover.xml

Use the IMAS-Core

After installing the IMAS-Core, you need to ensure that your code can find the installed Access Layer. To help you with this, a file al_env.sh is installed. You can source this file to set all required environment variables:

source <install_dir>/bin/al_env.sh
You may want to add this to your $HOME/.bashrc file to automatically make the IMAS-Core
installation available for you.

Note

To use a public dataset, you also need to set the IMAS_HOME environment variable. For example, on SDCC, this would be export IMAS_HOME=/work/imas.

Some programs may rely on an environment variable IMAS_VERSION to detect which version of the data dictionary is used in the current IMAS environment. You may set it manually with the DD version you've build theens-user API with, for example: export IMAS_VERSION=3.41.0.

Once you have set the required environment variables, you may continue Using the IMAS-Core.

If IMAS-Core is built with Python bindings, you can also use the Python bindings with imas-python. imas_python. Just install with pip install imas-python and you can use the Python bindings. more information is here imas-python.

Next Steps

For comprehensive examples and advanced usage patterns, see: