WORK IN PROGRESS!

 Table of Contents

How to install split IMAS using EasyBuild

This tutorial shows how to install IMAS (after repository split) using EasyBuild. The installation in this tutorial will be performed on the Gateway cluster but it can be done anywhere.

Install EasyBuild

You should install EasyBuild using Python and venv (virtual environment).

Code Block

language	bash
title	Install EasyBuild using Python

module load itm-python/3.10.13
python3 -m venv venv
module purge
source venv/bin/activate
pip3 install easybuild

You can use a different version of Python. Remember to purge all unnecessary modules that can cause conflicts with new modules created by EasyBuild.

...

To enable access to ITER GIT repositories HTTP access token is required.

Go to ITER Bitbucket (https://git.iter.org).
"Manage Account" - press user icon (upper right corner)
"Http Access Token"
"Create Token"
Copy token to clipboard
Create a secret.txt file in $HOME/.config/easybuild/ and paste the access token there

Code Block

language	text
title	secret.txt

Authorization: Bearer <token>

The configuration is located in the file $HOME/.config/easybuild/config.cfg. Create this file if it doesn't exist.

Code Block

title	$HOME/.config/easybuild/config.cfg

# System variables cannot be used in EB config file!!! 
# Do not put string values in quotes !!! 

[config]
prefix=/pfs/work/g2pbloch/imasenv_eb
modules-tool=EnvironmentModulesC
module-syntax=Tcl
http-header-fields-urlpat=^https://git.iter.org::<path to config dir>/.config/easybuild/secret.txt

[override]
insecure-download=True

Change the prefix to the path where do you want your installation.

Downloading configuration (EB) files

Clone these repositories and specify the paths to them in the --robot in the next step.

Code Block

language	text
title	clone repo

https://gitlab.eufus.psnc.pl/g2pbloch/easybuild-files 
https://gitlab.eufus.psnc.pl/g2pbloch/easybuild-imas-files 

# [Bartek Palak] Probably only the ITER repository of EB receipts is required (ssh://git@git.iter.org/imex/easybuild-easyconfigs.git) To be checked.

Installation of Data Dictionary (DD)

Run the DD installation (in the easybuild-imas-files directory):

Code Block

language	bash
title	IMAS install

eb Data-Dictionary/Data-Dictionary-3.40.1-GCCcore-10.2.0.eb --allow-modules-tool-mismatch --robot=/pfs/work/g2pbloch/test_instruction/easybuild-imas-files:/pfs/work/g2pbloch/test_instruction/eb_files_repo  --http-header-fields-urlpat="^https://git.iter.org::$HOME/.config/easybuild/secret.txt"

Remember to change the --robot and pass paths to your easybuild-files and easybuild-imas-files directories.

Configuring paths in IMAS configuration (EB) files

After DD installation change path in this line in the HLI easyconfigs to your {prefix}/software/Data-Dictionary/3.40.1-GCCcore-10.2.0/dd_3.40.1/

Code Block

language	py
title	DD path

 preconfigopts = 'export IMAS_VERSION="0.0.0" &&  export IMAS_PREFIX="/pfs/work/g2pbloch/test_instruction/software/Data-Dictionary/3.40.1-GCCcore-10.2.0/dd_3.40.1/" &&'

In Python configuration files IMAS-AL-Python, IMAS-AL-Python-Bindings you have to change path to python to $prefix/software/Python/3.8.6-GCCcore-10.2.0/

Installation of IMAS HLIs - 5.2.0dev

Code Block

language	bash
title	IMAS

eb IMAS-AL-Cpp/IMAS-AL-Cpp-5.2.0dev-foss-2020b-DD-3.40.1.eb --allow-modules-tool-mismatch --robot=/pfs/work/g2pbloch/test_instruction/easybuild-imas-files:/pfs/work/g2pbloch/test_instruction/eb_files_repo 
eb IMAS-AL-Fortran/IMAS-AL-Fortran-5.2.0dev-foss-2020b-DD-3.40.1.eb  --allow-modules-tool-mismatch --robot=/pfs/work/g2pbloch/test_instruction/easybuild-imas-files:/pfs/work/g2pbloch/test_instruction/eb_files_repo 
eb IMAS-AL-Java/IMAS-AL-Java-5.2.0dev-foss-2020b-Java-11-DD-3.40.1.eb  --allow-modules-tool-mismatch --robot=/pfs/work/g2pbloch/test_instruction/easybuild-imas-files:/pfs/work/g2pbloch/test_instruction/eb_files_repo 
eb IMAS-AL-Python/IMAS-AL-Python-5.2.0dev-foss-2020b-DD-3.40.1.eb  --allow-modules-tool-mismatch --robot=/pfs/work/g2pbloch/test_instruction/easybuild-imas-files:/pfs/work/g2pbloch/test_instruction/eb_files_repo

Remember to change the --robot and pass paths to your easybuild-files and easybuild-imas-files directories.

Installation of IMAS/3.42.0-2024.08.1

...

Introduction

EasyBuild is a framework for building and managing software on HPC systems. It automates compiling, installing, and configuring scientific applications while handling dependencies, toolchains, and environment modules.

A key concept is easyconfig files — text-based receipts that define build parameters, dependencies, versions, and toolchains. By using these receipts, EasyBuild installs software along with all its dependencies, ensuring a consistent, reproducible, and optimized HPC software environment.

How it works? The dependency resolution mechanism constructs a full dependency graph for the software package(s) being installed, after which a list of dependencies is composed for which no module is available yet. Each of the retained dependencies will then be built and installed, in the required order as indicated by the dependency graph.

This page shows how to install IMAS ecosystem using EasyBuild. The installation will be performed on the Gateway cluster but it can be done anywhere.

Prerequisites

Before you start, make sure that:

Easybuild is installed and publicly available via module system
Easybuild configuration file exists and is properly configured
IMAS related receipts are downloaded
All modules are purged and EasyBuild module is the only module loaded:
Code Block
module purge module load EasyBuild
$EASYCONFIG_PATHS system variable is set to point to all directories with easyconfig files

Downloading easyconfigs

To allow the users to seamlessly switch between EUROfusion and ITER clusters, the environment that is built on the Gateway mimics (to some extent) the one of the ITER SDCC machines.

To achieve this a receipts from the ITER cluster are utilised to install software on the GW.

Downloading configuration (EB) files

Source SDCC: /work/imas/opt/EasyBuild/ebfiles_repo/

Code Block

language	bash
title	Synchronisation of the ITER receipts

rsync -av --delete -e "ssh -J <user>@sdcc-login.iter.org"  <user>@sdcc-login02.iter.org:/work/imas/opt/EasyBuild/ebfiles_repo/ ./iter-receipts/

System variable EASYCONFIGS_PATH

Set system variable EASYCONFIGS_PATH that points to the directory with receipts

Code Block

language	text
title	clone repo

export EASYCONFIGS_PATH=`pwd`/iter-receipts

Warning
This simple mechanism will be replaced with a more complex one, where receipts would be maintained in GIT repositories.

Installation of software components

Searching for receipts

EasyBuild needs a receipt to install any software component. The following command can be used to look for receipts:

Code Block
eb --search <software_name> --robot-paths=$EASYCONFIG_PATHS

Info

--robot-paths=<path1>:<path2> configuration option supports prepending or appending to the default robot search path:

To prepend one or more paths, a list of paths followed by a ‘:’ should be specified.
To append one or more paths, a list of paths preceded by a ‘:’ should be specified.

See EasyBuild documentation for details and examples

A <software_name> could be only part of the name being searched. Additionally EasyBuild search is case insensitive. E.g. "dox" string can be provided while looking for "Doxygen"

Code Block

shell> eb --search dox --robot=$EASYCONFIG_PATHS

== found valid index for /gw/swimas/easybuild/opt/software/EasyBuild/5.0.0/easybuild/easyconfigs, so using it...
 * /afs/eufus.eu/user/g/g2bpalak/work/easybuild/all_iter/Doxygen/Doxygen-1.9.8-GCCcore-13.2.0.eb
 * /afs/eufus.eu/user/g/g2bpalak/work/easybuild/all_iter/Doxygen/Doxygen-1.13.2-GCCcore-13.2.0.eb
...
 * /gw/swimas/easybuild/opt/software/EasyBuild/5.0.0/easybuild/easyconfigs/d/Doxygen/Doxygen-1.9.8-GCCcore-13.2.0.eb
 * /gw/swimas/easybuild/opt/software/EasyBuild/5.0.0/easybuild/easyconfigs/d/Doxygen/Doxygen-1.11.0-GCCcore-13.3.0.eb

Usually receipt name uses following syntax:

Code Block
<software name>-<software version>-<toolchain>-<toolchain version> e.g.: Doxygen-1.9.8-GCCcore-13.2.0.eb

Installation

Code Block

language	bash
title	IMAS

eb <receipt name>.eb --robot --robot-paths=$EASYCONFIG_PATHS

e.g.:
eb Doxygen-1.9.8-GCCcore-13.2.0.eb --robot --robot-paths=$EASYCONFIGS_PATHS

Info

title	Hints

--robot/-r command line option enables dependency resolution See EasyBuild documentation for details
It is strongly advised to change temporary directories to use $ITMWORK
It is recommended to run before actual installation:
- eb with option -missing-modules/-M to check what dependencies will be installed
- eb with option --dry-run/-D or --extended-dry-run/-x, to check what and how will be installed
All 'massive' builds should be performed on the worker nodes
See EB help for the other useful eb switches

Installation of the 'production' software

To install the 'production' version of the software belonging to IMAS ecosystem, a few extra options have to be added to point out EB to the dedicated public directory /gw/swimas/easybuild

Code Block

language	plain

--prefix='/gw/swimas/easybuild/opt' 
--installpath-modules='/gw/swimas/easybuild/etc'
--ignore-checksums (optional)


# TO BE DISCUSSED: Accessing sources while debugging. Should 'source' directory be public, as well?

Installation of the IMAS bundle

The IMAS bundle is (usually) provided by ITER and loads all IMAS High Level Interfaces and related modules:

Content of IMAS bundle

IMAS bundle consist of:

IMAS High Level Interfaces
- IMAS-AL-Cpp
- IMAS-AL-Fortran
- IMAS-AL-Java
- IMAS-AL-Matlab
- IMAS-AL-Python
Related modules:
- IDStools

IMAS bundle receipts

The IMAS bundle receipts name usually contains the 'IMAS' string, Data Dictionary version, date of release and toolchain version, e.g.: IMAS-3.42.0-2024.09-foss-2023b.eb or IMAS-4.0.0-2024.12-foss-2023b.eb

Before installation search for a proper IMAS bundle version

Code Block

shell> eb --search IMAS-3 --robot-paths=$EASYCONFIG_PATHS

== found valid index for /gw/swimas/easybuild/opt/software/EasyBuild/5.0.0/easybuild/easyconfigs, so using it...
...
 * /gss_efgw_work/work/g2bpalak/easybuild/iter-receipts/IMAS/IMAS-3.42.0-2024.08

...

-foss-2023b.eb

...


 * /gss_efgw_work/work/g2bpalak/easybuild/iter-receipts/IMAS/IMAS-3.42.0-2024.08

...

-intel-2023b.eb

...


...
 * /gss_efgw_work/work/g2bpalak/easybuild/iter-receipts/IMAS/IMAS-3.42.0-2024.09-foss-2023b.eb
 * /gss_efgw_work/work/g2bpalak/easybuild/iter-receipts/IMAS/IMAS-3.42.0-2024.09-intel-2023b.eb
...

Warning

Every IMAS High Level Interface depends on the IMAS Access Layer Core ( IMAS-AL-Core )

Make sure that all IMAS HLIs use exactly the same version of IMAS-AL-Core and other common dependencies !!!

Installation

Once the receipt with a proper version of Data Dictionary and toolchain is found, the IMAS bundle can be installed as any other software:

Code Block
eb <IMAS bundle receipt>.eb --robot --robot-paths=$EASYCONFIG_PATHS e.g.: eb IMAS-3.42.0-2024.08.1-intel-2023b.eb --robot --robot-paths=$EASYCONFIG_PATHS

How to use IMAS

After installation you can load IMAS modules i.e:

Code Block

language	bash
title	Load module

module use {prefix}/modules/all
module load IMAS-AL-Cpp/5.2.0dev-foss-2020b-DD-3.40.1
module load IMAS-AL-Fortran/5.2.0dev-foss-2020b-DD-3.40.1
module load IMAS-AL-Java/5.2.0dev-foss-2020b-Java-11-DD-3.40.1
module load IMAS-AL-Python/5.2.0dev-foss-2020b-DD-3.40.1

`imasenv` module

Adding software components to existing installation

Set MODULEPATH system variable

Code Block
export MODULEPATH=/gw/swimas/easybuild/etc/all

Useful tips

Installing dependencies as hidden modules

The key feature of the EasyBuild is the ability to install a software component with all its dependencies. Unfortunatlely EasyBuild installs module not only for the requested software but for every dependency as well.

It results with the number of available modules growing with every installation, becoming less and less hard to navigate for the users.

There are few options to hide modules, unfortunately every of them has its disadvantages,

eb --hide-deps=<moduleName1>,<moduleName2>,..., <moduleNameN> option of eb requires for all modules to be explicitly listed
eb --hide-all-dependencies - implemented in working branch but PR#3217 has been not merged since 2020
module-hide <module-name> - Lmod module system command (see documentation). . Modules have to be hide one by one.

Change the default tmp directory
Anchor
tmp_dir_change
tmp_dir_change

Easybuild produces a lot of temporary content (logs, intermediate build files, etc)

The default /tmp dir on the GW offers quite small capacity. Once tmp is full, system cannot work properly.

It is strongly recommended to change the default /tmp to a directory in $ITMWORK

Code Block

language	bash
title	.bash_profile

tmpdir=$ITMWORK/tmp

export TMP=${tmpdir}
export TEMP=${tmpdir}
export TMPDIR=${tmpdir}

Run a massive builds on the worker nodes

Code Block

language	bash

# Run 'interactive' batch job using SLURM 'srun' command
# -p gw                  : 'gw' queue offering the longer walltime than the default 'gwdebug'
# --ntasks-per-node=48   : number of cores requested (1 node provides up to 48 cores)
# --time=48:0:0          : walltime (documentation says that the default walltime in 'gw' queue is 48h but not explicitly specified is set to 1h - To Be Checked)
# --x11                  : X11 forwarding (optional

How to use IMAS

After installation you can load IMAS modules i.e:

Code Block

language	bash
title	Load module

module use {prefix}/modules/all
module load IMAS-AL-Cpp/5.2.0dev-foss-2020b-DD-3.40.1
module load IMAS-AL-Fortran/5.2.0dev-foss-2020b-DD-3.40.1
module load IMAS-AL-Java/5.2.0dev-foss-2020b-Java-11-DD-3.40.1
module load IMAS-AL-Python/5.2.0dev-foss-2020b-DD-3.40.1

How it works

eb - EasyBuild
IMAS-AL-Cpp/IMAS-AL-Cpp-5.2.0dev-foss-2020b-DD-3.40.1.eb - path to EasyBuild configuration file
--allow-modules-tool-mismatch - flag
--robot - paths to configuration files
--http-header-fields-urlpat - secret to downloading files from ITER repo

Installation of the 'production' version

...

Code Block

language	plain

--prefix='/gw/swimas/easybuild/opt' 
--installpath-modules='/gw/swimas/easybuild/etc'

# TO BE DISCUSSED: Accessing sources while debugging. Should 'source' directory be public, as well? 

# following modules must be installed 
# pkgconfig
# Cmake
# IMAS_AL-Core receipt - to be checked!!!
    '-D Python3_ROOT_DIR=/gw/swimas/easybuild/opt/software/Python/3.11.5-GCCcore-13.2.0 '
    '-D Python3_EXECUTABLE=/gw/swimas/easybuild/opt/software/Python/3.11.5-GCCcore-13.2.0/bin/python3 '
    '-D Python_ROOT_DIR=/gw/swimas/easybuild/opt/software/Python/3.11.5-GCCcore-13.2.0 '
    '-D Python_EXECUTABLE=/gw/swimas/easybuild/opt/software/Python/3.11.5-GCCcore-13.2.0/bin/python3 '

Adding software components to existing installation

...

Code Block
export MODULEPATH=/gw/swimas/easybuild/etc/all

...

Useful tips

Installing dependencies as hidden modules

Warning

TO BE CHECKED !!!!!

{{--hide-deps}}

Purge loaded modules before using Easybuild

Warning

EasyBuild requires no modules to be loaded !

Please execute:

Code Block
module purge

Change the default tmp directory

Easybuild produces a lot of temporary content (logs, intermediate build files, etc)

The default /tmp dir on the GW offers quite small capacity. Once tmp is full, system cannot work properly.

It is strongly recommended to change the default /tmp to a directory in $ITMWORK

Code Block

language	bash
title	.bash_profile

tmpdir=$ITMWORK/tmp

export TMP=${tmpdir}
export TEMP=${tmpdir}
export TMPDIR=${tmpdir}

Run a massive builds on the worker nodes

Code Block

language	bash

# Run 'interactive' batch job using SLURM 'srun' command
# -p gw : 'gw' queue offering the longer walltime than the default 'gwdebug'
# --ntasks-per-node=48 : number of cores requested (1 node provides up to 48 cores)
# --time=48:0:0 : walltime (documentation says that the default walltime in 'gw' queue is 48h but not explicitly specified is set to 1h - To Be Checked)
# --pty /bin/bash        : pseudoterminal

bash> srun -p gw --ntasks-per-node=48 --time=48:0:0 --pty /bin/bash

...

Once resources are allocated, a new shell is being opened opens on the working node . A usually reporting file system error is reported in most cases:

Code Block
bash: /afs/eufus.eu/user/g/g2<user>/.bashrc: Permission denied

...

Code Block
bash> kinit; aklog

Now .bashrcbash_profile could be 'sourced' to enable user's startup settings:

Code Block
bash> source .bashrcbash_profile

Now EasyBuild can be used to build a software.

...

Space shortcuts

Page tree

Versions Compared

Old Version 59

New Version Current

Key

WORK IN PROGRESS!

How to install split IMAS using EasyBuild

Install EasyBuild

Downloading configuration (EB) files

Installation of Data Dictionary (DD)

Configuring paths in IMAS configuration (EB) files

Installation of IMAS HLIs - 5.2.0dev

Installation of IMAS/3.42.0-2024.08.1

Introduction

Prerequisites

Downloading easyconfigs

Installation of software components

Searching for receipts

Installation

Installation of the IMAS bundle

Content of IMAS bundle

IMAS bundle receipts

Installation

How to use IMAS

`imasenv` module

Adding software components to existing installation

Useful tips

Installing dependencies as hidden modules

Change the default tmp directory
Anchor
tmp_dir_change
tmp_dir_change

Run a massive builds on the worker nodes

How to use IMAS

How it works

Installation of the 'production' version

Adding software components to existing installation

Useful tips

Installing dependencies as hidden modules

Purge loaded modules before using Easybuild

Change the default tmp directory

Run a massive builds on the worker nodes

Space shortcuts

Page tree

Page History

Versions Compared

Old Version 59

New Version Current

Key

WORK IN PROGRESS!

How to install split IMAS using EasyBuild

Install EasyBuild

Downloading configuration (EB) files

Installation of Data Dictionary (DD)

Configuring paths in IMAS configuration (EB) files

Installation of IMAS HLIs - 5.2.0dev

Installation of IMAS/3.42.0-2024.08.1

Introduction

Prerequisites

Downloading easyconfigs

Installation of software components

Searching for receipts

Installation

Installation of the IMAS bundle

Content of IMAS bundle

IMAS bundle receipts

Installation

How to use IMAS

imasenv module

Adding software components to existing installation

Useful tips

Installing dependencies as hidden modules

Change the default tmp directory Anchortmp_dir_changetmp_dir_change

Run a massive builds on the worker nodes

How to use IMAS

How it works

Installation of the 'production' version

Adding software components to existing installation

Useful tips

Installing dependencies as hidden modules

Purge loaded modules before using Easybuild

Change the default tmp directory

Run a massive builds on the worker nodes

`imasenv` module

Change the default tmp directory
Anchor
tmp_dir_change
tmp_dir_change