• Requirements
  • Static codes (st-wslda)
  • Time-dependent codes (td-wslda)
• Downloading the Toolkit
• Compiling Standard Libraries and Tools (Optional)
• Setting Up Templates
• Testing Templates and Execution
  • Compilation Test
  • Execution Test
  • Example
• Creating Machine Templates
• Making the Toolkit Accessible to Other Users (Optional)
• Updating of the toolkit
• Installation Examples

Requirements

Static codes (st-wslda)

• C compiler (e.g., gcc, Intel compiler icc, etc.)
• MPI C compiler (e.g., mpicc, Intel compiler mpiicc, etc.)
• Python
• FFTW library
• LAPACK library
• ScaLAPACK library
• ELPA library (optional)
• CUDA compiler (optional, for ELPA)

Note 1: Compilers and core libraries (FFTW, LAPACK, ScaLAPACK) are typically installed by default on most computing clusters. If the system is equipped with GPUs, the CUDA Toolkit is usually available as well. ELPA is also installed on many systems; if not, it can be compiled manually.

Note 2: LAPACK and ScaLAPACK are included in the Intel® Math Kernel Library (MKL).

Note 3: It is strongly recommended to use st-wslda with ELPA support whenever possible, as it significantly accelerates diagonalization. See the ELPA installation guide for details.

Time-dependent codes (td-wslda)

• C compiler (e.g., gcc, Intel compiler icc, etc.)
• MPI C compiler (e.g., mpicc, Intel compiler mpiicc, etc.)
• CUDA compiler
• Python

Note 1: Time-dependent codes require GPU-accelerated systems. td-wslda cannot run on CPU-only systems.

Downloading the Toolkit

The recommended way to obtain the toolkit is via git:

git clone https://gitlab.fizyka.pw.edu.pl/wtools/wslda.git

Alternatively, you may use mirror repositories:
GitLab or GitHub.

The toolkit resides in the wslda directory. See the folder structure description for details.

After cloning, define the global environment variable:

export WSLDA=path_to_wslda_folder

It is recommended to place this command in your shell configuration file (e.g., .bashrc).

To use the toolkit with AMD ROCm, you need to hipify the code. Follow the instructions provided on this page.

Compiling Standard Libraries and Tools (Optional)

The toolkit includes several auxiliary libraries and tools that support computation and data processing. See Auxiliary tools for details. Although optional, compiling them during installation is recommended.

To compile, ensure that both a C compiler and an MPI C compiler are available. Specify them in the header of install-libs.sh:

export CC="gcc -std=gnu99"
export MPICPP="mpic++ -std=gnu99"

Some libraries require FFTW. Ensure it is installed before compilation.

To build all libraries:

./install-libs.sh

After completion, the script provides instructions for setting environment variables, for example:

export WSLDA=/path/to/wslda
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/path/to/wslda/lib/wdata:/path/to/wslda/lib/wderiv:/path/to/wslda/lib/winterp:/path/to/wslda/lib/wbox
export PATH=$PATH:/path/to/wslda/lib/wdata/bin:/path/to/wslda/tools/bin

Share these export statements with other users if the toolkit is installed in a shared location. Ensure that the wslda directory is readable by all intended users.

Each library is compiled via make in its respective directory. For example:

make -C lib/wdata

If compilation fails, enter the relevant directory and adjust the Makefile accordingly.

Setting Up Templates

W-SLDA follows a template-based workflow.

Templates are located in:

• st-project-template -- static problems (st)
• td-project-template -- time-dependent problems (td)

A template folder should contain:

Name	Requirement	Dependency	Description
Makefile	Mandatory	Machine-dependent	Compiler settings and flags
machine.h	Mandatory	Machine-dependent	Machine configuration (diagonalization engine, GPUs per node, etc.)
README.md	Optional	Machine-dependent	User instructions
env.sh	Optional	Machine-dependent	Environment setup script
job.sh	Optional	Machine-dependent	Example submission script
input.txt	Mandatory	Problem-dependent	Default input file
predefines.h	Mandatory	Problem-dependent	Compiler predefinitions
problem-definition.h	Mandatory	Problem-dependent	Problem definition
logger.h	Mandatory	Problem-dependent	Logging configuration

At minimum, Makefile and machine.h must be adapted to your system.

Machine-specific examples are available in the templates directory.

If your system is listed, use:

./install-templates.py system_name

This script copies appropriate files into the template directories.

