bwHPC Wiki - User contributions [en]

When to use an HPC Cluster

2026-09-16T08:16:38Z

S Fischer: feedback from bwCloud colleagues

I have calculations to do - should I try using one of the bwHPC clusters for my tasks?

== When to use HPC computers ==

You can benefit from an HPC-Cluster if:

# You can run many separate calculations in parallel
# Software can efficiently divide your problem into many smaller problems that run in parallel
# You need more RAM (memory) than your computer can provide
# You need more GPUs and have no other source
# You need to process large amounts of data that do not fit on your computer

== When '''not''' to use HPC computers ==

You will probably not have a big benefit from using HPC when:

* Your calculation runs in serial (only on one compute core is used, things cannot run in parallel) and you have few calculations
* Your workflow requires that you run one calculation, then retrieve data to analyze it locally, then run the next calculation
* You have different computational needs than raw computing power.

Except 3) or 4) of "when to use a cluster" force you to use the clusters anyway.

If you need other computational tasks of the likes of

* hosting a web server
* hosting a database
* having a test bed for software development
* having systems for university courses on linux, programming languages, etc
* having an environment for student projects or theses,

then the bwCloud-OS offering virtual machines might be the right thing for you

'''→ https://bwcloud-os.de/'''

== Misconceptions ==
=== "Everything will be faster" ===
[[File:BwUniCluster_2.0_Feb2020_1024x423.jpg|right|thumb|alt=bwUniCluster2.0 |upright=1| many compute cores: Every "tray" in these racks contains 1-4 computers, every computer typically has 50-200 compute cores. ]]

The performance of a single compute core is not higher than that of your typical desktop computer. The main things we can offer are:

* Many compute cores
* Much RAM (memory)
* GPUs

=== "It's just a computer, I know how to use a computer" ===

While the clusters are indeed "just" many Linux computers, they are also multi-million Euro instruments. So while they may have many similarities with a Linux desktop, in some respects, it is better to think of them like of other expensive instruments you may use in your research. HPC clusters have hardware components you may have never heard of in the consumer market, they typically have more than one CPU socket (making among other things memory management more complicated), etc. etc. etc.

=== "I want to host servers on bwHPC" ===

