Advanced Configuration and Remote Execution

Advanced Configuration and Remote Execution#

In this section, we provide a detailed explanation of how to configure ASAP to run simulations (local or remote) using one of the supported programs. ASAP supports SIESTA (TranSIESTA) versions 4.1, 5.0 and 5.2, and Quantum Espresso version 6.x and 7.x.
Fig. 1 shows schematically the steps you need to complete depending on your needs. The process has to be done only once for each combination of requirements.
Install SIESTA

Fig. 1 Scheme illustrating the steps to set up the calculator. For local simulations, Step 2 can be omitted.#

This chapter of the manual also includes three annexes to help complete the setup process and provide additional guidance.

Step 1: Install the program (SIESTA, TranSIESTA, Quantum ESPRESSO)#

Each of these programs can be installed in serial modes (the program runs on a single processor, executing tasks sequentially) or parallel mode (the program distributes tasks across multiple processors, allowing simultaneous execution of different parts of the computation, significantly speeding up large-scale simulations).

SIESTA version 4.1#

We recommend you to use the embedded SIESTA executable provided by ASAP as explained in chapter Quick Start Guide.
You can also download the binary for your operating system from our webpage at https://www.simuneatomistics.com/siesta-toolkit/siesta-binaries.

SIESTA version 5.x#

As for SIESTA 4.1, we recommend you to use the embedded SIESTA installexecutable provided by ASAP as explained in chapter Quick Start Guide.
If you want to install it yourself and your operative system is Linux or MacOS, we recommend to use Anaconda or Miniconda. For a step by step guide please check Section Annex 1: Install SIESTA and Quantum ESPRESSO using Miniconda.
Notice that from SIESTA 5.0 onwards, TranSIESTA is integrated within the SIESTA package and does not require separate installation.
If you plan to run simulations in parallel mode, in addition to installing the necessary program (e.g., SIESTA, TranSIESTA, Quantum ESPRESSO), you must also install the required parallel libraries for your operating system. These libraries enable communication between processors and ensure efficient use of system resources during parallel execution. Check Section Annex 2: Install parallel libraries if you want to know how to install them on Windows and Linux.

Quantum ESPRESSO version 7.4#

We recommend you to use the embedded Quantum ESPRESSO executable provided by ASAP as explained in chapter Quick Start Guide.
If you want to install it yourself and your operative system is Linux or MacOS, we recommend to use Anaconda or Miniconda. For a step by step guide please check Section Annex 1: Install SIESTA and Quantum ESPRESSO using Miniconda.

Step 2: Set up ASAP for remote computing#

Connect ASAP to a remote machine#

The connection of ASAP to a remote machine has to be done only once for each remote server and is not necessary for local simulations. If you plan to run locally, you can skip this step.
To run simulations with ASAP on a remote server, ensure first that the remote environment meets the necessary requirements. See Section Annex 3: Configure remote server for details.
Once the requirements are met, click the Configure Runner button to set up ASAP for remote computing.
Advanced guide configure runners
It will open the configuration runners widget, as shown in Fig. 2.
Advanced guide configure runners

Fig. 2 Configuration runner widget.#

  • New remote…. To open the configuration widget containing a form that allows you to configure remote connections to clusters or servers for remote computing

  • New program…. To configure an executable on the remote server. See subsection Step 3: Set up the program.

  • Edit…. To edit a previously configured remote machine.

  • Delete. To delete a previously configured remote connection.

  • Copy. To copy a previously created remote configuration.

Click on the New remote… button to open the remote configuration widget. This widget contains a form that allows you to configure remote connections to clusters or servers for remote computing, as shown in Fig. 3.
../_images/runners-resources-remote-machine.png

Fig. 3 Remote configuration widget. You can set up your remote machine here.#

The first four fields define the required parameters to establish the connection to a remote server/cluster.

  • Name: Name of the remote connection, up to the user preferences.

  • Hostname: IP address of the remote server.

  • Username: Username of the user in the remote server.

  • Port: To adjust the network port used to connect through SSH. At present, this field must be non-empty.

The remaining fields define additional settings related to the remote execution environment, connection behavior, and Python configuration.

  • Timeout: To setup the network timeout. At present, this field must be non-empty.

  • Required password at connection time: If checked the user is required to input the remote server password in order to connect.

  • Python: Tells ASAP where to find the python interpreter.

  • Remote RC command: Tell ASAP how to set the remote environment appropriately before running simulations. Please follow the recommendations described in section Install Python package on the remote server.

  • Remote workspace: Workspace to use for the simulations on the remote server. If no absolute path is given, the remote workspace will be considered relative to the remote user home directory.

Click the Check this configuration button to test the connection to the server using the selected Python environment.
Install SIESTA

