Skip to content

Commit b5a5713

Browse files
pranabdaspranabdas
committed
SOF-7764: instruction on how to add application container with apptainer
1 parent f353129 commit b5a5713

File tree

2 files changed

+125
-7
lines changed

2 files changed

+125
-7
lines changed

‎lang/en/docs/cli/actions/add-software.md‎

Lines changed: 124 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,129 @@
1-
# Add New Software
1+
# Add New Software
22

3-
The user can compile new software on the [Command Line Interface](../overview.md) (CLI). This is helpful, for example, after introducing some changes or patches to the source code. In order to compile such new software a special permission is required to access the master nodes of our [computational clusters](../../infrastructure/clusters/overview.md), where the compilation shall be performed. This permission can be requested by following [these instructions](../../ui/support.md).
3+
The user can compile new software on the [Command Line Interface](
4+
../overview.md) (CLI). This is helpful, for example, after introducing some
5+
changes or patches to the source code. Currently, majority of our applications
6+
are packaged as Apptainer (Singularity) containers along with their
7+
dependencies. In that way each application is independent of each other, and
8+
there is no conflict among dependencies. If you wish to run an application that
9+
is installed in our cluster, you are encouraged to build your application and
10+
dependencies as Apptainer/<wbr/>Singularity container. It is also possible to
11+
convert docker containers into Apptainer/<wbr/>Singularity image.
412

5-
We also explain how to add python packages to the environment [in this page](create-python-env.md).
13+
Below is an example Apptainer/<wbr/>Singularity definition to build Quantum
14+
ESPRESSO along with its dependencies.
15+
16+
17+
```singularity title="espresso.def"
18+
Bootstrap: docker # (1)!
19+
From: almalinux:9.7 # (2)!
20+
21+
%labels # (3)!
22+
Maintainer Mat3ra.com
23+
Version QE-6.3-gcc-openmpi-openblas
24+
25+
%environment # (4)!
26+
export PATH=/usr/lib64/openmpi/bin:/opt/qe-6.3/bin:$PATH
27+
export LD_LIBRARY_PATH=/usr/lib64/openmpi/lib:$LD_LIBRARY_PATH
28+
29+
%post # (5)!
30+
# install dependencies
31+
dnf install -y epel-release
32+
dnf config-manager --set-enabled crb
33+
dnf install -y gcc-gfortran \
34+
git \
35+
make \
36+
fftw-devel \
37+
openblas \
38+
openblas-devel \
39+
openmpi-devel \
40+
scalapack-openmpi-devel \
41+
wget \
42+
which
43+
44+
# download QE and compile
45+
VERSION=6.3
46+
INSTALL_PREFIX="/opt/qe-$VERSION"
47+
BUILD_DIR=~/tmp
48+
mkdir $BUILD_DIR
49+
50+
cd $BUILD_DIR
51+
wget https://gitlab.com/QEF/q-e/-/archive/qe-${VERSION}/q-e-qe-${VERSION}.tar.gz
52+
tar -xf q-e-qe-${VERSION}.tar.gz
53+
cd q-e-qe-${VERSION}
54+
55+
export PATH=/usr/lib64/openmpi/bin:$PATH
56+
export FFLAGS="-O2 -fallow-argument-mismatch"
57+
export FCFLAGS="-O2 -fallow-argument-mismatch"
58+
59+
./configure MPIF90=mpif90 CC=mpicc F90=gfortran F77=gfortran \
60+
--with-scalapack=yes \
61+
BLAS_LIBS="-lopenblas" LAPACK_LIBS="-lopenblas" \
62+
LDFLAGS="-Wl,-rpath,/usr/lib64/openmpi/lib -Wl,-rpath,/usr/lib64"
63+
64+
make all
65+
make -B install
66+
67+
# cleanup
68+
rm -rf $BUILD_DIR
69+
dnf clean all && rm -rf /var/lib/dnf /var/cache/dnf /var/cache/yum
70+
```
71+
72+
1. Bootstrap from a Docker image
73+
2. Select your base image
74+
3. Metadata such as version, maintainer details, etc.
75+
4. Set runtime environment variables
76+
5. Build routine goes under the `post` section
77+
78+
Container can be built with:
79+
```bash
80+
apptainer build espresso.sif espresso.def
81+
```
82+
83+
Once the container image is build, it maybe pushed to a container registry such
84+
as [GitHub Container Registry](
85+
https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry).
86+
87+
```bash
88+
apptainer push espresso.sif oras://ghcr.io/<user-or-org-name>/<namespace>/<container-name>:<tag>
89+
```
90+
91+
Now, the image can be pulled from another machine with:
92+
```bash
93+
apptainer pull oras://ghcr.io/<user-or-org-name>/<namespace>/<container-name>:<tag>
94+
```
95+
96+
Alternatively, user can secure copy the image file:
97+
```bash
98+
scp espresso.sif <username>@login.mat3ra.com:/cluster-001-home/<username>
99+
```
100+
101+
!!! Info Large libraries such as Intel OneAPI, NVIDIA HPC SDK, which are several
102+
Gigabyte in size, can be mapped from our custer host instead of bundling
103+
together with the application.
104+
105+
106+
## Compiling software in our cluster
107+
In order to compile such new software a special permission is required to access
108+
the master nodes of our [computational clusters](
109+
../../infrastructure/clusters/overview.md), where the compilation shall be
110+
performed. This permission can be requested by following [these instructions](
111+
../../ui/support.md).
112+
113+
We also explain how to add python packages to the environment [in this page](
114+
create-python-env.md).
6115

7116
## Example: New Quantum ESPRESSO Version
8117

9-
The user might wish to compile a version of the [Quantum ESPRESSO](../../software-directory/modeling/quantum-espresso/overview.md) simulation package different from the ones offered [through environment modules](modules-actions.md#list-available-modules). This new versions might also include modifications to the source code by the user.
118+
The user might wish to compile a version of the [Quantum ESPRESSO](
119+
../../software-directory/modeling/quantum-espresso/overview.md) simulation
120+
package different from the ones offered [through environment modules](
121+
modules-actions.md#list-available-modules). This new versions might also include
122+
modifications to the source code by the user.
10123

11-
We refer to the official documentation [^1] for the instructions on how to compile Quantum ESPRESSO via CLI. Sample routines that allow for the compilation are demonstrated below:
124+
We refer to the official documentation [^1] for the instructions on how to
125+
compile Quantum ESPRESSO via CLI. Sample routines that allow for the compilation
126+
are demonstrated below:
12127

13128
```bash
14129
# Create temporary directory
@@ -24,10 +139,12 @@ module load mpi/ompi-110 openblas/218-g-540
24139
./configure
25140
make libfox
26141
make pw
27-
```
142+
```
28143

29144
!!! warning "Compilation routines are given for demonstration only"
30-
The commands below are present to demonstrate the approach only and are limited in applicability. They do not include any consideration of the optimization of parallel performance, for example.
145+
The commands above are present to demonstrate the approach only and are
146+
limited in applicability. They do not include any consideration of the
147+
optimization of parallel performance, for example.
31148

32149
## Links
33150

‎mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,7 @@ theme:
9696
features:
9797
- announce.dismiss
9898
- content.action.edit
99+
- content.code.annotate
99100
- content.code.copy
100101
- content.tooltips
101102
- navigation.footer

0 commit comments

Comments
 (0)