On the bwHPC clusters, you submit jobs to a supercomputer that get scheduled and processed over time. It is not the place for permanent server hosting. If you need self-service virtual machines, check out [https://bwcloud-os.de/en/ bwCloud-OS], which offers an OpenStack-based [https://en.wikipedia.org/wiki/Infrastructure_as_a_service IaaS] platform for research, teaching, and administration in Baden-Württemberg.

== What are the Costs? ==

=== Monetary ===

No cost to you as the end-user

(But of course the HPC systems are bought for millions of Euro and the power cost of running calculations is in the same order of magnitude as buying the systems)

=== Effort / Time ===

There is quite a learning curve to start calculating.

* Linux shell knowledge is a major part
* HPC-specific knowledge:
** Software module system - software supplied by the cluster maintainers (vide infra)
** How to use the scheduler / write job scripts: how to send calculations to a computer on the cluster (vide infra)
* Wait times: a good cluster is always busy. Expect a waiting time betwween 1h and 2 days until your calculation(s) start

=== Compute Workflow ===

A short description of the workflow how running calculation works can be found under [[Running Calculations]] and can give you a general idea.

=== Software ===

Basic usage is very simple: you run <code> module load module_name </code> and use the software, but important documentation and examples are also built into the modules.

The usage of the software on the cluster is described in [[Environment Modules]]

== Still With Us? ==

If you feel your calculations meet the requirements and you will save a lot of time despite some learning overhead, proceed to the [[Registration]] page.

Helix/Software/Matlab

2026-09-11T10:29:16Z

S Fischer: /* MATLAB Compiler/Runtime */

{| style="border: 2px solid #d33; background-color: #fee7e6; padding: 10px; margin-bottom: 1em; width: 100%;"
|-
| '''⚠ MATLAB modules have been removed on March 31, 2026.'''

The MathWorks state license (Landeslizenz) has expired on March 31, 2026 and will not be renewed. The MATLAB modules <code>math/matlab</code> are no longer be available on Helix.

'''Alternatives:'''
* '''GNU Octave''' (<code>module load math/octave</code>): MATLAB scripts that do not use special features of toolboxes may run with Octave without or with minor changes.
* '''Matlab Compiler / Matlab Runtime''': Use the [https://de.mathworks.com/products/compiler.html MATLAB Compiler] to build stand-alone binaries on your local computer (with your own license) and run them with the MATLAB Runtime on the cluster — no license required at runtime (see section "Compile MATLAB binaries with mcc" below).
* '''Institute license''': If your institute has its own MathWorks network license, it may be possible to use it from the cluster. This must be checked on a case-by-case basis — please [https://www.bwhpc.de/supportportal.php submit a ticket].
* Other alternatives: <code>math/julia</code>, <code>math/R</code>, <code>devel/python</code>
|}

{{Softwarepage|math/matlab}}

{| width=600px class="wikitable"
|-
! Description !! Content
|-
| module load
| math/matlab
|-
| License
| [https://de.mathworks.com/pricing-licensing/index.html?intendeduse=edu&prodcode=ML Academic License/Commercial]
|-
| Citing
| n/a
|-
| Links
| [https://de.mathworks.com/products/matlab/ MATLAB Homepage] | [https://de.mathworks.com/index.html?s_tid=gn_logo MathWorks Homepage] | [https://de.mathworks.com/support/?s_tid=gn_supp Support and more]
|-
| Graphical Interface
| No
|}

= Description =

'''MATLAB''' (MATrix LABoratory) is a high-level programming language and interactive computing environment for numerical calculation and data visualization.

= Loading MATLAB =

The preferable way is to run the MATLAB command line interface without GUI:
<pre>$ matlab -nodisplay</pre>

An interactive MATLAB session with graphical user interface (GUI) can be started with the command (requires X11 forwarding enabled for your ssh login):
<pre>$ matlab</pre>

Note: Do not start a long-duration interactive MATLAB session on a login node of the cluster. Submit an [[Helix/Slurm#Interactive_Jobs | interactive job]] and start MATLAB from within the dedicated compute node assigned to you by the queueing system.

The following generic command will execute a MATLAB script or function named "example":
<pre>$ matlab -nodisplay -batch example > result.out 2>&1</pre>

The output of this session will be redirected to the file result.out. The option <syntaxhighlight style="border:0px" inline=1>-batch</syntaxhighlight> executes the MATLAB statement non-interactively.

= Parallel Computing Using MATLAB =

Parallelization of MATLAB jobs is realized via the built-in multi-threading provided by MATLAB's BLAS and FFT implementation and the parallel computing functionality of MATLAB's Parallel Computing Toolbox (PCT).

== Implicit Threading ==

A large number of built-in MATLAB functions may utilize multiple cores automatically without any code modifications required. This is referred to as implicit multi-threading and must be strictly distinguished from explicit parallelism provided by the Parallel Computing Toolbox (PCT) which requires specific commands in your code in order to create threads.

Implicit threading particularly takes place for linear algebra operations (such as the solution to a linear system A\b or matrix products A*B) and FFT operations. Many other high-level MATLAB functions do also benefit from multi-threading capabilities of their underlying routines. If multi-threading is not desired, single-threading can be enforced by adding the command line option <syntaxhighlight style="border:0px" inline=1>-singleCompThread</syntaxhighlight>.

Whenever implicit threading takes place, MATLAB will detect the total number of cores that exist on a machine and by default makes use of all of them. This has very important implications for MATLAB jobs in HPC environments with shared-node job scheduling policy (i.e. with multiple users sharing one compute node). Due to this behaviour, a MATLAB job may take over more compute resources than assigned by the queueing system of the cluster (and thereby taking away these resources from all other users with running jobs on the same node - including your own jobs).

Therefore, when running in multi-threaded mode, MATLAB always requires the user's intervention to not allocate all cores of the machine (unless requested so from the queueing system). The number of threads must be controlled from within the code by means of the <syntaxhighlight style="border:0px" inline=1>maxNumCompThreads(N)</syntaxhighlight> function or, alternatively, with the <syntaxhighlight style="border:0px" inline=1>feature('numThreads', N)</syntaxhighlight> function (which is undocumented).

== Using the Parallel Computing Toolbox (PCT) ==

By using the PCT one can make explicit use of several cores on multicore processors to parallelize MATLAB applications without MPI programming. Under MATLAB version 8.4 and earlier, this toolbox provides 12 workers (MATLAB computational engines) to execute applications locally on a single multicore node. Under MATLAB version 8.5 and later, the number of workers available is equal to the number of cores on a single node (up to a maximum of 512).

If multiple PCT jobs are running at the same time, they all write temporary MATLAB job information to the same location. This race condition can cause one or more of the parallel MATLAB jobs fail to use the parallel functionality of the toolbox.

To solve this issue, each MATLAB job should explicitly set a unique location where these files are created. This can be accomplished by the following snippet of code added to your MATLAB script.

<pre>
% create a local cluster object
pc = parcluster('local')

% get the number of dedicated cores from environment
nprocs = str2num(getenv('SLURM_NPROCS'))

% you may explicitly set the JobStorageLocation to the tmp directory that is unique to each cluster job (and is on local, fast scratch)
parpool_tmpdir = [getenv('TMP'),'/.matlab/local_cluster_jobs/slurm_jobID_',getenv('SLURM_JOB_ID')]
mkdir(parpool_tmpdir)
pc.JobStorageLocation = parpool_tmpdir

% start the parallel pool
parpool(pc, nprocs)
</pre>

If a large number of MATLAB-jobs are run in parallel, they can also conflict when writing generic information to <syntaxhighlight style="border:0px" inline=1>~/.matlab</syntaxhighlight>. This can be circumvented by setting <syntaxhighlight style="border:0px" inline=1>$MATLAB_PREFDIR</syntaxhighlight> to different directories in your Batch-script, e.g.

<pre>export MATLAB_PREFDIR=$TMP</pre>

== Using a different implementation of BLAS/LAPACK ==

By default, Matlab uses a version of Intel MKL as its BLAS/LAPACK library. It is possible to manually change this to different libraries by setting the <syntaxhighlight style="border:0px" inline=1>BLAS_VERSION</syntaxhighlight> and <syntaxhighlight style="border:0px" inline=1>LAPACK_VERSION</syntaxhighlight> environment variables. The following lines can be added to the batch-script to change it, in this example to BLIS and Flame, which are optimized for AMD processors:

<pre>
module load numlib/aocl/3.2.0

export BLAS_VERSION=$AOCL_LIB_DIR/libblis-mt.so
export LAPACK_VERSION=$AOCL_LIB_DIR/libflame.so

export BLIS_NUM_THREADS=$SLURM_NTASKS
</pre>

This can increase performance depending on the task, for example large matrix multiplications, but caution is advised.

= General Performance Tips for MATLAB =

MATLAB data structures (arrays or matrices) are dynamic in size, i.e. MATLAB will automatically resize the structure on demand. Although this seems to be convenient, MATLAB continually needs to allocate a new chunk of memory and copy over the data to the new block of memory as the array or matrix grows in a loop. This may take a significant amount of extra time during execution of the program.

Code performance can often be drastically improved by pre-allocating memory for the final expected size of the array or matrix before actually starting the processing loop. In order to pre-allocate an array of strings, you can use MATLAB's build-in cell function. In order to pre-allocate an array or matrix of numbers, you can use MATLAB's build-in zeros function.

The performance benefit of pre-allocation is illustrated with the following example code.

<pre>
% prealloc.m

clear all;

num=10000000;

disp('Without pre-allocation:')
tic
for i=1:num
a(i)=i;
end
toc

disp('With pre-allocation:')
tic
b=zeros(1,num);
for i=1:num
b(i)=i;
end
toc
</pre>

On a compute node, the result may look like this:

<pre>
Without pre-allocation:
Elapsed time is 2.879446 seconds.
With pre-allocation:
Elapsed time is 0.097557 seconds.
</pre>

Please recognize that the code runs almost 30 times faster with pre-allocation.

= MATLAB Compiler/Runtime =

If you do not have access to a full MATLAB installation on Helix, you can still run compiled MATLAB applications using the MATLAB Runtime module.

'''Important:''' The MATLAB Runtime version must '''exactly''' match the MATLAB version used for compilation. For example, code compiled with R2023a requires <code>math/matlab-runtime/R2023a</code>.

Three steps are necessary:
# Create a binary on your computer with MATLAB Compiler.
# Transfer the compiled binary to Helix.
# Load MATLAB Runtime and run compiled binary on Helix.

While the compiler supports the full MATLAB language, not all toolboxes are fully suported. The official documentation provides more details on [https://mathworks.com/products/compiler/compiler_support.html limitations] of the compiler. In addition, the [https://mathworks.com/help/pdf_doc/compiler/compiler.pdf user's guide] contains examples and a section on troubleshooting.

== Compile MATLAB binaries with mcc ==

If you have a MATLAB license that includes [https://de.mathworks.com/products/compiler.html MATLAB Compiler], e.g. on your local computer, you can use <code>mcc</code> to create binaries from MATLAB code.
Stand-alone MATLAB programs compiled with <code>mcc</code> do not require any license tokens at runtime and you can start jobs in parallel without any risk of running out of licences.

Compile your MATLAB code on a machine where you have a MATLAB license (e.g., your local workstation via an institute license):

<syntaxhighlight lang="bash">
mcc -m my_code.m
</syntaxhighlight>

Based on your MATLAB code (<code>my_code.m</code>), the compiler will create a binary (<code>my_code</code>) and a helper script (<code>run_my_code.sh</code>), which sets some environmental variables before it calls the binary.
This script may interfere with the module system.
Therefore, the binary should be called directly (see example below).

== Running compiled binaries with the MATLAB Runtime ==

Check available versions:

<syntaxhighlight lang="bash">
module avail math/matlab-runtime
</syntaxhighlight>

Currently installed: R2022a, R2023a, R2023b, R2024a, R2024b, R2025a, R2025b, R2026a.

Load a specific version that matches the version of your compiler:

<syntaxhighlight lang="bash">
module load math/matlab-runtime/R2026a
</syntaxhighlight>

Run your binary:
<syntaxhighlight lang="bash">
./my_code

# avoid the shell script generated by the compiler
# it interferes with the module system
# ./run_my_code.sh
</syntaxhighlight>

The MATLAB Runtime is [https://de.mathworks.com/products/compiler/matlab-runtime.html freely available from MathWorks] and can also be installed locally if needed.

Helix/Software/Matlab

2026-08-27T10:50:47Z

S Fischer: MATLAB Compiler/Runtime: links to documentation

{| style="border: 2px solid #d33; background-color: #fee7e6; padding: 10px; margin-bottom: 1em; width: 100%;"
|-
| '''⚠ MATLAB modules have been removed on March 31, 2026.'''

The MathWorks state license (Landeslizenz) has expired on March 31, 2026 and will not be renewed. The MATLAB modules <code>math/matlab</code> are no longer be available on Helix.

'''Alternatives:'''
* '''GNU Octave''' (<code>module load math/octave</code>): MATLAB scripts that do not use special features of toolboxes may run with Octave without or with minor changes.
* '''Matlab Compiler / Matlab Runtime''': Use the [https://de.mathworks.com/products/compiler.html MATLAB Compiler] to build stand-alone binaries on your local computer (with your own license) and run them with the MATLAB Runtime on the cluster — no license required at runtime (see section "Compile MATLAB binaries with mcc" below).
* '''Institute license''': If your institute has its own MathWorks network license, it may be possible to use it from the cluster. This must be checked on a case-by-case basis — please [https://www.bwhpc.de/supportportal.php submit a ticket].
* Other alternatives: <code>math/julia</code>, <code>math/R</code>, <code>devel/python</code>
|}

{{Softwarepage|math/matlab}}

{| width=600px class="wikitable"
|-
! Description !! Content
|-
| module load
| math/matlab
|-
| License
| [https://de.mathworks.com/pricing-licensing/index.html?intendeduse=edu&prodcode=ML Academic License/Commercial]
|-
| Citing
| n/a
|-
| Links
| [https://de.mathworks.com/products/matlab/ MATLAB Homepage] | [https://de.mathworks.com/index.html?s_tid=gn_logo MathWorks Homepage] | [https://de.mathworks.com/support/?s_tid=gn_supp Support and more]
|-
| Graphical Interface
| No
|}

= Description =

'''MATLAB''' (MATrix LABoratory) is a high-level programming language and interactive computing environment for numerical calculation and data visualization.

= Loading MATLAB =

The preferable way is to run the MATLAB command line interface without GUI:
<pre>$ matlab -nodisplay</pre>

An interactive MATLAB session with graphical user interface (GUI) can be started with the command (requires X11 forwarding enabled for your ssh login):
<pre>$ matlab</pre>

Note: Do not start a long-duration interactive MATLAB session on a login node of the cluster. Submit an [[Helix/Slurm#Interactive_Jobs | interactive job]] and start MATLAB from within the dedicated compute node assigned to you by the queueing system.

The following generic command will execute a MATLAB script or function named "example":
<pre>$ matlab -nodisplay -batch example > result.out 2>&1</pre>

The output of this session will be redirected to the file result.out. The option <syntaxhighlight style="border:0px" inline=1>-batch</syntaxhighlight> executes the MATLAB statement non-interactively.

= Parallel Computing Using MATLAB =

Parallelization of MATLAB jobs is realized via the built-in multi-threading provided by MATLAB's BLAS and FFT implementation and the parallel computing functionality of MATLAB's Parallel Computing Toolbox (PCT).

== Implicit Threading ==

A large number of built-in MATLAB functions may utilize multiple cores automatically without any code modifications required. This is referred to as implicit multi-threading and must be strictly distinguished from explicit parallelism provided by the Parallel Computing Toolbox (PCT) which requires specific commands in your code in order to create threads.

Implicit threading particularly takes place for linear algebra operations (such as the solution to a linear system A\b or matrix products A*B) and FFT operations. Many other high-level MATLAB functions do also benefit from multi-threading capabilities of their underlying routines. If multi-threading is not desired, single-threading can be enforced by adding the command line option <syntaxhighlight style="border:0px" inline=1>-singleCompThread</syntaxhighlight>.

Whenever implicit threading takes place, MATLAB will detect the total number of cores that exist on a machine and by default makes use of all of them. This has very important implications for MATLAB jobs in HPC environments with shared-node job scheduling policy (i.e. with multiple users sharing one compute node). Due to this behaviour, a MATLAB job may take over more compute resources than assigned by the queueing system of the cluster (and thereby taking away these resources from all other users with running jobs on the same node - including your own jobs).

Therefore, when running in multi-threaded mode, MATLAB always requires the user's intervention to not allocate all cores of the machine (unless requested so from the queueing system). The number of threads must be controlled from within the code by means of the <syntaxhighlight style="border:0px" inline=1>maxNumCompThreads(N)</syntaxhighlight> function or, alternatively, with the <syntaxhighlight style="border:0px" inline=1>feature('numThreads', N)</syntaxhighlight> function (which is undocumented).

== Using the Parallel Computing Toolbox (PCT) ==

By using the PCT one can make explicit use of several cores on multicore processors to parallelize MATLAB applications without MPI programming. Under MATLAB version 8.4 and earlier, this toolbox provides 12 workers (MATLAB computational engines) to execute applications locally on a single multicore node. Under MATLAB version 8.5 and later, the number of workers available is equal to the number of cores on a single node (up to a maximum of 512).

If multiple PCT jobs are running at the same time, they all write temporary MATLAB job information to the same location. This race condition can cause one or more of the parallel MATLAB jobs fail to use the parallel functionality of the toolbox.

To solve this issue, each MATLAB job should explicitly set a unique location where these files are created. This can be accomplished by the following snippet of code added to your MATLAB script.

<pre>
% create a local cluster object
pc = parcluster('local')

% get the number of dedicated cores from environment
nprocs = str2num(getenv('SLURM_NPROCS'))

% you may explicitly set the JobStorageLocation to the tmp directory that is unique to each cluster job (and is on local, fast scratch)
parpool_tmpdir = [getenv('TMP'),'/.matlab/local_cluster_jobs/slurm_jobID_',getenv('SLURM_JOB_ID')]
mkdir(parpool_tmpdir)
pc.JobStorageLocation = parpool_tmpdir

% start the parallel pool
parpool(pc, nprocs)
</pre>

If a large number of MATLAB-jobs are run in parallel, they can also conflict when writing generic information to <syntaxhighlight style="border:0px" inline=1>~/.matlab</syntaxhighlight>. This can be circumvented by setting <syntaxhighlight style="border:0px" inline=1>$MATLAB_PREFDIR</syntaxhighlight> to different directories in your Batch-script, e.g.

<pre>export MATLAB_PREFDIR=$TMP</pre>

== Using a different implementation of BLAS/LAPACK ==

By default, Matlab uses a version of Intel MKL as its BLAS/LAPACK library. It is possible to manually change this to different libraries by setting the <syntaxhighlight style="border:0px" inline=1>BLAS_VERSION</syntaxhighlight> and <syntaxhighlight style="border:0px" inline=1>LAPACK_VERSION</syntaxhighlight> environment variables. The following lines can be added to the batch-script to change it, in this example to BLIS and Flame, which are optimized for AMD processors:

<pre>
module load numlib/aocl/3.2.0

export BLAS_VERSION=$AOCL_LIB_DIR/libblis-mt.so
export LAPACK_VERSION=$AOCL_LIB_DIR/libflame.so

export BLIS_NUM_THREADS=$SLURM_NTASKS
</pre>

This can increase performance depending on the task, for example large matrix multiplications, but caution is advised.

= General Performance Tips for MATLAB =

MATLAB data structures (arrays or matrices) are dynamic in size, i.e. MATLAB will automatically resize the structure on demand. Although this seems to be convenient, MATLAB continually needs to allocate a new chunk of memory and copy over the data to the new block of memory as the array or matrix grows in a loop. This may take a significant amount of extra time during execution of the program.

Code performance can often be drastically improved by pre-allocating memory for the final expected size of the array or matrix before actually starting the processing loop. In order to pre-allocate an array of strings, you can use MATLAB's build-in cell function. In order to pre-allocate an array or matrix of numbers, you can use MATLAB's build-in zeros function.

The performance benefit of pre-allocation is illustrated with the following example code.

<pre>
% prealloc.m

clear all;

num=10000000;

disp('Without pre-allocation:')
tic
for i=1:num
a(i)=i;
end
toc

disp('With pre-allocation:')
tic
b=zeros(1,num);
for i=1:num
b(i)=i;
end
toc
</pre>

On a compute node, the result may look like this:

<pre>
Without pre-allocation:
Elapsed time is 2.879446 seconds.
With pre-allocation:
Elapsed time is 0.097557 seconds.
</pre>

Please recognize that the code runs almost 30 times faster with pre-allocation.

= MATLAB Compiler/Runtime =

If you do not have access to a full MATLAB installation on Helix, you can still run compiled MATLAB applications using the MATLAB Runtime module.

'''Important:''' The MATLAB Runtime version must '''exactly''' match the MATLAB version used for compilation. For example, code compiled with R2023a requires <code>math/matlab-runtime/R2023a</code>.

Three steps are necessary:
# Create a binary on your computer with MATLAB Compiler.
# Transfer the compiled binary to Helix.
# Load MATLAB Runtime and run compiled binary on Helix.

While the compiler supports the full MATLAB language, not all toolboxes are fully suported. The official documentation provides more details on [https://mathworks.com/products/compiler/compiler_support.html limitations] of the compiler. In addition, the [https://mathworks.com/help/pdf_doc/compiler/compiler.pdf user's guide] contains examples and a section on troubleshooting.

== Compile MATLAB binaries with mcc ==

If you have a MATLAB license that includes [https://de.mathworks.com/products/compiler.html MATLAB Compiler], e.g. on your local computer, you can use <code>mcc</code> to create binaries from MATLAB code.
Stand-alone MATLAB programs compiled with <code>mcc</code> do not require any license tokens at runtime and you can start jobs in parallel without any risk of running out of licences.

Compile your MATLAB code on a machine where you have a MATLAB license (e.g., your local workstation via an institute license):

<syntaxhighlight lang="bash">
mcc -m my_code.m
</syntaxhighlight>

== Running compiled binaries with the MATLAB Runtime ==

Check available versions:

<syntaxhighlight lang="bash">
module avail math/matlab-runtime
</syntaxhighlight>

Currently installed: R2022a, R2023a, R2023b, R2024a, R2024b, R2025a, R2025b.

Load a specific version that matches the version of your compiler:

<syntaxhighlight lang="bash">
module load math/matlab-runtime/R2025b
</syntaxhighlight>

Run your binary:
<syntaxhighlight lang="bash">
./my_code
</syntaxhighlight>

The MATLAB Runtime is [https://de.mathworks.com/products/compiler/matlab-runtime.html freely available from MathWorks] and can also be installed locally if needed.

When to use an HPC Cluster

2026-08-25T08:38:49Z

S Fischer: change link to English website

I have calculations to do - should I try using one of the bwHPC clusters for my tasks?

== When to use HPC computers ==

You can benefit from an HPC-Cluster if:

# You can run many separate calculations in parallel
# Software can efficiently divide your problem into many smaller problems that run in parallel
# You need more RAM (memory) than your computer can provide
# You need more GPUs and have no other source
# You need to process large amounts of data that do not fit on your computer

== When '''not''' to use HPC computers ==

You will probably not have a big benefit from using HPC when:

* Your calculation runs in serial (only on one compute core is used, things cannot run in parallel) and you have few calculations
* Your workflow requires that you run one calculation, then retrieve data to analyze it locally, then run the next calculation

Except 3) or 4) of "when to use a cluster" force you to use the clusters anyway.

== Misconceptions ==
=== "Everything will be faster" ===
[[File:BwUniCluster_2.0_Feb2020_1024x423.jpg|right|thumb|alt=bwUniCluster2.0 |upright=1| many compute cores: Every "tray" in these racks contains 1-4 computers, every computer typically has 50-200 compute cores. ]]

The performance of a single compute core is not higher than that of your typical desktop computer. The main things we can offer are:

* Many compute cores
* Much RAM (memory)
* GPUs

=== "It's just a computer, I know how to use a computer" ===

While the clusters are indeed "just" many Linux computers, they are also multi-million Euro instruments. So while they may have many similarities with a Linux desktop, in some respects, it is better to think of them like of other expensive instruments you may use in your research. HPC clusters have hardware components you may have never heard of in the consumer market, they typically have more than one CPU socket (making among other things memory management more complicated), etc. etc. etc.

=== "I want to host servers on bwHPC" ===

On the bwHPC clusters, you submit jobs to a supercomputer that get scheduled and processed over time. It is not the place for permanent server hosting. If you need self-service virtual machines, check out [https://bwcloud-os.de/en/ bwCloud-OS], which offers an OpenStack-based [https://en.wikipedia.org/wiki/Infrastructure_as_a_service IaaS] platform for research, teaching, and administration in Baden-Württemberg.

== What are the Costs? ==

=== Monetary ===

No cost to you as the end-user

(But of course the HPC systems are bought for millions of Euro and the power cost of running calculations is in the same order of magnitude as buying the systems)

=== Effort / Time ===

There is quite a learning curve to start calculating.

* Linux shell knowledge is a major part
* HPC-specific knowledge:
** Software module system - software supplied by the cluster maintainers (vide infra)
** How to use the scheduler / write job scripts: how to send calculations to a computer on the cluster (vide infra)
* Wait times: a good cluster is always busy. Expect a waiting time betwween 1h and 2 days until your calculation(s) start

=== Compute Workflow ===

A short description of the workflow how running calculation works can be found under [[Running Calculations]] and can give you a general idea.

=== Software ===

Basic usage is very simple: you run <code> module load module_name </code> and use the software, but important documentation and examples are also built into the modules.

The usage of the software on the cluster is described in [[Environment Modules]]

== Still With Us? ==

If you feel your calculations meet the requirements and you will save a lot of time despite some learning overhead, proceed to the [[Registration]] page.

When to use an HPC Cluster

2026-08-25T08:37:16Z

S Fischer: more details on bwCloud-OS

I have calculations to do - should I try using one of the bwHPC clusters for my tasks?

== When to use HPC computers ==

You can benefit from an HPC-Cluster if:

# You can run many separate calculations in parallel
# Software can efficiently divide your problem into many smaller problems that run in parallel
# You need more RAM (memory) than your computer can provide
# You need more GPUs and have no other source
# You need to process large amounts of data that do not fit on your computer

== When '''not''' to use HPC computers ==

You will probably not have a big benefit from using HPC when:

* Your calculation runs in serial (only on one compute core is used, things cannot run in parallel) and you have few calculations
* Your workflow requires that you run one calculation, then retrieve data to analyze it locally, then run the next calculation

Except 3) or 4) of "when to use a cluster" force you to use the clusters anyway.

== Misconceptions ==
=== "Everything will be faster" ===
[[File:BwUniCluster_2.0_Feb2020_1024x423.jpg|right|thumb|alt=bwUniCluster2.0 |upright=1| many compute cores: Every "tray" in these racks contains 1-4 computers, every computer typically has 50-200 compute cores. ]]

The performance of a single compute core is not higher than that of your typical desktop computer. The main things we can offer are:

* Many compute cores
* Much RAM (memory)
* GPUs

=== "It's just a computer, I know how to use a computer" ===

While the clusters are indeed "just" many Linux computers, they are also multi-million Euro instruments. So while they may have many similarities with a Linux desktop, in some respects, it is better to think of them like of other expensive instruments you may use in your research. HPC clusters have hardware components you may have never heard of in the consumer market, they typically have more than one CPU socket (making among other things memory management more complicated), etc. etc. etc.

=== "I want to host servers on bwHPC" ===

On the bwHPC clusters, you submit jobs to a supercomputer that get scheduled and processed over time. It is not the place for permanent server hosting. If you need self-service virtual machines, check out [https://bwcloud-os.de/ bwCloud-OS], which offers an OpenStack-based [https://en.wikipedia.org/wiki/Infrastructure_as_a_service IaaS] platform for research, teaching, and administration in Baden-Württemberg.

== What are the Costs? ==

=== Monetary ===

No cost to you as the end-user

(But of course the HPC systems are bought for millions of Euro and the power cost of running calculations is in the same order of magnitude as buying the systems)

=== Effort / Time ===

There is quite a learning curve to start calculating.

* Linux shell knowledge is a major part
* HPC-specific knowledge:
** Software module system - software supplied by the cluster maintainers (vide infra)
** How to use the scheduler / write job scripts: how to send calculations to a computer on the cluster (vide infra)
* Wait times: a good cluster is always busy. Expect a waiting time betwween 1h and 2 days until your calculation(s) start

=== Compute Workflow ===

A short description of the workflow how running calculation works can be found under [[Running Calculations]] and can give you a general idea.

=== Software ===

Basic usage is very simple: you run <code> module load module_name </code> and use the software, but important documentation and examples are also built into the modules.

The usage of the software on the cluster is described in [[Environment Modules]]

== Still With Us? ==

If you feel your calculations meet the requirements and you will save a lot of time despite some learning overhead, proceed to the [[Registration]] page.

When to use an HPC Cluster

2026-08-25T08:30:17Z

S Fischer: updated link

I have calculations to do - should I try using one of the bwHPC clusters for my tasks?

== When to use HPC computers ==

You can benefit from an HPC-Cluster if:

# You can run many separate calculations in parallel
# Software can efficiently divide your problem into many smaller problems that run in parallel
# You need more RAM (memory) than your computer can provide
# You need more GPUs and have no other source
# You need to process large amounts of data that do not fit on your computer

== When '''not''' to use HPC computers ==

You will probably not have a big benefit from using HPC when:

* Your calculation runs in serial (only on one compute core is used, things cannot run in parallel) and you have few calculations
* Your workflow requires that you run one calculation, then retrieve data to analyze it locally, then run the next calculation

Except 3) or 4) of "when to use a cluster" force you to use the clusters anyway.

== Misconceptions ==
=== "Everything will be faster" ===
[[File:BwUniCluster_2.0_Feb2020_1024x423.jpg|right|thumb|alt=bwUniCluster2.0 |upright=1| many compute cores: Every "tray" in these racks contains 1-4 computers, every computer typically has 50-200 compute cores. ]]

The performance of a single compute core is not higher than that of your typical desktop computer. The main things we can offer are:

* Many compute cores
* Much RAM (memory)
* GPUs

=== "It's just a computer, I know how to use a computer" ===

While the clusters are indeed "just" many Linux computers, they are also multi-million Euro instruments. So while they may have many similarities with a Linux desktop, in some respects, it is better to think of them like of other expensive instruments you may use in your research. HPC clusters have hardware components you may have never heard of in the consumer market, they typically have more than one CPU socket (making among other things memory management more complicated), etc. etc. etc.

=== "I want to host servers on bwHPC" ===

On the bwHPC-clusters, you submit jobs to a supercomputer that get scheduled and processed over time. It is not the place for permanent server hosting. If you need self-service virtual machines, check out the [https://bwcloud-os.de/ bwCloud-OS].

== What are the Costs? ==

=== Monetary ===

No cost to you as the end-user

(But of course the HPC systems are bought for millions of Euro and the power cost of running calculations is in the same order of magnitude as buying the systems)

=== Effort / Time ===

There is quite a learning curve to start calculating.

* Linux shell knowledge is a major part
* HPC-specific knowledge:
** Software module system - software supplied by the cluster maintainers (vide infra)
** How to use the scheduler / write job scripts: how to send calculations to a computer on the cluster (vide infra)
* Wait times: a good cluster is always busy. Expect a waiting time betwween 1h and 2 days until your calculation(s) start

=== Compute Workflow ===

A short description of the workflow how running calculation works can be found under [[Running Calculations]] and can give you a general idea.

=== Software ===

Basic usage is very simple: you run <code> module load module_name </code> and use the software, but important documentation and examples are also built into the modules.

The usage of the software on the cluster is described in [[Environment Modules]]

== Still With Us? ==

If you feel your calculations meet the requirements and you will save a lot of time despite some learning overhead, proceed to the [[Registration]] page.

Helix/Software/Matlab

2026-08-24T10:35:09Z

S Fischer: MATLAB Runtime: reorder paragraphs and add more details

{| style="border: 2px solid #d33; background-color: #fee7e6; padding: 10px; margin-bottom: 1em; width: 100%;"
|-
| '''⚠ MATLAB modules have been removed on March 31, 2026.'''

The MathWorks state license (Landeslizenz) has expired on March 31, 2026 and will not be renewed. The MATLAB modules <code>math/matlab</code> are no longer be available on Helix.

'''Alternatives:'''
* '''GNU Octave''' (<code>module load math/octave</code>): MATLAB scripts that do not use special features of toolboxes may run with Octave without or with minor changes.
* '''Matlab Compiler / Matlab Runtime''': Use the [https://de.mathworks.com/products/compiler.html MATLAB Compiler] to build stand-alone binaries on your local computer (with your own license) and run them with the MATLAB Runtime on the cluster — no license required at runtime (see section "Compile MATLAB binaries with mcc" below).
* '''Institute license''': If your institute has its own MathWorks network license, it may be possible to use it from the cluster. This must be checked on a case-by-case basis — please [https://www.bwhpc.de/supportportal.php submit a ticket].
* Other alternatives: <code>math/julia</code>, <code>math/R</code>, <code>devel/python</code>
|}

{{Softwarepage|math/matlab}}

{| width=600px class="wikitable"
|-
! Description !! Content
|-
| module load
| math/matlab
|-
| License
| [https://de.mathworks.com/pricing-licensing/index.html?intendeduse=edu&prodcode=ML Academic License/Commercial]
|-
| Citing
| n/a
|-
| Links
| [https://de.mathworks.com/products/matlab/ MATLAB Homepage] | [https://de.mathworks.com/index.html?s_tid=gn_logo MathWorks Homepage] | [https://de.mathworks.com/support/?s_tid=gn_supp Support and more]
|-
| Graphical Interface
| No
|}

= Description =

'''MATLAB''' (MATrix LABoratory) is a high-level programming language and interactive computing environment for numerical calculation and data visualization.

= Loading MATLAB =

The preferable way is to run the MATLAB command line interface without GUI:
<pre>$ matlab -nodisplay</pre>

An interactive MATLAB session with graphical user interface (GUI) can be started with the command (requires X11 forwarding enabled for your ssh login):
<pre>$ matlab</pre>

Note: Do not start a long-duration interactive MATLAB session on a login node of the cluster. Submit an [[Helix/Slurm#Interactive_Jobs | interactive job]] and start MATLAB from within the dedicated compute node assigned to you by the queueing system.

The following generic command will execute a MATLAB script or function named "example":
<pre>$ matlab -nodisplay -batch example > result.out 2>&1</pre>

The output of this session will be redirected to the file result.out. The option <syntaxhighlight style="border:0px" inline=1>-batch</syntaxhighlight> executes the MATLAB statement non-interactively.

= Parallel Computing Using MATLAB =

Parallelization of MATLAB jobs is realized via the built-in multi-threading provided by MATLAB's BLAS and FFT implementation and the parallel computing functionality of MATLAB's Parallel Computing Toolbox (PCT).

== Implicit Threading ==

A large number of built-in MATLAB functions may utilize multiple cores automatically without any code modifications required. This is referred to as implicit multi-threading and must be strictly distinguished from explicit parallelism provided by the Parallel Computing Toolbox (PCT) which requires specific commands in your code in order to create threads.

Implicit threading particularly takes place for linear algebra operations (such as the solution to a linear system A\b or matrix products A*B) and FFT operations. Many other high-level MATLAB functions do also benefit from multi-threading capabilities of their underlying routines. If multi-threading is not desired, single-threading can be enforced by adding the command line option <syntaxhighlight style="border:0px" inline=1>-singleCompThread</syntaxhighlight>.

Whenever implicit threading takes place, MATLAB will detect the total number of cores that exist on a machine and by default makes use of all of them. This has very important implications for MATLAB jobs in HPC environments with shared-node job scheduling policy (i.e. with multiple users sharing one compute node). Due to this behaviour, a MATLAB job may take over more compute resources than assigned by the queueing system of the cluster (and thereby taking away these resources from all other users with running jobs on the same node - including your own jobs).

Therefore, when running in multi-threaded mode, MATLAB always requires the user's intervention to not allocate all cores of the machine (unless requested so from the queueing system). The number of threads must be controlled from within the code by means of the <syntaxhighlight style="border:0px" inline=1>maxNumCompThreads(N)</syntaxhighlight> function or, alternatively, with the <syntaxhighlight style="border:0px" inline=1>feature('numThreads', N)</syntaxhighlight> function (which is undocumented).

== Using the Parallel Computing Toolbox (PCT) ==

By using the PCT one can make explicit use of several cores on multicore processors to parallelize MATLAB applications without MPI programming. Under MATLAB version 8.4 and earlier, this toolbox provides 12 workers (MATLAB computational engines) to execute applications locally on a single multicore node. Under MATLAB version 8.5 and later, the number of workers available is equal to the number of cores on a single node (up to a maximum of 512).

If multiple PCT jobs are running at the same time, they all write temporary MATLAB job information to the same location. This race condition can cause one or more of the parallel MATLAB jobs fail to use the parallel functionality of the toolbox.

To solve this issue, each MATLAB job should explicitly set a unique location where these files are created. This can be accomplished by the following snippet of code added to your MATLAB script.

<pre>
% create a local cluster object
pc = parcluster('local')

% get the number of dedicated cores from environment
nprocs = str2num(getenv('SLURM_NPROCS'))

% you may explicitly set the JobStorageLocation to the tmp directory that is unique to each cluster job (and is on local, fast scratch)
parpool_tmpdir = [getenv('TMP'),'/.matlab/local_cluster_jobs/slurm_jobID_',getenv('SLURM_JOB_ID')]
mkdir(parpool_tmpdir)
pc.JobStorageLocation = parpool_tmpdir

% start the parallel pool
parpool(pc, nprocs)
</pre>

If a large number of MATLAB-jobs are run in parallel, they can also conflict when writing generic information to <syntaxhighlight style="border:0px" inline=1>~/.matlab</syntaxhighlight>. This can be circumvented by setting <syntaxhighlight style="border:0px" inline=1>$MATLAB_PREFDIR</syntaxhighlight> to different directories in your Batch-script, e.g.

<pre>export MATLAB_PREFDIR=$TMP</pre>

== Using a different implementation of BLAS/LAPACK ==

By default, Matlab uses a version of Intel MKL as its BLAS/LAPACK library. It is possible to manually change this to different libraries by setting the <syntaxhighlight style="border:0px" inline=1>BLAS_VERSION</syntaxhighlight> and <syntaxhighlight style="border:0px" inline=1>LAPACK_VERSION</syntaxhighlight> environment variables. The following lines can be added to the batch-script to change it, in this example to BLIS and Flame, which are optimized for AMD processors:

<pre>
module load numlib/aocl/3.2.0

export BLAS_VERSION=$AOCL_LIB_DIR/libblis-mt.so
export LAPACK_VERSION=$AOCL_LIB_DIR/libflame.so

export BLIS_NUM_THREADS=$SLURM_NTASKS
</pre>

This can increase performance depending on the task, for example large matrix multiplications, but caution is advised.

= General Performance Tips for MATLAB =

MATLAB data structures (arrays or matrices) are dynamic in size, i.e. MATLAB will automatically resize the structure on demand. Although this seems to be convenient, MATLAB continually needs to allocate a new chunk of memory and copy over the data to the new block of memory as the array or matrix grows in a loop. This may take a significant amount of extra time during execution of the program.

Code performance can often be drastically improved by pre-allocating memory for the final expected size of the array or matrix before actually starting the processing loop. In order to pre-allocate an array of strings, you can use MATLAB's build-in cell function. In order to pre-allocate an array or matrix of numbers, you can use MATLAB's build-in zeros function.

The performance benefit of pre-allocation is illustrated with the following example code.

<pre>
% prealloc.m

clear all;

num=10000000;

disp('Without pre-allocation:')
tic
for i=1:num
a(i)=i;
end
toc

disp('With pre-allocation:')
tic
b=zeros(1,num);
for i=1:num
b(i)=i;
end
toc
</pre>

On a compute node, the result may look like this:

<pre>
Without pre-allocation:
Elapsed time is 2.879446 seconds.
With pre-allocation:
Elapsed time is 0.097557 seconds.
</pre>

Please recognize that the code runs almost 30 times faster with pre-allocation.

= MATLAB Compiler/Runtime =

If you do not have access to a full MATLAB installation on Helix, you can still run compiled MATLAB applications using the MATLAB Runtime module.

'''Important:''' The MATLAB Runtime version must '''exactly''' match the MATLAB version used for compilation. For example, code compiled with R2023a requires <code>math/matlab-runtime/R2023a</code>.

Three steps are necessary:
# Compile MATLAB binary on your computer.
# Transfer the compiled binary to Helix.
# Load MATLAB Runtime and run compiled binary on Helix.

== Compile MATLAB binaries with mcc ==

If you have a MATLAB license that includes [https://de.mathworks.com/products/compiler.html MATLAB Compiler], e.g. on your local computer, you can use <code>mcc</code> to create binaries from MATLAB code.
Stand-alone MATLAB programs compiled with <code>mcc</code> do not require any license tokens at runtime and you can start jobs in parallel without any risk of running out of licences.

Compile your MATLAB code on a machine where you have a MATLAB license (e.g., your local workstation via an institute license):

<syntaxhighlight lang="bash">
mcc -m my_code.m
</syntaxhighlight>

== Running compiled binaries with the MATLAB Runtime ==

Check available versions:

<syntaxhighlight lang="bash">
module avail math/matlab-runtime
</syntaxhighlight>

Currently installed: R2022a, R2023a, R2023b, R2024a, R2024b, R2025a, R2025b.

Load a specific version that matches the version of your compiler:

<syntaxhighlight lang="bash">
module load math/matlab-runtime/R2025b
</syntaxhighlight>

Run your binary:
<syntaxhighlight lang="bash">
./my_code
</syntaxhighlight>

The MATLAB Runtime is [https://de.mathworks.com/products/compiler/matlab-runtime.html freely available from MathWorks] and can also be installed locally if needed.

SDS@hd/Access

2026-08-24T09:19:08Z

S Fischer: /* Recommended Setup */

This page provides an overview on how to access data served by SDS@hd. To get an introduction to data transfer in general, see [[Data_Transfer|data transfer]].

'''Notation:''' Please replace all placeholder contents within guillemets <code>< ></code> with the actual value. For example, replace ''<name_of_my_dog>'' with ''Fluffy'' .

== Prerequisites ==

* You need to be [[SDS@hd/Registration|registered]].
* You need to be in the belwue-Network. This means you have to use the VPN Service of your HomeOrganization, if you want to access SDS@hd from outside the bwHPC-Clusters (e.g. via eduroam or from your personal notebook).

== Needed Information, independent of the chosen tool ==

* '''Username:''' You can look it up under your user data at [https://bwservices.uni-heidelberg.de/user/index.xhtml bwServices]. The username is ''<localPrimaryGroup>_<eduPersonPrincipalName>'' . (It is the same as for the bwHPC Clusters. Example: ''hd_ab123''.)
* '''Password:''' The Service Password that you set at bwServices in the [[SDS@hd/Registration#Step_B:_Registration_for_SDS@hd_Service|registration step]].
* '''SV-Acronym:''' Use the lower case version of the acronym for all access options.
* '''Hostname:''' The hostname depends on the chosen network protocol:
** For [[Data_Transfer/SSHFS|SSHFS]] and [[Data_Transfer/SFTP|SFTP]]: ''lsdf02-sshfs.urz.uni-heidelberg.de''
** For [[SDS@hd/Access/SMB|SMB]] and [[SDS@hd/Access/NFS|NFS]]: ''lsdf02.urz.uni-heidelberg.de''
** For [[Data_Transfer/WebDAV|WebDAV]] the url is: ''https://lsdf02-webdav.urz.uni-heidelberg.de''
* '''Domain:''' The domain is ''BWSERVICESAD'' (needed for smb and nfs connections).

== Recommended Setup ==
The following graphic shows the recommended way for accessing SDS@hd via Windows/Mac/Linux. The table provides an overview of the most important access options and links to the related pages. 
If you have various use cases, it is recommended to use [[Data_Transfer/Rclone|Rclone]]. You can copy, sync and mount with it. Thanks to its multithreading and checksumming capability Rclone is a good fit for transferring big data. 
For an overview of all connection possibilities, please have a look at [[Data_Transfer/All_Data_Transfer_Routes|all data transfer routes]].

[[File:Data_transfer_diagram_simple.jpg|center|700px]]
Figure 1: SDS@hd main transfer routes
*Institutions that allow SMB connections to SDS@hd are for example: Heidelberg University, Karlsruhe Institute of Technology (KIT), Hohenheim University, Freiburg University, Hochschule Rottenburg, Hochschule Biberach. Currently, SMB connections are not possible from Mannheim University.

{| class="wikitable"
|- style="font-weight:bold; text-align:center; vertical-align:middle;"
!
! Use Case
! Windows
! Mac
! Linux
! Possible Bandwith
! Firewall Ports
|-
| [[Data_Transfer/Rclone|Rclone]] + <protocol>
| copy, sync and mount, multithreading, checksumming for verifying success of up-/download
| ✓
| ✓
| ✓
| depends on used protocol
| depends on used protocol
|-
| [[SDS@hd/Access/SMB|SMB]]
| mount as network drive in file explorer or usage via Rclone
| [[SDS@hd/Access/SMB#Windows|✓]]
| [[SDS@hd/Access/SMB#Mac|✓]]
| [[SDS@hd/Access/SMB#Linux|✓]]
| up to 40 Gbit/sec
| 139 (netbios), 135 (rpc), 445 (smb)
|-
| [[Data_Transfer/WebDAV|WebDAV]]
| go to solution for restricted networks
| [✓]
| ✓
| ✓
| up to 100GBit/sec
| 80 (http), 443 (https)
|- style="vertical-align:middle;"
| [[Data_Transfer/Graphical_Clients#MobaXterm|MobaXterm]]
| Graphical User Interface (GUI)
| [[Data_Transfer/Graphical_Clients#MobaXterm|✓]]
| ☓
| ☓
| see sftp
| see sftp
|- style="vertical-align:middle;"
| [[SDS@hd/Access/NFS|NFS]]
| mount for multi-user environments
| ☓
| ☓
| [[SDS@hd/Access/NFS|✓]]
| up to 40 Gbit/sec
| -
|- style="vertical-align:middle;"
| [[Data_Transfer/SSHFS|SSHFS]]
| mount, needs stable internet connection
| ☓
| [[Data_Transfer/SSHFS#MacOS_&_Linux|✓]]
| [[Data_Transfer/SSHFS#MacOS_&_Linux|✓]]
| see sftp
| see sftp
|- style="vertical-align:middle;"
| [[Data_Transfer/SFTP|SFTP]]
| interactive shell, better usability when used together with Rclone
| [[Data_Transfer/SFTP#Windows|✓]]
| [[Data_Transfer/SFTP#MacOS_&_Linux|✓]]
| [[Data_Transfer/SFTP#MacOS_&_Linux|✓]]
| up to 40 Gbit/sec
| 22 (ssh)
|}
Table 1: SDS@hd transfer routes

=== Access from a bwHPC Cluster ===

'''bwUniCluster''' 
You can't mount to your $HOME directory but you can create a mount under $TMPDIR by following the instructions for [[Data_Transfer/Rclone#Usage_Rclone_Mount | Rclone mount]]. It is advised to wait a couple of seconds (<code>sleep 5</code>) before trying to use the mounted directory.

'''bwForCluster Helix''' 
You can directly access your storage space under ''/mnt/sds-hd/'' on all login and compute nodes.

'''bwForCluster BinAC 2''' 
You can directly access your storage space under ''/mnt/sds-hd/'' on all login and compute nodes. The prerequisites are:
* The SV responsible has enabled the SV on BinAC 2 once by writing to [mailto:sds-hd-support@urz.uni-heidelberg.de sds-hd-support@urz.uni-heidelberg.de]
* You have a valid kerberos ticket, which can be fetched with <code>kinit <userID></code>

'''Other''' 
You can mount your SDS@hd SV on the cluster yourself by using [[Data_Transfer/Rclone | Rclone]] with the [[Data_Transfer/Rclone#Usage_Rclone_Mount | Rclone mount]] command. As transfer protocol you can use WebDAV or sftp. For a full overview please have a look at [[Data_Transfer/All_Data_Transfer_Routes | All Data Transfer Routes]].

=== Access via Webbrowser (read-only) ===

Visit [https://lsdf02-webdav.urz.uni-heidelberg.de/ lsdf02-webdav.urz.uni-heidelberg.de] and login with your SDS@hd username and service password. Here you can get an overview of the data in your "Speichervorhaben" and download single files. To be able to do more, like moving data, uploading new files, or downloading complete folders, a suitable client is needed as described above.

== Best Practices ==

* '''Managing access rights'''
** When the SV is mounted on Windows, access rights can be adjusted in the file/folder properties menu. (Users from Heidelberg without Windows can use the [https://www.urz.uni-heidelberg.de/de/service-katalog/desktop-und-arbeitsplatz/windows-terminalserver Windows terminal server]).
** bwForCluster Helix users can change the access rights via Helix by using [[Workspace#Regular_Unix_Permissions | unix permissions]] or [[Workspace#ACLs:_Access_Control_Lists | access control lists]]. On non native mounts ACL changes won't work.
** Additionally to the already mentioned options, the SVV can take over ownership of files by opening a [[Data_Transfer/SFTP|SFTP]] shell and running <code>chown -R <userID> <path/to/folder></code> .

* '''Multiuser environment''' → Use [[SDS@hd/Access/NFS|NFS]]

== Troubleshooting ==

Maintance windows and known issues are communicated via the email list or the News section at the SDS@hd start page in the wiki.

* '''Issue:''' The credentials aren't accepted
*: Check if your credentials work in general by trying the access via webbrowser: [https://lsdf02-webdav.urz.uni-heidelberg.de/].
*: If this doesn't work:
*:: → [[Registration/Login/Username| Check your Username]]
*:: → [[Registration/bwForCluster/Helix#Troubleshooting_with_the_Help_of_bwServices | Troubleshooting with bwServices]]
* '''Other Issue'''
** If available, follow the troubleshooting guide of your specific connection method.
** Make sure to not use LAN and WLAN at the same time to prevent connection problems.
** If you have an institutional account, make sure to be a fully active member of your institution.
If these suggestions didn't help, write to the [mailto:sds-hd-support@urz.uni-heidelberg.de support]. Provide the following information:
* Your operating system
* Does the access via webbrowser work?
*: If yes, provide us with detailed information on how you tried to access your SV (used access method, username, ...).

Helix/bwVisu/JupyterLab

2026-08-18T08:41:23Z

S Fischer: icons looks different now

[https://jupyter.org/ JupyterLab] is an integrated development environment (IDE) that provides a flexible and scalable interface for the Jupyter Notebook system. It supports interactive data science and scientific computing across over 40 programming languages (including Python, Julia, and R).

== Change Python Version ==

The default python version can be seen by running <code>python --version</code> in the terminal.

A different python version can be installed into a new virtual environment and then registered as IPython kernel for the usage in JupyterLab. This is explained in the chapter [[#Add_packages_via_conda_environments | add packages via conda environments]].

== Install Python Packages ==

Python packages can be added by installing them into a virtual environment and then creating an IPython kernel from the virtual environment. 
Kernels can be shared. See the notes below. 
If you want to move a virtual environment, it is adivsed to recreate it in the new place. Otherwise, dependencies based on relative paths will break.

# Create a virtual environment with...
#* [[#Add_packages_via_venv_virtual_environments | ...venv]] or
#* [[#Add_packages_via_Conda_virtual_environments | ...conda]] (choose this option if you want to install a different python version) or
#* ...[https://docs.astral.sh/uv/getting-started/ uv] if you want to install a different python version but don't want to use conda.
# [[#Create_an_IPython_Kernel | Create an IPython kernel]] from the virtual environment
# Use the kernel within JupyterLab
#* By default new kernels are saved under <code>~/.local/share/jupyter</code> and this location is automatically detected. Therefore, new kernels are directly available.
#*:[[File:BwVisu JuypterLab KernelPath.png|In the JupyterLab job configuration form, a custom kernel path can be provided.|right|thumb|x150px]]
#* If the kernel is saved somewhere else, the path can be provided in the "Kernel path" field when configuring the JupyterLab job (see image). For a kernel placed under <code>path_to_parent_dir/share/jupyter/kernels/my_kernel</code> the needed "Kernel path" would be <code>path_to_parent_dir/share/jupyter</code>.
# When the kernel is used the first time, the file <code>notebook_secrets</code> is created automatically. It can be found under "Kernel path". For others to use the kernel, they must have read access to this file. The command <code>chmod 750 notebook_secrets</code> would for example allow the whole SDS@hd SV read access. For the access management in workspaces, please see [[Workspace#Setting_Permissions_for_Sharing_Files| Workspace Permissions]].

Notes regarding the sharing of IPython kernels
* The virtual environment and the kernel need to be placed in a shared directory. For example at SDS@hd.
* There could be a subdirectory for the virtual environments and one for the kernels.
* The path to the kernels is saved in the environment variable $JUPYTER_DATA_DIR. Jupyter relevant paths can be seen with <code>jupyter --paths</code>

=== Add packages via ''venv'' virtual environments ===
More information about venv or other python virtual environments can be found at the [[Development/Python | Python]] page.

Steps for creating a '''venv''' virtual environment:
<ol style="list-style-type: decimal;">
<li>Open a terminal.</li>
<li>Create a new virtual evironment:
<syntaxhighlight lang="bash">python3 -m venv <env_parent_dir>/<env_name></syntaxhighlight>
* <code>env_parent_dir</code> is the path to the folder where the virtual environment shall be created. Relative paths can be used.
* Caution: If you you want to share the environment with others, make sure to already create it in the shared place.
</li>
<li>Activate the environment:
<syntaxhighlight lang="bash">source <env_parent_dir>/<env_name>/bin/activate</syntaxhighlight></li>
<li>Update pip and install packages:
<syntaxhighlight lang="bash">pip install -U pip --no-user
# when the environment is installed in home
pip install <packagename>
# when the environment is installed somewhere else and shall not have dependencies in home so that others can access it as well
pip install <packagename> --no-user</syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

=== Add packages via Conda virtual environments ===
More information about using conda can be found at the [[Development/Conda | Conda]] page.

<ol style="list-style-type: decimal;">
<li>Load the miniforge module by clicking first on the double hexagon icon on the left-hand side of Jupyter's start page and then on the "load" button right of the entry for miniforge in the software module menu.
<li>Open a terminal.</li>
<li>Create a new virtual environment:
* If you are the only person using the environment, you can install it in your home directory:
<syntaxhighlight lang="bash">conda create --name <env_name> python=<python version></syntaxhighlight>
* If you want to install it into a different directory, for example a shared place:
<syntaxhighlight lang="bash">conda create --prefix <path_to_shared_directory>/<env_name> python=<python version>
</syntaxhighlight>
</li>
<li>Activate your environment:
<syntaxhighlight lang="bash">conda activate <myenv></syntaxhighlight></li>
<li>Install your packages:
<syntaxhighlight lang="bash">conda install <mypackage></syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

== Create an IPython Kernel ==

Python kernels are implementations of the Jupyter notebook environment for different languages or virtual environments. You can switch between kernels easily, allowing you to use the best tool for a specific task.
conda_kernels

=== Create a kernel from a virtual environment ===

<ol>
<li>Activate the virtual environment.</li>
<li>Install the ipykernel package:
<syntaxhighlight lang="bash">pip install ipykernel</syntaxhighlight></li>
<li>Register the virtual environment as custom kernel to Jupyter.
* If you are the only person using the environment:
<syntaxhighlight lang="bash">python3 -m ipykernel install --user --name=<kernel_name></syntaxhighlight>
The kernel can be found under <code>~/.local/share/jupyter/kernels/</code>.
* If you installed the environment in a shared place and want to have the kernel there as well:
<syntaxhighlight lang="bash">python3 -m ipykernel install --prefix <path_to_kernel_folder> --name=<kernel_name></syntaxhighlight>
The kernel can then be found under <code>path_to_kernel_folder/share/jupyter/kernels/<kernel_name></code>. As long as the same <code>path_to_kernel_folder</code> is used, all kernels will be saved next to each other in "kernels".
</li>
</ol>

=== Multi-Language Support ===

JupyterLab supports over 40 programming languages including Python, R, Julia, and Scala. This is achieved through the use of different kernels.

==== R Kernel ====

<ol style="list-style-type: decimal;">
<li>On the cluster:
<pre>$ module load math/R
$ R
> install.packages('IRkernel')</pre></li>
<li>On bwVisu:
<ol style="list-style-type: decimal;">
<li>Start Jupyter App</li>
<li>In left menu: load math/R</li>
<li>Open Console:</li>

<pre>$ R
> IRkernel::installspec(displayname = 'R 4.2')</pre>

<li>Start kernel 'R 4.2' as console or notebook</li>
</ol>
</ol>

==== Julia Kernel ====

Load the math/julia module. Open the Terminal.

<pre>
julia
]
add IJulia
</pre>

After that, Julia is available as a kernel.

== Interactive Widgets ==

JupyterLab supports interactive widgets that can create UI controls for interactive data visualization and manipulation within the notebooks. Example of using an interactive widget:

<pre class="{.python">from ipywidgets import IntSlider
slider = IntSlider()
display(slider)</pre>
These widgets can be sliders, dropdowns, buttons, etc., which can be connected to Python code running in the backend.

== FAQ ==

<ol><li>'''How can I use bwForCluster Helix software modules?'''
First click on the double hexagon icon on the left-hand side of Jupyter's start page. Then load a module by clicking on the "load" button next to the corresponding module entry.</li>
<li>'''My virtual environment works on Helix but not in the bwVisu JupyterLab job.'''
If the environment uses Helix modules, you have to load the modules in the bwVisu job first. For example, when you used the python 3.13 module for creating the environment, the path to this python version is saved in the environment. When the module is not loadedin bwVisu, the path is not available and you might get an error like "''[...]/bin/python: error while loading shared libraries: libpython3.13.so.1.0: cannot open shared object file: No such file or directory''"</li>
<li>'''How can I navigate to my SDS@hd folder in the file browser?'''
Please see the instructions at the [[Helix/bwVisu/Usage#Files | Usage]] page.</li>
<li>'''I prefer VSCode over JupyterLab. Can I start a JupyterLab job and then connect with it via VSCode?'''
This is not possible. Please start the job directly on Helix instead. You can find the instructions at the [[Development/VS_Code#Connect_to_Remote_Jupyter_Kernel | VSCode page]].</li>
<li>'''My conda commands are interrupted with message 'Killed'.'''
Request more memory when starting Jupyter.</li>
<li>'''Jupyterlab doesn't let me in but asks for a password.'''
Try using more memory for the job. If this doesn't help, try using the inkognito mode of your browser as the browser cache might be the problem.</li>
</ol>

Helix/bwVisu/JupyterLab

2026-08-18T08:34:05Z

S Fischer: Typo

[https://jupyter.org/ JupyterLab] is an integrated development environment (IDE) that provides a flexible and scalable interface for the Jupyter Notebook system. It supports interactive data science and scientific computing across over 40 programming languages (including Python, Julia, and R).

== Change Python Version ==

The default python version can be seen by running <code>python --version</code> in the terminal.

A different python version can be installed into a new virtual environment and then registered as IPython kernel for the usage in JupyterLab. This is explained in the chapter [[#Add_packages_via_conda_environments | add packages via conda environments]].

== Install Python Packages ==

Python packages can be added by installing them into a virtual environment and then creating an IPython kernel from the virtual environment. 
Kernels can be shared. See the notes below. 
If you want to move a virtual environment, it is adivsed to recreate it in the new place. Otherwise, dependencies based on relative paths will break.

# Create a virtual environment with...
#* [[#Add_packages_via_venv_virtual_environments | ...venv]] or
#* [[#Add_packages_via_Conda_virtual_environments | ...conda]] (choose this option if you want to install a different python version) or
#* ...[https://docs.astral.sh/uv/getting-started/ uv] if you want to install a different python version but don't want to use conda.
# [[#Create_an_IPython_Kernel | Create an IPython kernel]] from the virtual environment
# Use the kernel within JupyterLab
#* By default new kernels are saved under <code>~/.local/share/jupyter</code> and this location is automatically detected. Therefore, new kernels are directly available.
#*:[[File:BwVisu JuypterLab KernelPath.png|In the JupyterLab job configuration form, a custom kernel path can be provided.|right|thumb|x150px]]
#* If the kernel is saved somewhere else, the path can be provided in the "Kernel path" field when configuring the JupyterLab job (see image). For a kernel placed under <code>path_to_parent_dir/share/jupyter/kernels/my_kernel</code> the needed "Kernel path" would be <code>path_to_parent_dir/share/jupyter</code>.
# When the kernel is used the first time, the file <code>notebook_secrets</code> is created automatically. It can be found under "Kernel path". For others to use the kernel, they must have read access to this file. The command <code>chmod 750 notebook_secrets</code> would for example allow the whole SDS@hd SV read access. For the access management in workspaces, please see [[Workspace#Setting_Permissions_for_Sharing_Files| Workspace Permissions]].

Notes regarding the sharing of IPython kernels
* The virtual environment and the kernel need to be placed in a shared directory. For example at SDS@hd.
* There could be a subdirectory for the virtual environments and one for the kernels.
* The path to the kernels is saved in the environment variable $JUPYTER_DATA_DIR. Jupyter relevant paths can be seen with <code>jupyter --paths</code>

=== Add packages via ''venv'' virtual environments ===
More information about venv or other python virtual environments can be found at the [[Development/Python | Python]] page.

Steps for creating a '''venv''' virtual environment:
<ol style="list-style-type: decimal;">
<li>Open a terminal.</li>
<li>Create a new virtual evironment:
<syntaxhighlight lang="bash">python3 -m venv <env_parent_dir>/<env_name></syntaxhighlight>
* <code>env_parent_dir</code> is the path to the folder where the virtual environment shall be created. Relative paths can be used.
* Caution: If you you want to share the environment with others, make sure to already create it in the shared place.
</li>
<li>Activate the environment:
<syntaxhighlight lang="bash">source <env_parent_dir>/<env_name>/bin/activate</syntaxhighlight></li>
<li>Update pip and install packages:
<syntaxhighlight lang="bash">pip install -U pip --no-user
# when the environment is installed in home
pip install <packagename>
# when the environment is installed somewhere else and shall not have dependencies in home so that others can access it as well
pip install <packagename> --no-user</syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

=== Add packages via Conda virtual environments ===
More information about using conda can be found at the [[Development/Conda | Conda]] page.

<ol style="list-style-type: decimal;">
<li>Load the miniforge module by clicking first on the blue hexagon icon on the left-hand side of Jupyter's start page and then on the "load" button right of the entry for miniforge in the software module menu.
<li>Open a terminal.</li>
<li>Create a new virtual environment:
* If you are the only person using the environment, you can install it in your home directory:
<syntaxhighlight lang="bash">conda create --name <env_name> python=<python version></syntaxhighlight>
* If you want to install it into a different directory, for example a shared place:
<syntaxhighlight lang="bash">conda create --prefix <path_to_shared_directory>/<env_name> python=<python version>
</syntaxhighlight>
</li>
<li>Activate your environment:
<syntaxhighlight lang="bash">conda activate <myenv></syntaxhighlight></li>
<li>Install your packages:
<syntaxhighlight lang="bash">conda install <mypackage></syntaxhighlight></li>
<li> [[#Create_an_IPython_Kernel | Create an IPython kernel]]</li>
</ol>

== Create an IPython Kernel ==

Python kernels are implementations of the Jupyter notebook environment for different languages or virtual environments. You can switch between kernels easily, allowing you to use the best tool for a specific task.
conda_kernels

=== Create a kernel from a virtual environment ===

<ol>
<li>Activate the virtual environment.</li>
<li>Install the ipykernel package:
<syntaxhighlight lang="bash">pip install ipykernel</syntaxhighlight></li>
<li>Register the virtual environment as custom kernel to Jupyter.
* If you are the only person using the environment:
<syntaxhighlight lang="bash">python3 -m ipykernel install --user --name=<kernel_name></syntaxhighlight>
The kernel can be found under <code>~/.local/share/jupyter/kernels/</code>.
* If you installed the environment in a shared place and want to have the kernel there as well:
<syntaxhighlight lang="bash">python3 -m ipykernel install --prefix <path_to_kernel_folder> --name=<kernel_name></syntaxhighlight>
The kernel can then be found under <code>path_to_kernel_folder/share/jupyter/kernels/<kernel_name></code>. As long as the same <code>path_to_kernel_folder</code> is used, all kernels will be saved next to each other in "kernels".
</li>
</ol>

=== Multi-Language Support ===

JupyterLab supports over 40 programming languages including Python, R, Julia, and Scala. This is achieved through the use of different kernels.

==== R Kernel ====

<ol style="list-style-type: decimal;">
<li>On the cluster:
<pre>$ module load math/R
$ R
> install.packages('IRkernel')</pre></li>
<li>On bwVisu:
<ol style="list-style-type: decimal;">
<li>Start Jupyter App</li>
<li>In left menu: load math/R</li>
<li>Open Console:</li>

<pre>$ R
> IRkernel::installspec(displayname = 'R 4.2')</pre>

<li>Start kernel 'R 4.2' as console or notebook</li>
</ol>
</ol>

==== Julia Kernel ====

Load the math/julia module. Open the Terminal.

<pre>
julia
]
add IJulia
</pre>

After that, Julia is available as a kernel.

== Interactive Widgets ==

JupyterLab supports interactive widgets that can create UI controls for interactive data visualization and manipulation within the notebooks. Example of using an interactive widget:

<pre class="{.python">from ipywidgets import IntSlider
slider = IntSlider()
display(slider)</pre>
These widgets can be sliders, dropdowns, buttons, etc., which can be connected to Python code running in the backend.

== FAQ ==

<ol><li>'''How can I use bwForCluster Helix software modules?'''
First click on the blue hexagon icon on the left-hand side of Jupyter's start page. Then load a module by clicking on the "load" button next to the corresponding module entry.</li>
<li>'''My virtual environment works on Helix but not in the bwVisu JupyterLab job.'''
If the environment uses Helix modules, you have to load the modules in the bwVisu job first. For example, when you used the python 3.13 module for creating the environment, the path to this python version is saved in the environment. When the module is not loadedin bwVisu, the path is not available and you might get an error like "''[...]/bin/python: error while loading shared libraries: libpython3.13.so.1.0: cannot open shared object file: No such file or directory''"</li>
<li>'''How can I navigate to my SDS@hd folder in the file browser?'''
Please see the instructions at the [[Helix/bwVisu/Usage#Files | Usage]] page.</li>
<li>'''I prefer VSCode over JupyterLab. Can I start a JupyterLab job and then connect with it via VSCode?'''
This is not possible. Please start the job directly on Helix instead. You can find the instructions at the [[Development/VS_Code#Connect_to_Remote_Jupyter_Kernel | VSCode page]].</li>
<li>'''My conda commands are interrupted with message 'Killed'.'''
Request more memory when starting Jupyter.</li>
<li>'''Jupyterlab doesn't let me in but asks for a password.'''
Try using more memory for the job. If this doesn't help, try using the inkognito mode of your browser as the browser cache might be the problem.</li>
</ol>

Helix/Software/Matlab

2026-08-03T10:03:51Z

S Fischer: /* Compile MATLAB binaries with mcc */

{| style="border: 2px solid #d33; background-color: #fee7e6; padding: 10px; margin-bottom: 1em; width: 100%;"
|-
| '''⚠ MATLAB modules have been removed on March 31, 2026.'''

The MathWorks state license (Landeslizenz) has expired on March 31, 2026 and will not be renewed. The MATLAB modules <code>math/matlab</code> are no longer be available on Helix.

'''Alternatives:'''
* '''GNU Octave''' (<code>module load math/octave</code>): MATLAB scripts that do not use special features of toolboxes may run with Octave without or with minor changes.
* '''Matlab Compiler / Matlab Runtime''': Use the [https://de.mathworks.com/products/compiler.html MATLAB Compiler] to build stand-alone binaries on your local computer (with your own license) and run them with the MATLAB Runtime on the cluster — no license required at runtime (see section "Compile MATLAB binaries with mcc" below).
* '''Institute license''': If your institute has its own MathWorks network license, it may be possible to use it from the cluster. This must be checked on a case-by-case basis — please [https://www.bwhpc.de/supportportal.php submit a ticket].
* Other alternatives: <code>math/julia</code>, <code>math/R</code>, <code>devel/python</code>
|}

{{Softwarepage|math/matlab}}

{| width=600px class="wikitable"
|-
! Description !! Content
|-
| module load
| math/matlab
|-
| License
| [https://de.mathworks.com/pricing-licensing/index.html?intendeduse=edu&prodcode=ML Academic License/Commercial]
|-
| Citing
| n/a
|-
| Links
| [https://de.mathworks.com/products/matlab/ MATLAB Homepage] | [https://de.mathworks.com/index.html?s_tid=gn_logo MathWorks Homepage] | [https://de.mathworks.com/support/?s_tid=gn_supp Support and more]
|-
| Graphical Interface
| No
|}

= Description =

'''MATLAB''' (MATrix LABoratory) is a high-level programming language and interactive computing environment for numerical calculation and data visualization.

= Loading MATLAB =

The preferable way is to run the MATLAB command line interface without GUI:
<pre>$ matlab -nodisplay</pre>

An interactive MATLAB session with graphical user interface (GUI) can be started with the command (requires X11 forwarding enabled for your ssh login):
<pre>$ matlab</pre>

Note: Do not start a long-duration interactive MATLAB session on a login node of the cluster. Submit an [[Helix/Slurm#Interactive_Jobs | interactive job]] and start MATLAB from within the dedicated compute node assigned to you by the queueing system.

The following generic command will execute a MATLAB script or function named "example":
<pre>$ matlab -nodisplay -batch example > result.out 2>&1</pre>

The output of this session will be redirected to the file result.out. The option <syntaxhighlight style="border:0px" inline=1>-batch</syntaxhighlight> executes the MATLAB statement non-interactively.

= Parallel Computing Using MATLAB =

Parallelization of MATLAB jobs is realized via the built-in multi-threading provided by MATLAB's BLAS and FFT implementation and the parallel computing functionality of MATLAB's Parallel Computing Toolbox (PCT).

== Implicit Threading ==

A large number of built-in MATLAB functions may utilize multiple cores automatically without any code modifications required. This is referred to as implicit multi-threading and must be strictly distinguished from explicit parallelism provided by the Parallel Computing Toolbox (PCT) which requires specific commands in your code in order to create threads.

Implicit threading particularly takes place for linear algebra operations (such as the solution to a linear system A\b or matrix products A*B) and FFT operations. Many other high-level MATLAB functions do also benefit from multi-threading capabilities of their underlying routines. If multi-threading is not desired, single-threading can be enforced by adding the command line option <syntaxhighlight style="border:0px" inline=1>-singleCompThread</syntaxhighlight>.

Whenever implicit threading takes place, MATLAB will detect the total number of cores that exist on a machine and by default makes use of all of them. This has very important implications for MATLAB jobs in HPC environments with shared-node job scheduling policy (i.e. with multiple users sharing one compute node). Due to this behaviour, a MATLAB job may take over more compute resources than assigned by the queueing system of the cluster (and thereby taking away these resources from all other users with running jobs on the same node - including your own jobs).

Therefore, when running in multi-threaded mode, MATLAB always requires the user's intervention to not allocate all cores of the machine (unless requested so from the queueing system). The number of threads must be controlled from within the code by means of the <syntaxhighlight style="border:0px" inline=1>maxNumCompThreads(N)</syntaxhighlight> function or, alternatively, with the <syntaxhighlight style="border:0px" inline=1>feature('numThreads', N)</syntaxhighlight> function (which is undocumented).

== Using the Parallel Computing Toolbox (PCT) ==

By using the PCT one can make explicit use of several cores on multicore processors to parallelize MATLAB applications without MPI programming. Under MATLAB version 8.4 and earlier, this toolbox provides 12 workers (MATLAB computational engines) to execute applications locally on a single multicore node. Under MATLAB version 8.5 and later, the number of workers available is equal to the number of cores on a single node (up to a maximum of 512).

If multiple PCT jobs are running at the same time, they all write temporary MATLAB job information to the same location. This race condition can cause one or more of the parallel MATLAB jobs fail to use the parallel functionality of the toolbox.

To solve this issue, each MATLAB job should explicitly set a unique location where these files are created. This can be accomplished by the following snippet of code added to your MATLAB script.

<pre>
% create a local cluster object
pc = parcluster('local')

% get the number of dedicated cores from environment
nprocs = str2num(getenv('SLURM_NPROCS'))

% you may explicitly set the JobStorageLocation to the tmp directory that is unique to each cluster job (and is on local, fast scratch)
parpool_tmpdir = [getenv('TMP'),'/.matlab/local_cluster_jobs/slurm_jobID_',getenv('SLURM_JOB_ID')]
mkdir(parpool_tmpdir)
pc.JobStorageLocation = parpool_tmpdir

% start the parallel pool
parpool(pc, nprocs)
</pre>

If a large number of MATLAB-jobs are run in parallel, they can also conflict when writing generic information to <syntaxhighlight style="border:0px" inline=1>~/.matlab</syntaxhighlight>. This can be circumvented by setting <syntaxhighlight style="border:0px" inline=1>$MATLAB_PREFDIR</syntaxhighlight> to different directories in your Batch-script, e.g.

<pre>export MATLAB_PREFDIR=$TMP</pre>

== Using a different implementation of BLAS/LAPACK ==

By default, Matlab uses a version of Intel MKL as its BLAS/LAPACK library. It is possible to manually change this to different libraries by setting the <syntaxhighlight style="border:0px" inline=1>BLAS_VERSION</syntaxhighlight> and <syntaxhighlight style="border:0px" inline=1>LAPACK_VERSION</syntaxhighlight> environment variables. The following lines can be added to the batch-script to change it, in this example to BLIS and Flame, which are optimized for AMD processors:

<pre>
module load numlib/aocl/3.2.0

export BLAS_VERSION=$AOCL_LIB_DIR/libblis-mt.so
export LAPACK_VERSION=$AOCL_LIB_DIR/libflame.so

export BLIS_NUM_THREADS=$SLURM_NTASKS
</pre>

This can increase performance depending on the task, for example large matrix multiplications, but caution is advised.

= General Performance Tips for MATLAB =

MATLAB data structures (arrays or matrices) are dynamic in size, i.e. MATLAB will automatically resize the structure on demand. Although this seems to be convenient, MATLAB continually needs to allocate a new chunk of memory and copy over the data to the new block of memory as the array or matrix grows in a loop. This may take a significant amount of extra time during execution of the program.

Code performance can often be drastically improved by pre-allocating memory for the final expected size of the array or matrix before actually starting the processing loop. In order to pre-allocate an array of strings, you can use MATLAB's build-in cell function. In order to pre-allocate an array or matrix of numbers, you can use MATLAB's build-in zeros function.

The performance benefit of pre-allocation is illustrated with the following example code.

<pre>
% prealloc.m

clear all;

num=10000000;

disp('Without pre-allocation:')
tic
for i=1:num
a(i)=i;
end
toc

disp('With pre-allocation:')
tic
b=zeros(1,num);
for i=1:num
b(i)=i;
end
toc
</pre>

On a compute node, the result may look like this:

<pre>
Without pre-allocation:
Elapsed time is 2.879446 seconds.
With pre-allocation:
Elapsed time is 0.097557 seconds.
</pre>

Please recognize that the code runs almost 30 times faster with pre-allocation.

== Compile MATLAB binaries with mcc ==

If you have a MATLAB license that includes [https://de.mathworks.com/products/compiler.html MATLAB Compiler], e.g. on your local computer, you can use <code>mcc</code> to create binaries from MATLAB code.
Stand-alone MATLAB programs compiled with <code>mcc</code> do not require any license tokens at runtime and you can start jobs in parallel without any risk of running out of licences.

=== Running compiled binaries with the MATLAB Runtime ===

If you do not have access to a full MATLAB installation on Helix, you can still run compiled MATLAB applications using the MATLAB Runtime module:

module load math/matlab-runtime
./my_compiled_app

The MATLAB Runtime requires no license. To use it:

# Compile your MATLAB code on a machine where you have a MATLAB license (e.g., your local workstation via an institute license):
#: <code>mcc -m my_script.m</code>
# Transfer the compiled binary to Helix.
# Load the matching Runtime module and run:
#: <code>module load math/matlab-runtime/R2025b</code>
#: <code>./my_script</code>

'''Important:''' The Runtime version must '''exactly''' match the MATLAB version used for compilation. For example, code compiled with R2023a requires <code>math/matlab-runtime/R2023a</code>. Available versions:

module avail math/matlab-runtime

Currently installed: R2022a, R2023a, R2023b, R2024a, R2024b, R2025a, R2025b.

The MATLAB Runtime is [https://de.mathworks.com/products/compiler/matlab-runtime.html freely available from MathWorks] and can also be installed locally if needed.

HPC Glossary/Batch system

2026-06-03T14:25:45Z

S Fischer: /* Resource Management Systems on bwHPC Clusters */

← This page is part of the [[HPC Glossary]]
----

When we speak of a '''batch system''' on compute clusters, we mean the system that knows which compute nodes are used by whom and when they will become available. It also knows about all waiting jobs and determines which job are going to start next on which node whenever a node bekomes available.

== Why do we need a Resource Management System? ==

An HPC cluster is a multi-user system. Users have compute jobs with different demands on number of processor cores, memory, disk space and run-time. Some users run a program only occasionally for a big task, other users must run many simulations to finish their projects.

The cluster only provides a limited number of compute resources with certain features. Free access for all users to all compute nodes without time limit will not work. Therefore we need a resource management system (batch system) for the scheduling and the distribution of compute jobs on suitable compute resources.
The use of a resource management system pursues several objectives:

* Fair distribution of resources among users
* Compute jobs should start as soon as possible
* Full load and efficient usage of all resources
[[image:distributing_jobs1.svg]]

== How does a Resource Management System work? ==
A resource management system or batch system manages the compute nodes, jobs and queues and basically consists of two components:

* A resource manager which is responsible for the node status and for the distribution of jobs over the compute nodes.
* workload manager (scheduler) which is in charge of job scheduling, job managing, job monitoring and job reporting.

A resource management system works as follows:

* The user creates a job script containing requests for compute resources and submits the script to the resource management system.
* The scheduler parses the job script for resource requests and determines where to run the job and how to schedule it.
* The scheduler delegates the job to the resource manager.
* The resource manager executes the job and communicates the status information to the scheduler.

== How does a Job Scheduler work?==

The job scheduling process is influenced by many and sometimes contrasting parameters which are used as metrics for the scheduling algorithm. The objectives of a resource management system are approached in the following way:

* Fair distribution of resources among users: Ensure that all users get a fair share of processing time for their jobs.
* Compute jobs should start as soon as possible: Minimize the time jobs have to wait until they start.
* Full load and efficient usage of all resources: Aim for the highest possible utilization with the available jobs, because cluster resources are very expensive

The following simple example illustrates how a scheduler works.
Let us consider a system with 4 nodes. Each node has 4 processor cores.

Here the cluster is empty. No jobs are scheduled:

[[image:Scheduling-workload0.svg]]

Now jobs with different resource requests are scheduled:

* one job which needs two nodes (blue)
* one job which needs one node (red)
* multiple jobs, which need only one core (yellow, orange)
* some jobs are short running, others are long running (see time axis)

[[image:Scheduling-workload1.svg]]

Up to now enough resources are available so that all jobs can start instantly.

More jobs are submitted. Now not all job can start immediately on the available hardware resources. Some jobs are scheduled to run at a later time.

* Big jobs (in terms of hardware resources) often have to wait longer, because they cannot be scheduled flexibly.
* Long running jobs can delay the scheduling of big jobs, because they block needed hardware resources.
* Small and short jobs can be scheduled to fill gaps.
* If a job stops prematurely, short jobs can be rescheduled to start earlier (back filling).

[[image:Scheduling-workload2.svg]]

In addition to cores and time a scheduler has to consider many more metrics like memory, co-processors, fair share, and priority. Scheduling is a multi-dimensional optimization problem.

== Resource Management Systems on bwHPC Clusters ==

Slurm: complete resource management system with integrated resource manager and scheduler

All bwHPC cluster follow a fairshare policy. The waiting time of jobs depends on:

* your job's resource requests: Jobs with large resource requests wait longer for free resources.
* your usage history: High resource usage in a short time leads to a lower job priority.
* your university's share (bwUniCluster only): If the usage exceeds the university's share, the job priority decreases.

bwHPC clusters have specific configurations for the resource management system concerning:

* Job submission and monitoring commands (via Slurm)
* Queues and limits for the available hardware
* Node access policy:
** shared: compute nodes can be shared by jobs of different users
** single user: compute nodes can be shared by jobs of a single user
** single job: compute nodes are allocated exclusively for a single job

FAQ: How many jobs can run on a single node at the same time?

This depends on the node access policy:

* On "shared nodes", more than one job can run simultaneously if the requested resources are available, and these jobs may have been submitted by different users.
* On "single user nodes", more than one job can run simultaneously, but the jobs have to be submitted by one and the same user
* On "single job nodes", the access is exclusive for one job, irrespective of the number of requested cores.

Energy Efficient Cluster Usage

2026-05-29T09:10:12Z

S Fischer: /* Summary: General Recommendations */

= Introduction =

Energy consumption of data centers has been increasing continuously throughout the last decade. In 2020, the energy consumption of all data centers in Germany amounted to around [https://www.bundestag.de/resource/blob/863850/423c11968fcb5c9995e9ef9090edf9e6/WD-8-070-21-pdf-data.pdf 3 percent] of the total electricity produced. Accompanying this large energy consumption are large-scale emissions of CO2 to the atmosphere and thus significant contributions to climate change.
To illustrate this, an average compute job running on a single node for one day may easily consume 10 kWh or even more. That translates roughly to brewing 700 cups of coffee.
Assuming that a typical bwHPC cluster has a few hundred compute nodes, this amounts to the energy consumption of a village for each cluster.

Although a large amount of this energy consumption is an intrinsic requirement of running large HPC clusters (even when it's processors are idle, a cluster uses a lot of energy), efficient use of the available resources is important. Using as many resources as possible does not make a power user. Using them wisely does.
In the following, a basic introduction to some of the most important aspects of energy-efficient HPC usage from a user perspective is given.

We can generally distinguish three tasks when optimizing for running HPC jobs efficiently.

→ What do I want to do and why do I need an HPC Cluster for it?

→ How many and which kind of hardware resources do I require for it?

→ How do I optimize my code to use these resources most efficiently?

= What do I want to do and why do I need an HPC Cluster for it? =

The bwHPC clusters are used to almost full capacity, and running a job on an HPC node consumes a lot of energy, as shown above.
Therefore, users are requested to run only necessary jobs.

Please consider testing new setups and their output for validity prior to submitting jobs that require lots of resources. This also includes projects where a lot of (smaller) similar jobs are submitted.

Make sure to double-check your jobs prior to the submission, as having to discard the output data of an HPC project due to faulty input files is wasting a lot of computational resources.

Finally, identifying the specific resource requirements for a given job is important to allocate the optimal amount for your compute job, and to decide if an HPC cluster is needed at all.

= How many and which kind of hardware resources do I require for it =

Resource allocation is a crucial part when working on an HPC cluster.
As this is dependent on both the job as well as the specific cluster hardware and architecture available.

'''
A small number of jobs and few resources'''

→ Submit to the scheduler. No extended testing and resource scaling analysis are needed.

'''
Medium-sized projects'''

→ Run only necessary jobs: Please consider testing new setups and their output for validity prior to submitting a huge amount of similar jobs

→ Start small: Run your problem on a small set of resources first.

→ Use the proper tools for development: If you develop your own code, please use the proper tools for debugging and parallel performance analysis. See: [[Development#Documentation_in_the_Wiki|Development]].

→ A look at the job feedback can help you determine if you are using the cluster efficiently

'''Large projects'''

→ Same approach as for medium-sized projects.

→ Run a scaling analysis for your project with regard to how many resources work best. See: [[Scaling]].

'''Many short jobs'''

→ Handling via the scheduler is inefficient.

→ Simple parallelization by hand is advisable. See: A basic introduction to [[Development/Parallel_Programming | Parallel Programming]].

= How do I optimize my code to use these resources most efficiently? =

The above recommendations will help use the cluster resources more efficiently.
Regarding software development, power efficiency correlates obviously heavily with '''computing performance''', but also with memory usage, i.e. the amount of memory used, but also memory efficiency.

Here, we have gathered a few results based on other research:
→ Use an efficient programming language such as Rust, C, and C++ -- well any compiled language. Do not use any interpreted language like Perl or Python. Since Machine Learning is a hot topic, this deserves a few words: Any ML-Python code using Tensorflow or other libraries will make heavy usage of NumPy and other math packages, which will use C-based implementations. Please make sure, you use the provided Python modules, which are optimized to use Intel MKL and other mathematical libraries.

Further reading:
Rui Pereira, et al: "''Energy efficiency across programming languages: how do energy, time, and memory relate?''", SLE 2017: Proc. of the 10th ACM SIGPLAN Int. Conf. on SW Language Eng., Oct. 2017, pp. 256–267, [https://doi.org/10.1145/3136014.3136031 doi:10.1145/3136014.3136031]

→ Analyse memory access patterns

→ For small tight loops checking for locks, use the <code>pause</code> instruction.

= Summary: General Recommendations =

* Choose the most '''efficient algorithms''' for the given problem.
* Run only '''necessary''' jobs: Please consider testing new setups and their output for validity prior to submitting a huge amount of similar jobs.
* Start '''small''': Run your problem on a small number of parallel entities (be it processes or threads) first.
* '''Estimate''' the runtime of the parallel job as '''exactly''' as possible to increase the efficiency of the scheduling of the whole system.
* Use the proper tools for development: If you develop your own code, please use the proper tools for debugging and parallel performance analysis. More information is available on the bwHPC Wiki.
* A look at the '''job feedback''' can help you determine if you are using the cluster efficiently.

BwUniCluster3.0/Jupyter

2026-05-04T12:25:13Z

S Fischer: fixed broken links

Jupyter can be used as an alternative to accessing HPC resources via SSH. For this purpose only a web browser is required. Within the website source code of different programming languages can be edited and executed. Furthermore different user interfaces and terminals are available.

= Short description of Jupyter =

Jupyter is a web application, central component of Jupyter is the '''Jupyter Notebook'''. It is a document, which can contain formatted text, executable code sections and (interactive) visualizations (image, sound, video, 3D views).

The Jupyter notebooks are executed in an interactive session on the compute nodes of the respective cluster. Access is via any modern web browser. Data is prepared and visualized on the server and therefore does not have to be transmitted over the network. Only the resulting text, image, sound and video data is transmitted. Starting point of a Jupyter session is the HOME directory of the user on the respective cluster.

'''JupyterLab''' is a modern user interface, within which one or more Jupyter notebooks can be opened, edited and executed. The individual notebooks can be arranged as tabs or tiled. JupyterLab is the standard user interface. Besides JupyterLab the classic notebook user interface is available, in which only one Jupyter notebook per browser tab can be opened at a time.

A '''Jupyter Kernel''' describes a separate process, in which one Jupyter Notebook is executed at a time. Different kernels are available for different programming languages or language versions.

Before a Jupyter session is started, the access authorization must be checked first. This is done via '''JupyterHub''', where the resources are selected, for example the number of CPU cores, GPUs or the required main memory.

A detailed documentation of the Jupyter project can be found at [https://jupyter.readthedocs.io https://jupyter.readthedocs.io].

= Access requirements =

{|style="background:#deffee; width:100%;"
|style="padding:5px; background:#cef2e0; text-align:left"|
[[Image:Attention.svg|center|25px]]
|style="padding:5px; background:#cef2e0; text-align:left"|
Access to Jupyter is '''limited to IP addresses from the BelWü network'''.
All home institutions of our current users are connected to BelWü, so if you are on your campus network (e.g. in your office or on the Campus WiFi) you should be able to connect to bwUniCluster 3.0 without restrictions.
If you are outside one of the BelWü networks (e.g. at home), a VPN connection to the home institution or a connection to an SSH jump host at the home institution must be established first.
|}

To use Jupyter on the HPC resources of SCC, the access requirements for [https://wiki.bwhpc.de/e/Registration/bwUniCluster bwUniCluster 3.0] apply. A [https://wiki.bwhpc.de/e/Registration/bwUniCluster registration] is required. Please note, You should've completed registration and tested your login once using [https://wiki.bwhpc.de/e/Registration/SSH Secure Shell (ssh)].

= Login process =

Login takes place at
* bwUniCluster 3.0: [https://uc3-jupyter.scc.kit.edu uc3-jupyter.scc.kit.edu]
* SDIL: [https://sdil-jupyter.scc.kit.edu sdil-jupyter.scc.kit.edu]
* HoreKa: [https://hk-jupyter.scc.kit.edu hk-jupyter.scc.kit.edu]
* HAICORE: [https://haicore-jupyter.scc.kit.edu haicore-jupyter.scc.kit.edu]

For login, your username, your password and a 2-factor authentication are required.

You will first find yourself on a landing page that also gives more information about the currently installed software versions.
By pressing the login button you will be redirected to the JupyterHub page. Click on Enter JupyterHub to start the login process. Select the organization (e.g. KIT) that has granted you access to the HPC system and press Continue. In the Login section that appears, enter your username and password (not the service password).
After pressing the Login button you will be redirected to the second factor query page. Enter the one-time password (e.g. from KIT Token or Google Authenticator App) and press Validate. Now you are done with the login process and can start selecting your computing resources.

[[File:Jupyter_Anmeldung.gif|700px]]

= Selection of the compute resources =

The Jupyter notebooks are executed in an interactive session on the compute nodes of the HPC clusters. Just like accessing an interactive session with SSH, resource allocation is done by the Workload Manager Slurm. The selection of resources for Jupyter is realized via drop-down menus. Only jobs with a maximum of one node are possible.

Available resources for selection are

* Number of CPU cores
* Number of GPUs
* Runtime
* Partition/Queue
* Amount of main memory

If Auto-Reservation is selected the automatic Jupyter reservation of the cluster is enabled.

In normal mode, the grayed-out fields contain reasonable presets, depending on the number of required CPU cores or GPUs respectively. The presets can be bypassed in advanced mode, where further options are available.

Advanced Mode can be activated by clicking on the checkbox of the same name. The following additional options then become available:

* Specification of a reservation
* LSDF mount option
* BEEOND mount option

After the selection is made, the interactive job is started with the spawn button. As when requesting interactive compute resources with the `salloc` command, waiting times may occur. These are usually the longer the larger the requested resources are.
Even if the chosen resources are available immediately, the spawning process may take up to one minute.

[[File:Ressources_neu.gif|500px]]

Please note that in advanced mode, resource combinations can be selected that are impossible to be met. In this case, an error message will appear when the job is spawned.

[[File:Jupyter_Falsche_ressourcen.gif|500px]]

The spawning timeout is currently set to 10 minutes. With a normal workload of the HPC facility, this time is usually sufficient to get interactive resources.

== Prioritized access to computing resources on bwUniCluster 3.0 ==
The use of Jupyter requires the immediate availability of computing resources since the JupyterLab server is started within an interactive Slurm session. To improve the availability of CPUs/GPUs for interactive supercomputing with Jupyter, '''automatic reservation''' for CPU (cpu_il) and GPU (gpu_a100_il) resources has been set up on '''bwUniCluster 3.0'''. It is active '''between 8am and 8pm''' every weekday. The reservation is automatically active if

* no other reservation is set manually
* Auto-Reservation is enabled

To give you a better overview of the currently available resources, a status indicator has been implemented. It appears when selecting the number of required CPUs/GPUs and shows whether a Jupyter job of the selected size can currently be started or not. Green means the selected CPU/GPU resources are available instantly. Yellow means only a single additional job of the selected size can be started. Red means there are no GPU resources left that could satisfy the selected amount of resources.

If there are no more resources available within the reservation, you can try selecting a different amount of CPUs/GPUs or activate Advanced Mode and select a different partition. Availability can be estimated using sinfo_t_idle, which is available when logging in via SSH.

= JupyterLab =

JupyterLab is the standard user interface. In the following only its essential functions are briefly introduced. A detailed documentation is available at
[https://jupyterlab.readthedocs.io https://jupyterlab.readthedocs.io].

== Menu bar ==

The menu bar at the upper edge of JupyterLab has higher-level menus that display the actions available in JupyterLab along with their shortcut keys. The default menus are:

* File: Actions related to files and directories
* Edit: Actions related to editing documents and other activities
* View: actions that change the appearance of JupyterLab
* Run: Actions to execute code in various activities like notebooks and code consoles
* Kernel: Actions to manage kernels that are separate processes for executing code
* Tabs: a list of open documents and activities in the Dock Panel
* Settings: general settings and an editor for advanced settings
* Help: a list of help links to JupyterLab and the kernel

== Left sidebar ==

In the left sidebar there are foldable tabs. The most relevant ones are:

* File browser: Switch to directories and open files with left mouse button, context menu with right mouse button
* Running kernels: Overview of running kernels
* Command overview
* Tab Overview
* Lmod software selection: Search and load/unload Lmod software modules

== Main working area ==
The main working area in JupyterLab allows to arrange, resize and divide documents (notebooks, text files, etc.) and other activities (terminals, code consoles, etc.) in tabs. By holding down the left mouse button, the tabs can be grabbed and repositioned.

In a new JupyterLab session the Launcher tab is opened first. It contains buttons for starting new notebooks, code consoles and other functions. When a notebook is open, a new Launcher tab can be started by pressing the plus symbol in the file browser tab of the left sidebar, by calling ''File > New Launcher'' in the upper menu bar or by the key combination ''Ctrl+Shift+L''.

== Classic Notebook ==

The classic Jupyter Notebook user interface offers only one open Jupyter Notebook or terminal per browser tab. From the JupyterLab user interface the classic display can be reached in the menu bar under ''Help > Launch Classic Notebook''. Clicking on the JupyterHub logo in the upper left corner will take you back to the JupyterLab interface.

= Log out =

You can log out from a running Jupyter session by calling ''File > Log Out'' in the upper menu bar.

{| style="width: 100%; margin:4px 0 0 0; background:none; border-spacing: 0px;"
| style="width:100%; border:1px solid #BBBBBB; background:#fff5fa; vertical-align:top; color:#000;" |
{| style="width:100%; vertical-align:top; border:0px solid #BBBBBB; padding:4px;" |
|-
|{{Red}}| Attention
|-
|
Please note that your interactive session will continue in the background!

|}
|}

As long as the interactive session is running, you can re-enter it at any time. Depending on the duration of your absence, it may be necessary to re-enter your one-time password and possibly KIT password.

If you want to end the interactive session before it has reached its runtime, you can do so via the Hub Control Panel. Under ''File > Hub Control Panel'' in the upper menu bar, it is opened in a new browser tab. By pressing the ''Stop My Server'' button the session will be terminated. You can now log out using the ''Logout'' button in the upper right corner or start a new session directly using the ''Start My Server'' button, for example with a changed resource selection.

[[File:logout_small.gif|750px]]

= Selection of software =

For the selection of the required Lmod software modules the corresponding tab ''Softwares'' is available in the left sidebar. The list of available modules can be narrowed down by entering the search field. The desired module is loaded by pressing the ''Load'' button. In the list with the loaded modules you can remove them with the ''Unload'' button.

{| style="width: 100%; margin:4px 0 0 0; background:none; border-spacing: 0px;"
| style="width:100%; border:1px solid #BBBBBB; background:#f5fffa; vertical-align:top; color:#000;" |
{| style="width:100%; vertical-align:top; border:0px solid #BBBBBB; padding:4px;" |
|-
|{{Green}}| Note
|-
|
On already opened Jupyter Notebooks, newly loaded software modules become active only after restarting the kernel (''Kernel > Restart Kernel'' in the upper menu bar). Terminals must be closed and reopened.
|}
|}

[[File:software_small.gif|750px]]

== Software Stacks for Jupyter ==
Currently 3 special Jupyter software stacks are available via Lmod:

* <code>jupyter/minimal</code>
*: Minimal installation of JupyterLab

* <code>jupyter/base</code>
*: Basic installation of JupyterLab.
*: For a complete list of pre-installed packages, please refer to [https://uc3-jupyter.scc.kit.edu/software-modules/#pre-installed-software-packages this site].

* <code>jupyter/tensorflow</code> (default at login, will be deprecated with the advent of bwUniCluster 3.0)
*: Preinstalled software packages for machine learning applications. Includes among others TensorFlow, Keras, Torch, Pandas, Matplotlib, SKLearn.
*: For a complete list of pre-installed packages and their respective version, please refer to [https://uc3-jupyter.scc.kit.edu/software-modules/#pre-installed-software-packages this site].

* <code>jupyter/ai</code> (will be the new default at login für bwUniCluster 3.0, contains all latest and greatest software for AI workflows)
*: Preinstalled software packages for machine learning applications. Includes among others TensorFlow, Keras, Torch, Torchvision, Lighning, Pandas, Matplotlib, SKLearn.
*: For a complete list of pre-installed packages and their respective version, please refer to [https://uc3-jupyter.scc.kit.edu/software-modules/#pre-installed-software-packages this site].

* <code>jupyter/extensions</code>
*: Same packages as tensorflow + extensions

These software stacks can be used both when accessing the cluster via JupyterHub, as well as for conventional access via SSH via module load.

A continuously updated list with the installed packages can be found on the corresponding subpage of the respective cluster:

* bwUniCluster 3.0: [https://uc3-jupyter.scc.kit.edu/software-modules uc3-jupyter.scc.kit.edu/software-modules]
* HoreKa: [https://hk-jupyter.scc.kit.edu/software-modules hk-jupyter.scc.kit.edu/software-modules]

= Installation of further software =
The software provided by the Lmod modules jupyter/minimal, jupyter/base and jupyter/tensorflow can be easily supplemented by additional Python packages. There are 2 procedures for this.

<ul>
<li>User-Installation (not recommended) 
<code>pip install --user <packageName> </code> 
The additional packages are installed under $HOME/.local/lib/python3.11/site-packages/ which is part of PYTHONPATH.
</li>
<li>Virtual environments (recommended) 
The user can create and use virtual environments (cf. Virtual environments). Packages provided by the jupyter Lmod modules remain visible and usable.
</li>
</ul>

== Virtual environments ==

Python virtual environments allow to use different versions of a package and to keep your local site-packages (accessible under <code>$PYTHONPATH</code>) free from conflicts.

=== Creation of virtual environment ===

<pre>
python -m venv <myEnv>
source <myEnv>/bin/activate
pip install <packageName>
deactivate
</pre>

The additional packages are installed under <code><myEnv>/lib/python3.11/site-packages/</code>.

=== Usage of virtual environment ===

In order to use the virtual environment, it has to be activated via <code>source <myEnv>/bin/activate</code>. <code>PYTHONPATH</code> is set accordingly. Deactivation of the venv is done via <code>deactivate</code>.

=== Usage of virtual environment in JupyterLab ===

To be able to use the virtual environments within JupyterLab, a corresponding kernel has to be installed:

<pre>
source <myEnv>/bin/activate
python -m ipykernel install \
--user \
--name myEnv \
--display-name "Python (myEnv)"
</pre>

After installing the kernel (and possibly refreshing the browser window), a button named "myEnv" is available in JupyterLab. The kernel can also be selected from the drop-down menu.

'''Attention'''
The (Lmod) base module you used in the Creation of virtual environment step must be loaded to use the venv. However, to be on the safe side, you can also use the system Python (<code>/usr/bin/python3.11</code>) at creation time, which is available even without any <code>jupyter/{base,tensorflow}</code> module loaded.

== Examples on Data processing, Machine Learning & Visualization ==

In the [https://github.com/hpcraink/workshop-parallel-jupyter/ workshop repository] the usage and best practices on Python in general, and the packages NumPy, Pandas, SciKit and Dask are provided, containing running examples based on open data. It also explains, how Jupyter interacts with pre-installed and your own provided environments.

== R language ==

In order to use R language in JupyterLab, the Lmod module <code>math/R</code> has to be loaded (blue button in JupyterLab or <code>module add math/R</code> in terminal) and a corresponding kernel has to be installed.

<pre>
R
install.packages('IRkernel')
IRkernel::installspec()
</pre>

After installing the kernel , a button named "R" is available in JupyterLab. The kernel can also be selected from the drop-down menu.

'''Attention:'''
Don't forget to load the <code>math/R</code> module (blue button) before using the kernel.

== Julia language ==

In order to use Julia language in JupyterLab, the Lmod module <code>math/julia/1.10.8</code> has to be loaded (blue button in JupyterLab or <code>module math/julia/1.10.8</code> in terminal). When the module is loaded from the JupytherLab UI, the corresponding kernel will be installed. If you use the terminal, this has to be done manually

<pre>
julia
]
add IJulia
</pre>

After installing the kernel, a button named "Julia 1.10.8" is available in JupyterLab. The kernel can also be selected from the drop-down menu.

'''Attention:'''
Don't forget to load the <code>math/julia/1.10.8</code> module (blue button) before using the kernel.

= Jupyter Container Mode =

The container integration on the jupyterhub is done via pyxis. In order to use it the checkmark for container mode has to be clicked. Available options are:

* <code> --container-image:</code> The container image to use. Corresponds to the pyxis option --container-image
* <code> --container-name:</code> The name of the image to use. Corresponds to the pyxis option --container-name. Already downloaded containers in ~/.local/share/enroot can be startet by simply specifing their name.
* <code> --container-mount-home:</code> Corresponds to the pyxis option --container-mount-home. Mounts the home-directory

'''Attention:'''
Make sure Python3.11 and pip are installed in the Container or the notebook will not spawn. This can be checked via command python3.11 -m pip list inside your container

It is advised to create the container prior via e.G. enroot and install all necessary software. For more information see [https://wiki.bwhpc.de/e/BwUniCluster2.0/Containers#SLURM_Integration here]

----