Environment variables

sisl understands some environment variables that may be used to tweak, or change the default behaviour of sisl.

Here we list the different options:

SISL_NUM_PROCS = 1

Default the number of processors used in parallel calculations. Currently only certain Brillouin zone operations has this enabled.

Please test this for your machine before relying on it giving a lot of performance. Especially in conjunction with the OMP_NUM_THREADS flag for OpenMP in linear algebra libraries. Benchmark and see if it actually improves (certain combinations will severly hurt performance, while others will greatly improve performance). This value together with OMP_NUM_THREADS and SISL_PAR_CHUNKSIZE should be tuned for your case study.

It is very easy to encounter deadlocks when using parallel processing in sisl. The main problem is the interplay between the BLAS library and the threading in the multiprocessing library. Always try first by maximizing SISL_NUM_PROCS and set OMP_NUM_THREADS=1 to test whether it works on your machine, then further tuning can be done by ensuring that SISL_NUM_PROCS * OMP_NUM_THREADS <= CORES.

Generally one can get the maximum number of cores by:

import os
nprocs = len(os.sched_getaffinity(0))
# If your CPU has hyper-threads, then you have to divide by 2:
nprocs = nprocs // 2

SISL_PAR_CHUNKSIZE = 0.2

Default size of chunk for each processor when running parallel things.

The chunksize can be an int, in which case it is directly determining the chunksize. If it is a float, it is understood as the fraction of chunks each processor will get, so a chunksize of 0.5 means that each processor gets 2 chunks (the actual chunksize will be adjusted depending on the number of iterations). For 0.1, it results in 10 chunks per processor.

When doing parallel jobs the chunksize can greatly improve efficiency. For example a chunksize of 1 and 2 processors for a brillouinzone object means an execution like this:

<initialization>
proc-0: k[0]
proc-1: k[1]
<collection of results>
proc-0: k[2]
proc-1: k[3]
<collection of results>
...

With a chunksize of 2 it will look like:

<initialization>
proc-0: k[0]
proc-0: k[1]
proc-1: k[2]
proc-1: k[3]
<collection of results>
...

this can greatly improve performance, however, a too high chunksize can hurt performance, as well as a too low. A rule-of-thumb would be to select a chunksize such that the number of iterations is divisible by the chunksize. For BrillouinZone objects, the number of iterations is equivalent to the number of k-points.

SISL_SHOW_PROGRESS = false

Certain sisl routines has a builtin progress bar. This variable can default whether or not those will be shown. It can be nice for slow brillouinzone calculations to see if progress is actually being made.

SISL_IO_DEFAULT = ''

The default IO methods sisl.get_sile will select files with this file-endings. For instance there are many stdout file types (for each DFT code). Setting this to Siesta would force all files to first search for classes ending in Siesta (see sisl.io for class names).

SISL_TMP = '.sisl_tmp'

certain internal methods of sisl will use a temporary folder for storing data. The default is a new folder in the currently executed directory.

SISL_FILES_TESTS

Full path to a folder containing tests files. Primarily used for developers.

This can be used like this:

git clone -b stripped --single-branch https://github.com/zerothi/sisl-files.git
SISL_FILES_TESTS=$(pwd)/sisl-files pytest --pyargs sisl

SISL_CONFIGDIR = $HOME/.config/sisl

where certain configuration files should be stored.

Currently not in use.

SISL_LOG_FILE

if provided sisl will log to the provided file.

SISL_LOG_LEVEL = "info"

the log-level used if writing to a log-file. The value will be taken from the logging module, so it should be a variable in that module.

Code specific environment variables

Siesta

SISL_UNIT_SIESTA = codata2018 | legacy

determine the default units for Siesta files.

Since Siesta 5.0, the default units are updated to follow the CODATA 2018 values. This means that quite a bit of results changed. This will force the internal variables to be consistent with this.