Testing Templates and Execution

Compilation Test

Copy a test project to a temporary directory:

cd ~/tmp
cp -r $WSLDA/st-testcase-uniform/ .
cd st-testcase-uniform/
make

Successful compilation produces executables such as st-wslda-?d, where ? is 1, 2, or 3 and indicates the code dimensionality.

If compilation fails: Check environment variables. Verify Makefile and machine.h.

Notes:

1. Enable ELPA in machine.h if available.
2. Some systems require -DFORTRAN_NO_UNDERSCORE in CFLAGS.
3. Additional architecture-specific settings may be required in machine.h.
4. To compile the toolkit with AMD ROCm, follow the instructions provided on this page.

It is recommended to use a dedicated env.sh file for module loading:

module load ...
export LD_LIBRARY_PATH=...
module list

Then compile with:

source ./env.sh
make

Repeat the procedure analogously for td templates.

Execution Test

The toolkit provides two reference test cases that verify both correctness of implementation and proper configuration of the computational environment.

• st-testcase-uniform: This test solves the uniform system in the static (self-consistent) mode. The self-consistent loop is initialized using analytical expressions derived from BCS theory for a uniform Fermi gas. The initial guess corresponds to the exact solution of the uniform problem. Since the initial state is already the correct solution, the self-consistent procedure should converge immediately. This means that only a single iteration should be performed, and the code should conclude with ALGORITHM CONVERGED.
• td-testcase-uniform: This test evolves in time the same uniform solution, but now using the time-dependent solver. The initial state provided to the code is a stationary solution of the time-dependent equations. Therefore, it should remain unchanged during time evolution. All quantities (e.g., total energy, contributions to the energy, particle number) must remain constant within numerical precision. Observables printed to the screen and to the files should not exhibit time-dependence.

Together, these two tests verify: 1. Correct static self-consistency implementation. 2. Proper time-dependent propagation. 3. Consistency between static and time-dependent solvers. 4. Correct linkage of numerical libraries and GPU backends.

Example

mpirun -np 4 ./st-wslda-2d input.txt

Full test workflow:

# Static
cd st-testcase-uniform
source env.sh
make
mpirun -np 4 ./st-wslda-1d input.txt > st-test-1d.txt
mpirun -np 4 ./st-wslda-2d input.txt > st-test-2d.txt
mpirun -np 4 ./st-wslda-3d input.txt > st-test-3d.txt

cd td-testcase-uniform
source env.sh
make
mpirun -np 4 ./td-wslda-1d input.txt > td-test-1d.txt
mpirun -np 4 ./td-wslda-2d input.txt > td-test-2d.txt
mpirun -np 4 ./td-wslda-3d input.txt > td-test-3d.txt

Examples of outputs are (note they may change with the version change):

• st-test-1d.txt
• st-test-2d.txt
• st-test-3d.txt
• td-test-1d.txt
• td-test-2d.txt
• td-test-3d.txt

Creating Machine Templates

After successful testing, create a machine-specific template:

mkdir -p $WSLDA/templates/computer_name/st
mkdir -p $WSLDA/templates/computer_name/td

Copy relevant files:

cp Makefile README.md env.sh job.sh $WSLDA/templates/computer_name/st
cp Makefile README.md env.sh job.sh $WSLDA/templates/computer_name/td
cp machine.h $WSLDA/templates/computer_name/

machine.h must be shared between static and time-dependent configurations.

Go to the main folder of the toolkit and propagate templates to the project template folders

cd $WSLDA
./install-templates.py computer_name

We encourage submitting new machine templates to the W-SLDA developers for inclusion in the codebase.

Making the Toolkit Accessible to Other Users (Optional)

Ensure the wslda directory is readable:

chmod -R a+r wslda

Provide users with the required environment variables:

export WSLDA=/project/path/wslda
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/project/path/wslda/lib/wdata:/project/path/wslda/lib/wderiv:/project/path/wslda/lib/winterp:/path/to/wslda/lib/wbox
export PATH=$PATH:/project/path/wslda/lib/wdata/bin:/project/path/wslda/tools/bin

Updating of the toolkit

If a new version is released, the simplest option is to update your repository

cd $WSLDA
git pull
cat VERSION.h

This operation should update the engine files while keeping machine-dependent files (such as Makefile or machine.h) unchanged.

Installation Examples

• Eagle system (PCSS, Poland)
• Kamiak system (WSU)