Building and installing the IMAS-MATLAB

This page describes how to build and install the IMAS-MATLAB.

Documentation for developers wishing to contribute to the IMAS-MATLAB can be found in the IMAS-MATLAB development guide. Please refer to that guide if you wish to set up a development environment.

For more information about related components, see:

Note

For Windows-specific installation instructions, please refer to the MATLAB on Windows guide.

Prerequisites

To build the IMAS-MATLAB you need:

  • Git

  • A C++11 compiler (tested with GCC and Intel compilers)

  • CMake (3.16 or newer)

  • Boost C++ libraries (1.66 or newer)

  • PkgConfig

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]

  • MATLAB High Level Interface

    • MATLAB High Level Interface: A working MATLAB installation (tested with version 2023b)

Standard environments:

The following modules provide all the requirements when using the intel-2023b toolchain:

module load intel-compilers/2023.2.1 CMake/3.27.6-GCCcore-13.2.0 Saxon-HE/12.4-Java-21 \
    Boost/1.83.0-iimpi-2023b HDF5/1.14.3-iimpi-2023b \
    MDSplus/7.132.0-GCCcore-13.2.0 \
    UDA/2.8.1-iimpi-2023b Blitz++/1.0.2-GCCcore-13.2.0 \
    MATLAB/2023b-r5-GCCcore-13.2.0 SciPy-bundle/2023.11-intel-2023b \
    scikit-build-core/0.9.3-GCCcore-13.2.0

The following modules provide all the requirements when using the foss-2023b toolchain:

module load CMake/3.27.6-GCCcore-13.2.0 Saxon-HE/12.4-Java-21 \
    Boost/1.83.0-GCC-13.2.0 HDF5/1.14.3-gompi-2023b \
    MDSplus/7.132.0-GCCcore-13.2.0 \
    UDA/2.8.1-GCC-13.2.0 Blitz++/1.0.2-GCCcore-13.2.0 \
    MATLAB/2023b-r5-GCCcore-13.2.0 SciPy-bundle/2023.11-gfbf-2023b \
    build/1.0.3-foss-2023b scikit-build-core/0.9.3-GCCcore-13.2.0

The MATLAB/2023b-r5 installation is lightly tweaked

The installation at ITER uses EB PR#20508 and its tweak resolves IMAS-5162 by removing libstdc++.so.6 from the MATLAB installation. It also adds extern/bin/glnxa64 to LD_LIBRARY_PATH to address the MatlabEngine not found issue.

Caution

When using the HDF5 backend within MATLAB, depending on the HDF5 library being used you may need to add LD_PRELOAD=<hdf5_install_dir>/lib/libhdf5_hl.so when starting MATLAB.

The following packages provide most requirements when using Ubuntu 22.04:

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:

Building and installing a single High Level Interface

This section explains how to install a Matlab High Level Interface. Please make sure you have the Prerequisites installed.

Clone the repository

First you need to clone the repository of the High Level Interface you want to build:

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

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.

cd al-matlab  # al-fortran, al-java, al-cpp or al-python
cmake -B build -D CMAKE_INSTALL_PREFIX=$HOME/al-install -D OPTION1=VALUE1 -D OPTION2=VALUE2 [...]

Note

CMake will automatically fetch dependencies from other IMAS-MATLAB GIT repositories for you. You may need to provide credentials to clone the following repositories:

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 Configuration options. For example, add the following options to your cmake command to download the repositories over HTTPS instead of SSH:

Use explicit options to download dependent repositories over HTTPS
cmake -B build \
    -D AL_CORE_GIT_REPOSITORY=git@github.com:iterorganization/IMAS-Core.git \
    -D AL_PLUGINS_GIT_REPOSITORY=git@github.com:iterorganization/al-plugins.git \
    -D DD_GIT_REPOSITORY=git@github.com:iterorganization/IMAS-Data-Dictionary.git

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

Use CMake preset to set to download dependent repositories over HTTPS
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.

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

For a complete list of available configuration options, please see the IMAS Core Configuration Options.

Build the High Level Interface

Use make to build everything. You can speed things up by using parallel compiling as shown with the -j option. Be careful with the amount of parallel processes though: it’s easy to exhaust your machine’s available hardware (CPU or memory) which may cause the build to fail. This is especially the case with the C++ High Level Interface.

# Instruct make to build "all" in the "build" folder, using at most "8" parallel
# processes:
make -C build -j8 all

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.

Optional: Test the High Level Interface

If you set either of the options AL_EXAMPLES or AL_TESTS to ON, you can run the corresponding test programs as follows:

# Use make:
make -C build test
# Directly invoke ctest
ctest --test-dir build

This executes ctest to run all test and example programs. Note that this may take a long time to complete.

Install the High Level Interface

Run make install to install the high level interface in the folder that you chose in the configuration step above.

Use the High Level Interface

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

Set environment variables (replace <install_dir> with your install folder)
source <install_dir>/bin/al_env.sh

You may want to add this to your $HOME/.bashrc file to automatically make the Access Layer 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 the HLI with, for example: export IMAS_VERSION=3.41.0.

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

Troubleshooting

Problem: Target Boost::log already has an imported location

This problem is known to occur with the 2020b toolchain on SDCC. Add the CMake configuration option -D Boost_NO_BOOST_CMAKE=ON to work around the problem.