Installation

Requirements

Quick setup

Start by cloning the git-repository

cd ~/path/to/somewhere
git clone git@gitlab.com:materials-modeling/storq.git

Next you can either proceed to do a standard install via pip

or by manually adding the paths storq and its associated binaries to your .bashrc file

export PYTHONPATH=$PYTHONPATH:~/path/to/somewhere/storq
export PATH=$PATH:~/path/to/somewhere/storq/bin

Next you need to generate a configuration file. Storq comes with a command line tool that can do the bulk of the configuration for you. To initiate the automatic configuration run

The configuration process will alert you as to any settings which could not be automatically detected and hence need to be set manually. Note that some settings are optional, in which case only a warning is issued while others are critical for the operation of storq and are hence marked as “fatal”. Note that it is not uncommon that the automatic setup fails to find the binaries and POTCARs since it can be hard to search for many different names across potentially more than one filesystem. In particular for the POTCARs, storq needs a folder which contains subfolders named potpaw_ABC, where ABC=PBE, LDA, GGA, which must hold the coresponding POTCAR files. Naturally, if you only wish to use the PBE setups, only potpaw_PBE needs to exist.

Once you have completed the automatic configuration (and addressed any of its complaints) it might be necessary to set your mpi run-command in order to be able to run calculations. This is the case if your supercomputing resource uses a wrapped version of the default mpirun command (e.g. mpprun on NSC’s triolith<https://www.nsc.liu.se/systems/triolith/> or aprun on PDC’s beskow<https://www.pdc.kth.se/hpc-services/computing-systems/beskow-1.737436>). To change this option access the json configuration file through

and change the value of the mpi_command field to an appropriate command. It can furthermore be convenient to add a default allocation for your jobs to run on (you can override this later from your ASE script). To select an allocation, edit the value of the batch_account field to the name of your account (e.g. “snic20XX-X-XX” on a SNIC resource).

More about configuring storq

This section contains a more thorough description about the configuration process and what options are available.

The VASP configuration file and its options

The automatic configuration process will generate two configuration files named vasp.json and site.json and place them under ~/.config/storq. You can access and edit these at any time using the commands (beware that the files will be opened in the editor pointed to by your $EDITOR environmental variable and that if this is not set the default is vi)

The generation of the site.json file should be completely automatic, the file itself contains information about how the cluster environment is set up (e.g. the number of cores per node). The vasp.json file tells storq where to find VASP binarie, pseudopotentials etc. and controls the general behaviour of the calculator. All settings found in this file can be overridden from python but in practice only a few settings (walltime, number of nodes etc.) need to be changed from script to script. To access and change the storq configurations from within python use the Vasp.configure(key=value) method.

Below is a list of all currently availabe options for vasp.json and a basic summary of their effects.

  • vasp_mode: “queue” or “run”, should we run jobs directly or submit through queue.
  • mpi_command:
  • mpi_options: null
  • vasp_executable_std: Path to the standard VASP executable
  • vasp_executable_gam: Path to the special Gamma-point only VASP executable
  • vasp_executable_ncl: Path to the special Non-collinear VASP executable
  • vasp_potentials: Path to potpaw_ABC folders containing POTCARs where ABC=PBE,LDA,GGA
  • vasp_vdw_kernel: Path to the vdw_kernel.bindat file need to use the vdW-DF functionals.
  • user: Your username on the supercomputing resource.
  • batch_account: Your allocation on the supercomputing resource.
  • batch_options: A space-separated string of extra options passed to the sbatch command
  • batch_walltime: The walltime of your job passed a string HH:MM:SS
  • batch_nodes: The number of nodes used for your calculation
  • vasp_convergence: “basic” or “strict”, sets the strictness level of the calculators convergence checks.
  • vasp_restart_on: “convergence”,
  • vasp_stdout: Name of the file which VASP’s stdout gets written to, typically vasp.out.
  • vasp_validate: whether keywords passed to the calculator should be type checked (true or false)

A note on working with multiple filesystems

Many supercomputing resources feature multiple file systems, a common setup is having one distrubuted system and one parallel system (e.g. Lustre<lustre.org>). In this case one needs to be careful when settings up Storq and make sure that the necessary files are visible across the file systems or alternatively, located on the same file system. As a concrete example, consider PDC’s beskow<https://www.pdc.kth.se/hpc-services/computing-systems/beskow-1.737436> which uses a distributed file system called AFS as well as a parallel Lustre system. The supercomputing centre recommends installing software on Lustre, but the users’ home folders reside in AFS. Hence, even if Storq is installed on Lustre, the automatic configuration process will place the configuration files under $HOME on AFS. To resolve this situation one can move the .config folder to Lustre and place a symlink in AFS which points to the new location. Arguably, in this case a better option is to keep the .config folder on AFS but move it from $HOME to a subfolder $HOME/Public that is set to be visible from Lustre and then place a symlink in $HOME.