Step 3: Set up the program#

This widget is used to specify essential details about the simulation code, including its name and path on the local or remote machine. This configuration is required for both local and remote runs.
Click on the “New program…” button to open the “Program” widget.
Advanced guide configure runners new program
../_images/runners-resources-new-program.png

Fig. 4 Widget to configure the runner on the local or on a remote machine.#

Here, we list the options of the Program widget:

  • Name: Name of the program.

  • Executable: Executable program path on the local or remote machine.

  • Program Type: Two drop-down menus that allow you to select the program and its version. There are three available options: SIESTA, TranSIESTA and TBtrans (see Fig. 5).

  • MPI executable: MPI executable path on the local or remote machine.

  • … options: Use this field to include any additional commands not mentioned above but supported by the selected batch scheduler vendor.

  • Recomm. num. procs.: Default number of processors suggested by ASAP for this program.

  • Test program: Click this button to test the program.

If you run the check to test the program you should see the following message
Runners resources users queue
At this step, you can also specify whether the code will run directly or in a queue. When run locally, the calculator is always executed directly by ASAP, while on remote machines it can be executed either directly or through a batch scheduler. In the latter case, you can easily configure the Batch Scheduler parameters, which are the settings that control how jobs are managed and executed in a queue.
Select New/Edit queue to open the Batch Scheduler Configuration widget.
../_images/runners-resources-new-queue.png

Fig. 5 Batch Scheduler Configuration Widget#

It contains a form that will allow you configure the Batch Scheduler parameters.
The Batch Scheduler Configuration widget offers the option to tune the batch schedule vendor. ASAP supports Portable Batch System and Torque (PBS/TORQUE), Slurm Workload Manager (SLURM) and IBM Spectrum (LSF).
Runners resources batch schedule vendor
You can use fixed queue parameters. In this case, ASAP offers empty fields for the user to fill in, and then generates the submission script based on the selected batch scheduler.
Runners resources fixed queue

  • Configuration label: The name of Batch Scheduler Configuration.

  • Job name prefix: A word, letter or number to be placed before the identification number of the job. You can edit this prefix at your convenience.

  • Number of nodes: The number of nodes in a job.

  • Number of processors per node: How many processors are reserved for each node.

  • Batch queue: Queue name.

  • Maximum memory: Maximum required memory for the job.

  • Maximum CPU time: Maximum CPU time per node.

  • Maximum walltime: Maximum number of hours you want to run your job.

  • Notification email: User email specification.

Alternatively, you can select the option User’s queue script. This allows you to fully customize the job submission script.
Runners resources users queue
Once the configuration is complete, click the OK button to close the remote configuration widget.

Annex 1: Install SIESTA and Quantum ESPRESSO using Miniconda#

Download and install Miniconda#

If you already have Anaconda or Miniconda installed you can skip this step.
Follow the instructions at https://www.anaconda.com/docs/getting-started/miniconda/install#macos-linux-installation to install Miniconda for your operating system.

Create and activate a Conda Python environment for SIESTA#

Once Miniconda is installed, create a new environment for SIESTA by running the following command in your terminal,
conda create -n py311 python=3.11
Activate the newly created environment by running,
conda activate py311

Install SIESTA & TranSIESTA 5.2#

To install the serial version of SIESTA 5.2, use the following command:
conda install -c conda-forge siesta
If you require the parallel version of SIESTA (recommended when you need to perform computationally intensive simulations that can benefit from running on multiple processors simultaneously), you need to install before the scalapack package (high-performance linear algebra library for parallel distributed memory machines),
conda install conda-forge::scalapack
Afterwards, to install parallel version of SIESTA, type the following command:
conda install -c conda-forge "siesta=5.2=*openmpi*"
Alternatively, you can use the MPICH library for the same purpose:
conda install -c conda-forge "siesta=5.2=*mpich*"
Once the parallel version of SIESTA is installed, keep open your terminal and verify your installation following instructions given in the next section, Verify SIESTA installation.

Verify SIESTA installation#

To confirm that SIESTA has been successfully installed, on the same terminal window type from which you installed SIESTA 5.2 as described in section Install SIESTA & TranSIESTA 5.2,type the following command:
siesta --version
You should see the SIESTA version information displayed in the terminal as shown in the example below,
Executable      : siesta
Version         : 5.2.0
Architecture    : x86_64
Compiler version: GNU-13.3.0
Compiler flags  : -march=nocona -mtune=haswell -ftree-vectorize -fPIC -fstack-protector-strong -fno-plt -O2 -ffunction-sections -pipe -isystem <prefix>/include -I<prefix>/_build_env/include -fdebug-prefix-map=<prefix>/work=/usr/local/src/conda/siesta-5.2.0 -fdebug-prefix-map=<prefix>=/usr/local/src/conda-prefix -I<prefix>/lib -fallow-argument-mismatch -O3
Parallelisations: MPI
...

Install Quantum ESPRESSO#

You can also install the parallel version of Quantum ESPRESSO via Conda using the following command:
conda install conda-forge::qe

Verify Quantum ESPRESSO installation#

Type
pw.x
in the terminal to verify that Quantum ESPRESSO is correctly installed.
You should see output similar to the figure below, indicating that Quantum ESPRESSO is running and waiting for an input file.
Program PWSCF v.7.4 starts on  8May2025 at 10:32:36

This program is part of the open-source Quantum ESPRESSO suite
for quantum simulation of materials; please cite
    "P. Giannozzi et al., J. Phys.:Condens. Matter 21 395502 (2009);
    "P. Giannozzi et al., J. Phys.:Condens. Matter 29 465901 (2017);
    "P. Giannozzi et al., J. Chem. Phys. 152 154105 (2020);
     URL http://www.quantum-espresso.org",
in publications or presentations arising from this work. More details at
http://www.quantum-espresso.org/quote

Parallel version (MPI & OpenMP), running on       1 processor cores
Number of MPI processes:                 1
Threads/MPI process:                     1

MPI processes distributed on     1 nodes
2985 MiB available memory on the printing compute node when the environment starts

Waiting for input...

Annex 2: Install parallel libraries#

Windows: Installing Microsoft MPI v10.1.3#

Microsoft MPI v10.1.3 is a Windows mpi library necessary to run SIESTA using several processors. It is a microsoft software and can be downloaded from https://www.microsoft.com/en-us/download/details.aspx?id=105289. When you click on download please choose the item msmpisetup.exe.
../_images/microsoft-mpi.png
Once downloaded just double-click on it and follow the instructions to install the tool.

Debian/Ubuntu/Mint: Installing Scalapack Openmpi library#

To install Scalapack Openmpi library use the apt install command (you need to be superuser):
sudo apt install libscalapack-openmpi2.1
Version 2.1 must to be used to be compatible with the SIESTA binary that we provide.

Annex 3: Configure remote server#

To be able to run simulations with ASAP on remote servers, you have to make sure that the remote environments fulfil a few requirements. First of all, each remote server must provide a work environment compatible with the Unix standards. This includes any Linux distribution, any BSD distribution, and MacOS X to a large extent. Proprietary Unix-based systems are also supported. This is not required for the local computer.
In this appendix, we provide instructions on how to configure remote servers.
NOTE: The following steps have to be done only once on each remote server and are not necessary for local simulations.

  1. Make sure the user on the local computer can connect through SSH. See section SSH connection.

  2. Make sure that you have access to the correct version of Python 3 on the remote server. See section Python interpreter.

  3. Install Python package on the remote server.

SSH connection#

The first step in configuring a remote server for ASAP is to connect to it through SSH. Depending on the remote server provider policy the secutiry protocol access might vary. We suggest to connect through SSH to remote servers with public-key authentication, see section .
In the next subsections, we give you instructions on how to install a Install OpenSSH on the local machine and configure an SSH public-key authentication access.

Install OpenSSH#

We highly recommend OpenSSH, which is available for most Unix-like systems.
On Windows 10, you can install the OpenSSH Client following the steps below:

  • Type app in the start search bar.

  • Select “settings app”.

  • In the “Window Settings” which appears, click on “Apps”.

  • Then click on “Optional features” and “Add a feature”.

  • Look for OpenSSH Client, click on it and install.

If you encounter any problems in setting up openssh, please refer to your network administrator or to the OpenSSH documentation for installation instructions.

SSH public-key authentication#

SSH connection often require to input a password, the password can be inputed directly in ASAP, please refer to the option Required password at connection time in section Step 2: Set up ASAP for remote computing. Alternatively, the SSH connections can take place through public keys in a non-interactive way. This means that your local account must have a public-private SSH key pair properly configured and that the local public key must be registered on the remote server.
Once you have made sure that this is the case, you can proceed with the configuration of the remote server using this connection.
Please follow the steps below if you wish to configure an SSH public-key authentication access.
Generate public-private SSH key pair on Windows 10#

Open a powershell instance and use ssh-keygen to generate the public-private SSH key pair:

ssh-keygen

Follow the instructions to generate the id_rsa, id_rsa.pub files.

Register the local public key on the remote server#
Access the .ssh/ folder in your home using the command:
cd $HOME/.ssh

and list the files in the folder:

ls
Add the contents of your machine public key (id_rsa.pub) at the end of the $HOME/.ssh/authorized_keys file, located on the remote server. Create the authorized_keys file if it does not exist.
Note: Be careful to append your key to the file, preserving its previous contents, or you might become unable to connect to it from other computers than the current one.
Connect to the remote server through SSH to confirm that it does not ask you for a password. At most, you should be asked for the passphrase of your SSH key.

Python interpreter#

Independently of the program used to run remote simulations, the remote server must provide a working Python 3 environment.
Please note that Python version 3.8 or above is required on the remote server or the simulations will fail. If you are not sure how to access a Python 3 installation, please ask your server administrator to provide you with instructions on how to do so.
Once you are able to run a Python interpreter, you can check that it provides a couple of essential modules by running it:
python

and typing the following commands in the Python console:

import pip
import venv
If one of these 2 commands fails, please ask your server administrator to install the corresponding Python module or provide you with an alternative. Once done, you can exit from the Python console by typing Ctrl-D (or Cmd-D on MacOS).
Write down any command required to make Python visible to your system at the bottom of the .simune_env file.

You do not have Python already available in your machine: Miniconda#

Follow the instructions at https://www.anaconda.com/docs/getting-started/miniconda/install#macos-linux-installation to install Miniconda for your operating system

Install python3.12 enviroment by typing,

conda create -n py312 python=3.12
Next, activate py310 enviroment,
conda activate py312
Once the enviroment has been activated follow the next section instructions, Install Python package on the remote server.

Install Python package on the remote server#

The package necessary to install the python libraries that ASAP needs to run a simulation on a remote server can be downloaded using the following links

You should now have downloaded the package simune-asap-remote-env-XXXX.X.zip on your computer.

Please follow the next steps in order to complete the installation.

Copy simune-asap-remote-env-XXXX.X.zip on the remote server. This can be done using scp command, run the following command from your local machine,

scp -r simune-asap-remote-env-XXXX.X.zip <user>@<remote-server>:

Connect to the remote cluster using ssh command and unzip the folder,

unzip simune-asap-remote-env-XXXX.X.zip

and enter the folder

cd simune-asap-remote-env-XXXX.X

If you want to make sure that the installed environment corresponds to a specific version of Python, simply remove the simune-remote-env-py.tgz files associated with the other versions. For instance, if you have a Python 3.10 environment, you would type:

rm simune-remote-env-py3.7.tgz simune-remote-env-py3.8.tgz simune-remote-env-py3.9.tgz

If all files are present, the installer will always try to install the environment for the most recent Python version.

Finally, run the following command,

bash ./install-simune-env.sh

and wait for the script to finish. At the end, it will display instructions and explanations on how to use your new environment with ASAP. Please make a copy of these instructions before closing the connection.

../_images/remote-setup-terminal.png

Fig. 6 Copy the line starting with “source” in the remote RC command, please see section Step 2: Set up ASAP for remote computing.#

Troubleshooting#

Cannot connect to remote servers after Windows upgrade#

If connections to remote servers were working before a Windows upgrade and stop doing so afterwards, it is likely because the SSH agent has been disabled.
To re-enable it, open a PowerShell terminal with Administrator privileges and type:
Set-Service ssh-agent -StartupType Automatic

Then reboot the computer.

If this still doesn’t work, open a normal PowerShell terminal and type:

ssh-add $HOME/.ssh/id_rsa
If your key has a different name, please substitute id_rsa with the actual key name.
Restart ASAP after adding the key. This should now work.
If you still have trouble, please consult your system administrator.
SIMUNE is a company expert in Atomistic Simulations. We offer services for leading industrial, academic, and research customers working with materials (semiconductors, energy storage, new compounds, etc.). SIMUNE trains researchers on atomic scale simulation techniques and collaborates with them in complex simulation challenges. Besides, SIMUNE provides them with professional support in order to accelerate and optimize the materials design process.
ASAP (Advanced Simulation Atomistic Platform) software is a product of Simune Atomistics S.L. ASAP is composed of a set of tools and modules developed around atomistic simulation codes to facilitate their use for industrial users. ASAP includes a SIESTA calculator interface. Upcoming versions of ASAP will provide interfaces with other computational engines, some of which working at different scales than SIESTA.
ASAP is designed to fulfill the following main objectives:

  • Make popular materials modeling codes available to industrial users.

  • Gather the relevant tools and codes within a unified user interface, in order to improve their usability.

  • Automate the existing workflows for the simulation of materials properties and industrial problems of interest.

Soler, José M, Emilio Artacho, Julian D Gale, Alberto Garcia, Javier Junquera, Pablo Ordejón, and Daniel Sánchez-Portal. 2002. “The SIESTA Method for Ab Initio order-N Materials Simulation.” Journal of Physics: Condensed Matter 14 (11): 2745–79. https://doi.org/10.1088/0953-8984/14/11/302.