Atomistic

Simulation
Advanced
Platform
User’s Manual

ASAP Version 2022.1

Simune Atomistics

https://simuneatomistics.com/
ASAP User’s Manual
Version 2022.1

Copyright
c 2019–2022 Simune Atomistics S.L. All rights reserved.
https://simuneatomistics.com/

No part of this document or the related files may be reproduced or trans-

mitted in any form, by any means (electronic, photocopying, recording, or
otherwise) without the prior written permission of the publisher.

For permissions, please contact: info@simuneatomistics.com.

Contents

About this manual 1

1 ASAP basics 3
1.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2 ASAP workflows . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.3 About ASAP . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4 Preferences in ASAP . . . . . . . . . . . . . . . . . . . . . . 6
1.5 The main window and project tray . . . . . . . . . . . . . . 7
1.6 Managing projects in ASAP . . . . . . . . . . . . . . . . . . 10
1.6.1 Menu bar: File . . . . . . . . . . . . . . . . . . . . . . 10
1.6.2 Menu bar: Edit . . . . . . . . . . . . . . . . . . . . . 12
1.6.3 Menu bar: View . . . . . . . . . . . . . . . . . . . . . 13
1.6.4 Menu bar: Calculate . . . . . . . . . . . . . . . . . . 15
1.6.5 Menu bar: Analyse . . . . . . . . . . . . . . . . . . . 15
1.6.6 Menu bar: Help . . . . . . . . . . . . . . . . . . . . . 16

2 ASAP workflows 19
2.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
2.2 Single-point calculations . . . . . . . . . . . . . . . . . . . . 22
2.2.1 Single-point workflow: Analysis . . . . . . . . . . . . 25
2.3 Convergence Tools: mesh cutoff . . . . . . . . . . . . . . . 28
2.3.1 Convergence Tools: mesh cutoff workflow: Analysis 35
2.4 Convergence Tools: Brillouin Zone sampling . . . . . . . . 38
2.4.1 Convergence Tools. Brillouin Zone sampling work-
flow: Analysis . . . . . . . . . . . . . . . . . . . . . . 44
2.5 Geometry Optimisation . . . . . . . . . . . . . . . . . . . . 45
2.5.1 Geometry Optimisation workflow: Analysis . . . . 51
2.6 Molecular Dynamics . . . . . . . . . . . . . . . . . . . . . . 54
2.6.1 Molecular dynamics workflow: Analysis . . . . . . . 69
2.7 Equation Of State (EOS) . . . . . . . . . . . . . . . . . . . . 79
2.7.1 Equation Of State workflow: Analysis . . . . . . . . 84

2
CONTENTS 3

2.8 Nudged Elastic Band (NEB) . . . . . . . . . . . . . . . . . . 87

2.8.1 Starting a NEB project . . . . . . . . . . . . . . . . . 88
2.8.2 Editing initial and final geometries . . . . . . . . . . 89
2.8.3 NEB workflow: The NEB project tree . . . . . . . . . 92
2.8.4 NEB workflow: Geometry optimisation of initial
and final configurations . . . . . . . . . . . . . . . . 93
2.8.5 NEB workflow: Interpolation of intermediate images 94
2.8.6 NEB workflow: NEB configuration . . . . . . . . . . 95
2.8.7 NEB workflow: NEB Optimisation . . . . . . . . . . 100
2.8.8 NEB workflow: NEB Analysis . . . . . . . . . . . . . 101
2.9 Vibrations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
2.9.1 Vibrations workflow: Analysis . . . . . . . . . . . . . 110
2.10 Phonons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
2.10.1 Phonon workflow: Analysis . . . . . . . . . . . . . . 118
2.11 Interfacial energy tool (IET) . . . . . . . . . . . . . . . . . . 125
2.11.1 Interfacial Energy Tool workflow: Analysis . . . . . 131

3 The atomic structure builder 136

3.1 Structure Modeling in ASAP . . . . . . . . . . . . . . . . . . 136
3.1.1 Opening a new project . . . . . . . . . . . . . . . . . 136
3.1.2 Structure builder/viewer interface . . . . . . . . . . 138
3.2 ASE GUI in ASAP . . . . . . . . . . . . . . . . . . . . . . . . . 146
3.2.1 Visualisation . . . . . . . . . . . . . . . . . . . . . . . 146
3.2.2 Measuring geometric quantities . . . . . . . . . . . 147
3.2.3 Structure Manipulation . . . . . . . . . . . . . . . . 147

4 Parameters 150
4.1 Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
4.2 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
4.3 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
4.3.1 Band structure . . . . . . . . . . . . . . . . . . . . . 162
4.3.2 Electronic Density Of States and Projected Density
Of States . . . . . . . . . . . . . . . . . . . . . . . . . 165
4.3.3 Local density of states . . . . . . . . . . . . . . . . . 167

5 Calculators 170
5.1 The EMT Calculator . . . . . . . . . . . . . . . . . . . . . . . 171
5.2 The SIESTA Calculator . . . . . . . . . . . . . . . . . . . . . 173
5.2.1 SIESTA Parameters: Physics . . . . . . . . . . . . . . 175
5.2.2 SIESTA Parameters: Convergence . . . . . . . . . . 180
5.2.3 SIESTA Parameters: Basis set and Pseudopotentials 183
CONTENTS i

5.2.4 SIESTA Parameters: SCF . . . . . . . . . . . . . . . . 187

5.2.5 Preview input file . . . . . . . . . . . . . . . . . . . . 190
5.2.6 customise . . . . . . . . . . . . . . . . . . . . . . . . 191

6 Runners 194
6.1 Preparing run environments . . . . . . . . . . . . . . . . . 194
6.1.1 Installing SIESTA on the local computer . . . . . . . 194
6.1.2 Preparing a remote server before the first simula-
tion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
6.2 Managing local and remote runners . . . . . . . . . . . . . 196
6.2.1 Adding a remote machine . . . . . . . . . . . . . . . 198
6.2.2 Adding a program . . . . . . . . . . . . . . . . . . . 199

7 The run widget 204

8 Analysis 212
8.1 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.1.1 Density of States . . . . . . . . . . . . . . . . . . . . 217
8.1.2 Band Structure . . . . . . . . . . . . . . . . . . . . . 220
8.1.3 Partial DOS . . . . . . . . . . . . . . . . . . . . . . . 222
8.1.4 LDOS . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

Bibliography 231

A Preparing a remote server before the first simulation 232

A.1 OpenSSH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
A.1.1 Install OpenSSH . . . . . . . . . . . . . . . . . . . . . 233
A.1.2 SSH public-key authentication . . . . . . . . . . . . 234
A.2 Configure a Python 3 virtual environment on the remote
server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
A.2.1 Python interpreter . . . . . . . . . . . . . . . . . . . 235
A.2.2 Python 3 virtual environment . . . . . . . . . . . . . 236
A.3 Install ASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
A.4 Install SIESTA on the remote server . . . . . . . . . . . . . 238
A.5 Set up .simune_env configuration file . . . . . . . . . . . . 238
About this manual

This manual is the companion document of the Atomistic Simulation

Advanced Platform (ASAP), version 2022.1. Although most of its con-
tents may still be useful for upcoming versions of ASAP, we recom-
mend you to refer to the user manual provided with the version of
ASAP you are currently using. You can access to this manual through
the "Help / User Manual" menu in ASAP.

For any doubt, comment or question about ASAP or the present man-
ual, please contact us at: info@simuneatomistics.com.
Manual Overview:
• Chapter 1 explains how to get started with ASAP and manage
projects.
• Chapter 2 describes the available workflows to perform different
kinds of simulations (single-point, geometry optimisation, equa-
tion of state, nudged elastic band, etc.).
• Chapter 3 describes how to construct molecules, bulk systems
and surfaces using databases and built-in functions for structure
modeling in ASAP.
• Chapter 5 provides information on available ASAP calculators. A
calculator is a software component designed to facilitate the use
of a selected simulation code, from the preparation of input files
to the post-processing of output files, including the execution of
the program.
• Chapter 6 explains how to configure local and remote runners,
including parallelisation aspects.
• Chapter 7 describes the capabilities of the Run widget. The Run
widget facilitates the submission of a calculation to a local com-
puter or a remote server.

1
CONTENTS 2

• Chapter 8 provides an overview of the implemented analysis tools

for each of the available workflows.
Chapter 1

ASAP basics

1.1 Introduction
SIMUNE is a company expert in Atomistic Simulations. We offer ser-
vices for leading industrial,academic, and research customers work-
ing 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 professional support in order to accelerate
and optimize the materials design process.

The ASAP (Atomistic Simulation Advanced Platform) software package

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. This version of ASAP (2022.1)
includes a SIESTA calculator interface. Next versions of ASAP will in-
terface with other computational engines and incorporate codes with
other functionalities or working in different scales than SIESTA.

We have designed ASAP to fulfil the following objectives:

• Gather relevant tools and codes, provide support and usability to

them.

• Facilitate the use of popular material modelling codes to indus-

trial users.

• Automate the workflow needed to simulate particular material

properties and selected industrial problems.

3
CHAPTER 1. ASAP BASICS 4

1.2 ASAP workflows

We have designed ASAP workflows to help the user in all necessary
steps involved in a computer simulation aimed to study and charac-
terise material properties:

• Preparing the material model (Edit structure).

• Defining the properties of interest (Edit project).
• Setting up the input parameters for the simulation (Edit calcula-
tor).
• Running/submitting the calculation (Run).
• Analysing results (Analysis).

1.3 About ASAP

We have developed ASAP in Python 3. It is compatible with Python ≥
3.6. We use the Python library PySide2 (binding of the GUI toolkit Qt)
for GUI rendering. The other main packages and libraries ASAP relies
on are:

• The Atomic Simulation Environment, aka ASE (https://wiki.fysik.

dtu.dk/ase)
CHAPTER 1. ASAP BASICS 5

• SciPy (https://www.scipy.org)

• Matplotlib (https://matplotlib.org/)

ASAP 2022.1 implements the SIESTA calculator able to interface with

the SIESTA package. It has been tested on Windows 10, version 1903
onwards, on Linux (Debian, Ubuntu, CentOS), as well as macOS X High
Sierra, Yosemite, and Catalina.

If you are preparing an article using ASAP, please include following ac-
knowledgment in your manuscript:

"These studies were performed using some results obtained with the
ASAP-YYYY.N (Atomistic Simulation Advanced Platform)."

Here YYYY is the 4-digit representation of the year and N the release
index for that year, as for example ASAP-2022.1.

Please find below the references to methodology and software papers:

• E. Artacho, D. Sánchez-Portal, P. Ordejón, A. García, and J. M. Soler,

Linear-Scaling ab-initio Calculations for Large and Complex Sys-
tems, Phys. Status Solidi B 215, 809 (1999).

• J. M. Soler, E. Artacho, J. D. Gale, A. García, J. Junquera, P. Ordejón

and D. Sánchez-Portal, The SIESTA method for ab initio order-N
materials simulation J. Phys. Condens. Matter 14, 11, (2002)

• E. Artacho, E. Anglada, O. Diéguez, J. D. Gale, A. García, J. Junquera,

R. M. Martin, P. Ordejón, J. M. Pruneda, D. Sánchez-Portal and J. M.
Soler, The SIESTA method; developments and applicability, J. Phys.
Condens. Matter 20, 064208, (2008).

• A. H. Larsen, J. J. Mortensen, J. Blomqvist, I. E. Castelli, R. Chris-

tensen, M. Dulak, J. Friis, M. N. Groves, B.Hammer, C. Hargus, E.
D. Hermes, P. C. Jennings, P. B. Jensen,K. Kaasbjerg, J. Kermode,
J. R. Kitchin, E. L. Kolsbjerg, J. Kubal, S. Lysgaard, J. B. Marons-
son, T. Maxson, T. Olsen, L. Pastewka, A. Peterson, C. Rostgaard,
J. Schiøtz, O. Schutt, M. Strange, K.Thygesen, T. Vegge, L. Vilhelm-
sen, M. Walter, Z. Zeng, and K. W.Jacobsen, The Atomic Simulation
Environment — A Python library for working with atoms, J. Phys.
Condens. Matter 29, 273002 (2017).
CHAPTER 1. ASAP BASICS 6

1.4 Preferences in ASAP

In the ASAP menu bar, press the Preferences... button to open the
preferences widget.

The preferences widget in ASAP offers the possibility of:

• Select the workspace. Press the Choose... button to select the

directory to store the input-output of the calculations.

• Select the default calculator. Open the Default calculator dialog to

select one of the calculators offered by ASAP.
CHAPTER 1. ASAP BASICS 7

Press the OK button to close the Preferences widget.

1.5 The main window and project tray

We have designed the main window of ASAP to give the user a com-
plete overview of the active projects.
The menu bar contains all the action-buttons to perform all the basic
actions on the projects. The project tray shows all started projects.
Each row is a project or a subproject, action buttons on each line allow
you to act directly on the specific project. We show the action buttons
in the Figure 1.1.
CHAPTER 1. ASAP BASICS 8

Figure 1.1: ASAP main window.

1. Open project. The project is added to the project tray.

2. Duplicate project. To add a copy of the selected project to the
project tray.
3. Close project. The selected project is closed. It is not visible any-
more in the project tray. The related project files are not deleted.
4. Start a new project by creating a molecular structure.
5. Start a new project by creating a surface (2D system).
6. Start a new project by creating a bulk (3D system).
7. Start a new project by creating a nanotube.
8. Configure runners. You can manage local and remote runners.
9. Open the user manual.
10. View and edit the structure: Use double click to open ASE graphi-
cal user interface.
CHAPTER 1. ASAP BASICS 9

11. Project tray. It contains all the active projects.

12. Projects label.

13. Button to select the project type.

14. Button to edit project parameters (settings, variables and proper-

ties).

15. Button to select the calculator and edit calculator parameters.

16. Button to Run/Launch the simulation.

17. Button to analyse the obtained results.

18. Project status: New, running, completed, cancelled, failed.

Complex projects such as Nudged Elastic Band (Section 2.8) require the
presence of subprojects. Subprojects are displayed as nested projects.
See Figure 1.2.

Figure 1.2: ASAP subproject structure.

19. Main project: Parent project.

20. Subprojects: Nested child projects.

CHAPTER 1. ASAP BASICS 10

Figure 1.3: ASAP main window.

21. Notes. Button to write notes about the selected project.

1.6 Managing projects in ASAP

1.6.1 Menu bar: File

The file tab allows the user to manage the projects easily:

• Create new. Starts a new project with the desired type of struc-
ture. (See chapter 3)
The default project file is “project-XX” and it is created in the se-
lected workplace (see section 1.4). Furthermore, the default project
CHAPTER 1. ASAP BASICS 11

type is the single point calculation, but you can edit this easily (see
section 1.5).
In addition,if you want to know the location of the selected project
you can view it on the bottom of the window, once selected.

• New Project. Creates a new type of project (See section 2.1) of

the selected structure.

• Open. Allows you to open .json and .asap files.

• Open in terminal. Opens up a terminal linked to the selected

ASAP project.

• Close. Eliminate from the project from the tray.

• Save. Saves modifications done to the previous saved version.

• Save as. Saves the project file (.asap) under a specific name and
directory.

• Import. Allows you to open different types of files.

• Export. Saves different types of file.

Figure 1.4: Type of file options

• Delete. Erases the project from both the project tray and the
computer all together.

• Exit. Closes the software.

CHAPTER 1. ASAP BASICS 12

1.6.2 Menu bar: Edit

The edit tab allows the user to make all the available changes in the
projects.
Most of those options have an in depth explanations throughout the
guide and are easily accessible with the main window or by using the
left click in the mouse on top of the desired project (See section 1.5).

• Set project label. Changes the project name.

• Edit structure. Opens up the structure’s editing option using ASE

GUI (See section 3.2).

• Edit project type. Creates a duplicate of the selected structure

allowing the user to restart the project type.

• Edit project parameters. Opens up parameter widget (See chap-

ter 4).

• Calculator type. Opens up the tool to choose the computational

engine (See chapter 5).

• Calculator parameters. Opens up the tool to edit the SIESTA

parameters (See section 5.2).

• Edit variables. Gives you the different variable edit options (See
section 4.2).
CHAPTER 1. ASAP BASICS 13

Figure 1.5: Edit variables options

• Merge two structures.

• Merge for transport calculations.

• Rotate subsystem.

• Duplicate. Makes a copy of the selected project.

• Configure runners. Opens up the configuration runner widget

(See section 6.2).

• Preferences. Opens up the preferences widget (See section 1.4).

1.6.3 Menu bar: View

CHAPTER 1. ASAP BASICS 14

• Info. Opens up a widget with information about the selected

project.

Figure 1.6: Information widget

• HPC job queues.

• Drag & drop. Enables and disables the option to move the posi-
tion of the projects in the tray.
CHAPTER 1. ASAP BASICS 15

1.6.4 Menu bar: Calculate

• Run. Opens up the run widget (See chapter 7).

1.6.5 Menu bar: Analyse

• Analyse. Opens up the analyse widget of the selected project.

• Analyse PDOS file.

• Copy all files from remote.

• Unit conversion. Opens up the unit conversion widget. Unit con-

version facilitates unit conversions of different quantities: energy,
length, force, time and mass.
CHAPTER 1. ASAP BASICS 16

1.6.6 Menu bar: Help

• User manual. Opens up the ASAP user manual.

• Licences. Opens up a widget with all the licenses ASAP uses.

CHAPTER 1. ASAP BASICS 17

Figure 1.7: Licenses widget

• Download Siesta. Opens up the siesta download widget (See

section 5.2).

• Open log file.

• About dev. Opens up a window with general information about

ASAP.
CHAPTER 1. ASAP BASICS 18

Figure 1.8: General information about ASAP

Chapter 2

ASAP workflows

2.1 Overview
We have designed ASAP workflows to help you in all necessary steps
involved in a computer simulation,

• Preparing the material model.

• Defining the properties of interest.

• Setting up the input parameters for the simulation.

• Running/submitting the calculation.

• Analysing results.

In Chapter 3, we provide information on how to define the atomic

structure. In Chapter 5, we address the computational engines inter-
facing with ASAP. We provide instructions on how to manage local and
remote runners in Chapter 6.

19
CHAPTER 2. ASAP WORKFLOWS 20

In the present chapter, we focus on addressing the different types of

projects that we have implemented in ASAP 2022.1. We give infor-
mation on the project parameters and the analysis widget options for
each kind of project

In ASAP 2022.1, we have implemented the following types of projects:

• Single-point calculation A single-point energy calculation calcu-

lates the wave function and charge density, and hence the energy,
of the particular arrangement of nuclei defined by the atomistic
model (well-specified geometric structure). The computed energy
is the total energy (sum of the electronic energy and nuclear re-
pulsion energy).
See section 2.2 for further information on this type of project.
• Convergence tools: Mesh cutoff convergence
Siesta uses a finite 3D grid for the calculation of some integrals
and the representation of charge densities and potentials. Its
fineness is determined by its plane-wave cutoff, as given by the
MeshCutoff option. It means that all periodic plane waves with ki-
netic energy lower than this cutoff can be represented in the grid
without aliasing. In turn, this implies that if a function (e.g. the
density or the effective potential) is an expansion of only these
plane waves, it can be Fourier transformed back and forth with-
out any approximation.
Mesh cutoff convergence can be used to diagnose the eggbox
effect to be expected for a particular pseudopotential/basis-set
combination. The energy as a function of atomic coordinates dis-
placement is computed. The eggbox period is evaluated for the
selected Mesh cutoff values.
See section 2.3 for further information on this type of project.
• Convergence tools: Brillouin Zone sampling
In this type of project, ASAP runs a set of single-point calculations
using the selected Brillouin zone (BZ) sampling grids. ASAP uses
Monkhorst-Pack grids to sample the Brillouin zone. A Monkhorst-
Pack grid is a set of evenly spaced k-points and is specified by
3 numbers: the number of points along each axis in reciprocal
space.
See section 2.4 for further information on this type of project.
CHAPTER 2. ASAP WORKFLOWS 21

• Geometry Optimisation
The determination of equilibrium structure is of fundamental im-
portance in the modelling of materials at the atomic scale. In this
type of project, the calculation starts from a well-specified geo-
metric structure. Then, the atoms are moved to try to minimise
the forces (and stresses) acting on them. Several methods for the
structure geometry optimisation are available. All of them try to
locate minima and saddle points on the Potential Energy Surface
(PES).
See 2.5 for further information on this type of project.
• Molecular Dynamics The Molecular Dynamics (MD) type of project
performs dynamics of the system in time. At each time step, ab
initio calculations are performed and the forces acting on each
atom are extracted. The position of the atoms is updated with
respect to these forces using classical equations of motion (New-
ton’s second law). MD is computing electronic structure, forces
and stresses for the system geometry at each time step, updat-
ing the atomic positions and proceeding to the next cycle. ASAP
includes several algorithms to perform MD calculations.
See 2.6 for further information on this type of project.
• Equation of State (EOS) The workflow implemented in this type
of project automates the computation of energy (E) versus vol-
ume (V) curve. The curve is fitted to the selected universal Equa-
tions of State (EOS) (Murnaghan’s, third-order isothermal Birch-
Murnaghan’s, exponential Vinet’s...) to compute equilibrium prop-
erties such as bulk modulus (B).
See section 2.7 for further information on this type of project.
• Nudged Elastic Band (NEB) Nudged Elastic Band (NEB) is a method
for finding saddle points (transition state) and minimum energy
paths between known reactants (initial state) and products (final
state). ASAP facilitates all the steps involved in the workflow of a
NEB simulation.
See section 2.8 for further information on this type of project.
• Vibrations ASAP automates the calculation of vibrational modes
of a well-specified geometric structure. The vibrational frequen-
cies are calculated from a finite difference approximation of the
Hessian matrix.
CHAPTER 2. ASAP WORKFLOWS 22

See section 2.9 for further information on this type of project.

• Phonons
We have implemented a workflow to automate the computation
and analysis of phonons of a periodic system.
Our implementation uses the so-called small-displacement or frozen-
phonons method as has been done in ASE (https://wiki.fysik.
dtu.dk/ase/ase/phonons.html). The non-analytic contributions to
the dynamical matrix are currently not treated. On the other
hand, we perform the computation of the dynamical matrix in
reciprocal space with a Parlinski method (https://doi.org/10.
1103/PhysRevLett.78.4063). The Vibra utility, available within the
SIESTA package, inspired our implementation. (https://gitlab.
com/siesta-project/siesta/-/blob/master/Util/Vibra).
See section 2.10 for further information on this type of project.

• Interfacial Energy Tool The workflow implemented in this type

of project automates the computation of single-point calculations
of a system built out of two subsystems placed at different dis-
tances (d).

See section 2.11 for further information on this type of project.

2.2 Single-point calculations

In this type of project, it is calculated the wave function and charge
density, and hence the energy, of the particular arrangement of nuclei
defined by the atomistic model.

We refer the user to section 3.1 for further information on ASAP struc-
ture builder/viewer interface.
CHAPTER 2. ASAP WORKFLOWS 23

ASAP sets single-point calculation as the default project type.

Click on the Calculator icon to select the computational engine to be

used during the single point calculation.

We refer the user to chapter 5 for further information on ASAP avail-

able calculators.

Click on the Run icon to open Run widget. Then click on the Run button
to start the the single-point calculation.
CHAPTER 2. ASAP WORKFLOWS 24

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

After submitting a single-point calculation, the tab Calculator output in

Run widget shows the complete calculation output in real-time. For
this type of project, the tab Tab output shows the same information as
Calculator output.
CHAPTER 2. ASAP WORKFLOWS 25

2.2.1 Single-point workflow: Analysis

When the calculation is completed, select Exit and analyse to open
the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 26

The following information extracted from the single-point calculation

output is available:

• Show input. It shows the complete input file of the single-point

calculation. This option is only available for SIESTA calculator.
CHAPTER 2. ASAP WORKFLOWS 27

• Show output. It shows the complete output file of the single-

point calculation.

• Energy. It shows the information on Fermi energy and Total en-

ergy.

• Single-particle energies. Kohn-Sham eigenenergies of the sys-

tem. It prints information about the eigenvalues produced during
the (last) iteration of the self-consistent cycle, and associated with
CHAPTER 2. ASAP WORKFLOWS 28

the appropriate k-point sampling. It also shows a summary with

the minimum, maximum and frontier orbital energies HOMO (high-
est occupied molecular orbital) and LUMO (lowest unoccupied
molecular orbital).

We refer the user to chapter 8 for further information on ASAP analysis

widget.

2.3 Convergence Tools: mesh cutoff

This type of project diagnoses the eggbox effect to be expected for
a particular pseudopotential/basis-set combination. The energy as a
function of atomic coordinates displacement is computed. The eggbox
period is evaluated for a set of selected Mesh cutoff values.

The project starts with the definition of the atomic structure. We re-
fer the user to section 3.1 for further information on ASAP structure
builder/viewer interface.

After the atomic structure is defined, edit the type of project.

CHAPTER 2. ASAP WORKFLOWS 29

From the list of possible project types implemented in ASAP, select

Convergence tools: mesh cutoff.
CHAPTER 2. ASAP WORKFLOWS 30

Then click on the Parameters icon to open the Convergence tools: mesh
cutoff parameters widget.

The project parameters that can be tuned are:

• Mesh cutoff values in eV units. The Mesh cutoff parameter de-

fines the plane wave cutoff for the grid. Press the Add value
button to incorporate to the right window, each of your selected
Mesh cutoff values. In this type of project, ASAP will run a set of
single-point calculation using the selected Mesh cutoff values.
CHAPTER 2. ASAP WORKFLOWS 31

• Directions. You can select the direction in which you desire to

evaluate the eggbox effect; 1-st, 2-nd and 3-rd unit cell vector.
You must be aware that the number of calculations, and the com-
putational time, will be doubled (tripled) when two (three) direc-
tions are selected.
CHAPTER 2. ASAP WORKFLOWS 32

• Number of steps. In this type of project, the energy is computed

as a function of atomic coordinates displacement. This field indi-
cates the number of rigid displacements.
CHAPTER 2. ASAP WORKFLOWS 33

Click on the Calculator icon to select the computational engine to be

used during geometry optimisation.

The Convergence Tool: mesh cutoff is only compatible with SIESTA cal-
culator. We refer the user to chapter 5.2 for further information on
SIESTA calculator. Notice that, the real-space mesh cutoff energy lo-
cated in the Convergence parameters widget, described in subsection
5.2.2 is disabled for this type of project.

Click on the Run icon to open Run widget. Then click on the Run button
to submit the set of calculations required to evaluate the eggbox effect
for the selected meshcutoff parameters.
CHAPTER 2. ASAP WORKFLOWS 34

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

After submitting a job (run), the tab Calculator output in Run widget
shows the complete calculation output in real time.
CHAPTER 2. ASAP WORKFLOWS 35

In addition, the tab Task output in Run widget shows relevant informa-
tion of Geometry optimisation output in real-time.

2.3.1 Convergence Tools: mesh cutoff workflow: Anal-

ysis
When the calculation is completed, select Exit and analyse to open
the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 36

Select the Convergence of the mesh cutoff... button to visualise the

energy as a function of atomic coordinates displacement.
CHAPTER 2. ASAP WORKFLOWS 37

Check the tick-boxes corresponding to the mesh cutoff values and di-
rections for which you desire to evaluate the eggbox effect. The max-
imum energy difference (∆Emax ) is indicated in the figure for each of
the selected mesh cutoff values.
CHAPTER 2. ASAP WORKFLOWS 38

You can also visualise the effective force as a function of atomic coor-
dinates displacement.

2.4 Convergence Tools: Brillouin Zone sam-

pling
In this type of project, ASAP will run a set of single-point calculations us-
ing the selected Brillouin zone (BZ) sampling grids. ASAP uses Monkhorst-
Pack grids to sample the Brillouin zone. A Monkhorst-Pack grid is a set
of evenly spaced k-points and is specified by 3 numbers: the number
CHAPTER 2. ASAP WORKFLOWS 39

of points along each axis in reciprocal space.

The project starts with the definition of the atomic structure. We re-
fer the user to section 3.1 for further information on ASAP structure
builder/viewer interface.

After the atomic structure is defined, edit the type of project,

from the list of possible project types implemented in ASAP, select Con-
vergence tools: BZ sampling.

Then click on the Parameters icon to open the Convergence tools: BZ

sampling parameters widget.
CHAPTER 2. ASAP WORKFLOWS 40

On the right side of the Parameter widget, you can see the Monkhorst-
Pack grid that will be used for each of the single-point calculations. You
can modify the BZ sampling by tuning the following parameters:

• Monkhorst-Pack grid. Initial Monkhorst-Pack grid.

ASAP also indicates the corresponding k-grid cutoff, a parame-
ter determining the fineness of the k-grid used for Brillouin zone
sampling. The k-grid cutoff is half the length of the smallest lat-
tice vector of the supercell required to obtain the same sampling
precision with a single k point.

• Scaling of Monkhorst-Pack grid. The minimum (initial) and max-

imum (final) scaling applied to the MP grid previously indicated.

• Number of grids. To indicate the total number of grids to be

created.

• Type of grids. To indicate if you desire to include only even or

odd Monkhorst-Pack grids.
CHAPTER 2. ASAP WORKFLOWS 41

Press the Update BZ samplings button to update the list of grids dis-
played in the right side of the Parameter widget.

Press the OK button to close the IET widget once the parameters are
properly set.

Click on the Calculator icon to select the computational engine to be

used during geometry optimisation.
CHAPTER 2. ASAP WORKFLOWS 42

The Convergence Tool: BZ sampling is only compatible with the SIESTA

calculator. We refer the user to chapter 5.2 for further information on
SIESTA calculator.

Click on the Run icon to open the Run widget. Then click on the Run
button to submit the set of calculations required to perform the BZ
sampling.

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

After submitting a job (run), the Calculator output tab in the Run widget
shows the complete calculation output in real time.
CHAPTER 2. ASAP WORKFLOWS 43

In addition, the Task output tab in the Run widget shows relevant infor-
mation of Geometry optimisation output in real-time.
CHAPTER 2. ASAP WORKFLOWS 44

2.4.1 Convergence Tools. Brillouin Zone sampling work-

flow: Analysis
When the calculation is completed, select Exit and analyse to open
the analysis widget.

Select one of the Plot type options to visualise the energy deviation,
maximal force deviation or Frobenius norm of stress deviation com-
puted for each of the used Brillouin zone (BZ) sampling grids. Each de-
viation is computed using the corresponding value obtained with the
highest BZ sampling grid.
CHAPTER 2. ASAP WORKFLOWS 45

2.5 Geometry Optimisation

The geometry optimisation procedure is a standard theoretical tool
used to determine molecular structure. The type of project Geome-
try Optimisation implemented in ASAP seeks to find the geometry of a
particular arrangement of the atoms that represents a local or global
minimum.

A Geometry optimisation project starts with the definition of the atomic

structure. We refer the user to section 3.1 for further information on
ASAP structure builder/viewer interface.

After the atomic structure is defined, edit the type of project.

From the list of possible project types implemented in ASAP, select Ge-
ometry optimisation.
CHAPTER 2. ASAP WORKFLOWS 46

Then click on the Parameters icon to open the Geometry optimisation

parameters widget.

The project parameters that can be tuned are:

• Optimisation method ASAP can make use of all the local optimi-
sation algorithms available in ASE (https://wiki.fysik.dtu.dk/
ase/ase/optimize.html): BFGS, BFGSLineSearch, LBFGS, LBFGSLi-
neSearch, GPMin, MDMin and FIRE.
CHAPTER 2. ASAP WORKFLOWS 47

You can check the tick-box Optimise unit cell to optimise each
direction of the unit cell. You can also check the tick-boxes corre-
sponding to specific cell directions.
CHAPTER 2. ASAP WORKFLOWS 48

The Berny algorithm is currently being implemented and is not yet

usable in production. It has been disabled for safety.

• Max Force. Parameter to specify the convergence criterion. The

force on all individual atoms should be less than the specified
maximum force.

Click on the Calculator icon to select the computational engine to be

used during geometry optimisation.

We refer the user to chapter 5 for further information on ASAP avail-

able calculators.

Click on the Run icon to open Run widget. Then click on the Run button
to submit the geometry optimisation calculation.
CHAPTER 2. ASAP WORKFLOWS 49

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

After submitting a job (run), the tab Calculator output in Run widget
shows the complete calculation output in real time.
CHAPTER 2. ASAP WORKFLOWS 50

In addition, the tab Task output in Run widget shows relevant informa-
tion of Geometry optimisation output in real-time.
CHAPTER 2. ASAP WORKFLOWS 51

2.5.1 Geometry Optimisation workflow: Analysis

When the calculation is completed, select Exit and analyse to open
the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 52

Select Relaxation Analyse to visualise the energy and maximum force

convergence as a function of the minimisation steps,
CHAPTER 2. ASAP WORKFLOWS 53

Select the button View current image to visualise the converged atomic
CHAPTER 2. ASAP WORKFLOWS 54

structure in any of the steps of the geometry optimisation.

Select the button View all in 3D to visualise the geometry optimisation

as an animation.

We refer the user to chapter 8 for further information on ASAP analysis

widget.

2.6 Molecular Dynamics

ASAP provides a flexible GUI to facilitate all the steps involved in the
workflow of Molecular Dynamics simulations (MD) with a selected cal-
culator.

The project starts with the definition of the atomic structure of the sys-
tem. We refer the user to section 3.1 to find more information on the
ASAP structure builder/viewer interface.
CHAPTER 2. ASAP WORKFLOWS 55

After the atomic structure is defined, edit the type of project by select-
ing Molecular Dynamics from the list of possible project types imple-
mented in ASAP.

Notice that it is possible to run MD either with ASE or with SIESTA.

MD-ASE is compatible with all the calculators implemented in ASAP.
MD-SIESTA is only compatible with the SIESTA calculator. We recom-
mend to use MD implementation in SIESTA (MD-SIESTA) when using
the SIESTA calculator.

After selecting the project type, click on the Parameters icon to open
the Parameter widget.

You can use the Parameter widget to set up the input parameters re-
lated to the selected type of project (Settings), edit the masses, mag-
netic moments and atomic positions of the system (Variables), and
CHAPTER 2. ASAP WORKFLOWS 56

set up the input parameters required to compute the target material

properties of your calculation (Properties).

We describe below the settings and variables relevant for MD calcula-

tions, i.e. Velocity Distribution, as it affects the systems dynamics. We
refer the user to chapter 4 for more information on all parameters that
can be tuned in the Parameter widget.

Settings

The settings widget associated with a MD type of project offers the

following options:
• Time units. The options are femto-seconds (fs), i.e. 10−15 sec-
onds, and pico-seconds (ps), i.e. 10−12 s.
• Number of steps. Number of steps of the MD simulation. The
number of steps multiplied by the time step will give a full-time
MD calculation.
• Time step. This parameter controls the length of the time step in
the MD simulation. If the time step is too large, the dynamics of
the system will show unphysical non-energy conservation behav-
ior, population of high-frequency modes, even melting. There-
fore, if the system includes light atoms as Hydrogen, it is neces-
sary to consider a reduced time step. It is always safer to choose
CHAPTER 2. ASAP WORKFLOWS 57

a small time step. However, this will increase computation time.

We advise examining the system under study and select the time
step carefully. For most metallic systems, a time step of 5 fs
would be a good choice. Systems with light atoms (e.g. hydro-
gen), and/or with strong bonds (e.g. C-C, C-H) will require a smaller
time step.

• Logging frequency defines how frequently the information of

a running MD calculation is stored. During the MD simulation,
atomic positions and velocities are stored. This is very useful to
visualise and analyse the calculations.

• Algorithm. ASAP currently has different statistical ensembles in-

tegrated by the following algorithms:

– Verlet (NVE): Standard Verlet algorithm. Microcanonical en-

semble, where the number of atoms (N), volume (V) and total
energy (E) are conserved.
– Nosé thermostat (NVT): MD with temperature controlled by
means of a Nosé thermostat. Only available for MD-SIESTA
– Parrinello-Rahman (NP): MD with pressure contNosérolled
by the Parrinello-Rahman method. Only available for MD-
SIESTA
– Nosé Parrinello-Rahman (NPT): isothermal–isobaric ensem-
ble, where the number of atoms (N), pressure (P) and tem-
perature (T) are conserved. MD with temperature is con-
trolled by means of a Nosé thermostat and pressure con-
trolled by the Parrinello-Rahman method.
– Annealing. MD with annealing to a desired temperature and/or
pressure. Only available for MD-SIESTA

We explain below the additional settings that you can tune for each of
the algorithms listed above.

Nosé thermostat (NVT)

CHAPTER 2. ASAP WORKFLOWS 58

• Initial T. Initial temperature for the MD run. The atoms are as-
signed random velocities drawn from the Maxwell-Bolzmann dis-
tribution with the corresponding temperature. The constraint of
zero center of mass velocity is imposed. In units of K, eV or meV.

• Target temperature. Target temperature for Nosé thermostat.

In units of K, eV or meV.

• Nosé mass. Generalised mass of Nosé variable. This determines

the time scale of the Nosé variable dynamics, and the coupling of
the thermal bath to the physical system.

Parrinello-Rahman (NP)
CHAPTER 2. ASAP WORKFLOWS 59

• Initial T. Initial temperature for the MD run. The atoms are as-
signed random velocities drawn from the Maxwell-Bolzmann dis-
tribution with the corresponding temperature. The constraint of
zero center of mass velocity is imposed. In units of K, eV or meV.

• Target pressure. Target pressure for Parrinello-Rahman method.

In units of GPa, eV/Angström3 or Ry/Bohr3 .

• Parinello-Raman mass. Generalised mass of Parrinello-Rahman

variable. This determines the time scale of the Parrinello-Rahman
variable dynamics, and its coupling to the physical system.

Nosé Parrinello-Rahman (NPT)

ASAP widget for MD-ASE

CHAPTER 2. ASAP WORKFLOWS 60

• Temperature. In units of K, eV or meV.

• External stress. In units of eV/Angström3 ).

• T-time. Frequency of the temperature updates (in units of fs).

CHAPTER 2. ASAP WORKFLOWS 61

• P-time. Frequency of the pressure updates (in units of fs).

The P-factor, in units of eV/Angström3 , is automatically computed as

a function of the P-time and B-mod parameters: P-factor=P-time2 ·B-
mod.

ASAP widget for MD-SIESTA

CHAPTER 2. ASAP WORKFLOWS 62

• Initial T. Initial temperature for the MD run. The atoms are as-
signed random velocities drawn from the Maxwell-Bolzmann dis-
tribution with the corresponding temperature. The constraint of
zero center of mass velocity is imposed. In units of K, eV or meV.

• Target pressure. Target pressure for Parrinello-Rahman method.

In units of GPa, eV/Angström3 or Ry/Bohr3 .

• Nosé mass. Generalised mass of Nosé variable. This determines

the time scale of the Nosé variable dynamics, and the coupling of
the thermal bath to the physical system.

• Parinello-Raman mass. Generalised mass of Parrinello-Rahman

variable. This determines the time scale of the Parrinello-Rahman
variable dynamics, and its coupling to the physical system.

Annealing

Anneal. opt.. The annealing options are desired temperature and/or

pressure.
CHAPTER 2. ASAP WORKFLOWS 63

If the Temperature is selected, the additional settings are:

• Target temperature. Target temperature for annealing MD. In

units of K, eV or meV.

• Tau relax. Relaxation time to reach target temperature and/or

pressure in annealing MD. Note that this is a relaxation time, and
as such it gives a rough estimate of the time needed to achieve
CHAPTER 2. ASAP WORKFLOWS 64

the given targets. As a normal simulation also exhibits oscilla-

tions, the actual time needed to reach the averaged targets will
be significantly longer.

If the Pressure is selected, the additional settings are:

• Target pressure. The target pressure is achieved by velocity and

unit cell rescaling, in a given time determined by the variable Tau
relax. In units of GPa, eV/Angström3 or Ry/Bohr3 .

• Bulk modulus estimation. Estimation (may be rough) of the

bulk modulus of the system. This is needed to set the rate of
change of cell shape to reach target pressure. In units of GPa,
eV/Angström3 or Ry/Bohr3 .

• Tau relax. Relaxation time to reach target temperature and/or

pressure in annealing MD. Note that this is a relaxation time, and
as such it gives a rough estimate of the time needed to achieve
the given targets. As a normal simulation also exhibits oscilla-
tions, the actual time needed to reach the averaged targets will
be significantly longer. In units of fs and ps.

If both Temperature and Pressure are selected, the additional settings

are:
CHAPTER 2. ASAP WORKFLOWS 65

• Target temperature. The target temperature is achieved by ve-

locity and unit cell rescaling, in a given time determined by the
variable Tau relax. In units of K, eV or meV.

• Target pressure. The target pressure is achieved by velocity and

unit cell rescaling, in a given time determined by the variable Tau
relax. In units of GPa, eV/Angström3 or Ry/Bohr3 .

• Bulk modulus estimation. Estimation (may be rough) of the

bulk modulus of the system. This is needed to set the rate of
change of cell shape to reach target pressure. In units of GPa,
eV/Angström3 or Ry/Bohr3 .

• Tau relax. Relaxation time to reach target temperature and/or

pressure in annealing MD. Note that this is a relaxation time, and
as such it gives a rough estimate of the time needed to achieve
the given targets. As a normal simulation also exhibits oscilla-
tions, the actual time needed to reach the averaged targets will
be significantly longer. In units of fs and ps.

Variables

The Velocity Distribution widget is only available when selecting MD-

ASE.
CHAPTER 2. ASAP WORKFLOWS 66

The Velocity Distribution widget shows the list of elements and the
components of their velocity vectors.

The initial velocities are initially set to zero, however, they can be changed
manually. The constraint on zero center of mass velocity is imposed
automatically. Random velocities drawn by a Maxwell-Boltzmann dis-
tribution can be assigned to atoms of the system. You can set a desired
temperature in the Maxwell-Boltzmann box. Press the Initialize now
button to set up the initial velocities.
CHAPTER 2. ASAP WORKFLOWS 67

To maintain the system at the target temperature select the Force tick-
box.

Press the OK button to close the parameter widget once the parame-
ters are properly set.
Click on the Calculator icon to select the computational engine to be
used during geometry optimisation.
CHAPTER 2. ASAP WORKFLOWS 68

We refer the user to chapter 5 for further information on ASAP avail-

able calculators.

Click on the Run icon to open the Run widget. Then click on the Run
button to submit the molecular dynamics calculation. We refer the
user to chapter 6 for further information on the computational re-
sources configuration in ASAP.

After submitting a job (run), the Calculator output tab in Run widget
shows the complete calculation output in real time. In addition, the
Task output tab in Run widget shows relevant information on the Molec-
ular Dynamic output in real-time.
CHAPTER 2. ASAP WORKFLOWS 69

2.6.1 Molecular dynamics workflow: Analysis

When the calculation is completed, select Exit and analyse to open
the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 70

The MD series widget offer two plot types: Time series and Radial dis-
tribution function. At the bottom of the widget, you can find the most
important output parameters calculated during the MD run.

• hEki and hT i are the average kinetic energy and average temper-
ature, respectively. These parameters are helpful to control the
evolution of the system during dynamic run.
CHAPTER 2. ASAP WORKFLOWS 71

• h∆T 2 i is the average variation of the temperature during MD run.

This parameter shows how big the temperature fluctuations are
during the run. This measure is particularly useful while perform-
ing system analysis in the vicinity of phase transitions, when the
system is experiencing an increase of fluctuations.

• 2hT i2 /N is the averaged square temperature normalised by the

degrees of freedom (N). It is an indirect measure of specific heat.

At the right side of the MD series widget, you can visualise the geome-
try at any of the steps of the MD run.

Select View 3D to visualise the image, at the selected step, with ASE
GUI,

Click the Play button to visualise the structure evolution during the MD
run in the three dimensions.
CHAPTER 2. ASAP WORKFLOWS 72

You can visualise the results of MD as time series (y-axis) of:

• kinetic energy

• kinetic and potential. For the visualisation of both kinetic and

potential energies.
CHAPTER 2. ASAP WORKFLOWS 73

• potential energy

• pressure. The option is only available if provided by the calcula-

tor.

• temperature.
CHAPTER 2. ASAP WORKFLOWS 74

• total energy

Notice that you can modify the logging step range that will be shown
in the visualisation,
CHAPTER 2. ASAP WORKFLOWS 75

and visualise the Time series as a function of steps or time (in unit of
fs).

After editing those parameters, click on the Update the plot button,
CHAPTER 2. ASAP WORKFLOWS 76

It is also possible to visualise Radial Distribution Function (RDF). RDF

measures the probability of finding an atom at distance r (in units of
Angström) given that there is an atom at position 0. Essentially, it is a
histogram of interatomic distances.
CHAPTER 2. ASAP WORKFLOWS 77

• Num. intervals: parameter defining the sampling of the x axis.

• Maximal distance Maximal distance (rmax ) in units of Angström.

CHAPTER 2. ASAP WORKFLOWS 78

• Plot style. The options are Bars or Lines.

CHAPTER 2. ASAP WORKFLOWS 79

2.7 Equation Of State (EOS)

We have designed the Equation Of State (EOS) workflow to automate
the computation needed to fit the equation of state for bulk systems.
Starting from an approximate lattice constant, it is performed a bulk
calculation (single-point energy) for different lattice constants.

The equilibrium volume, bulk modulus and equilibrium energy of the

structure model are derived from one selected formula. For example,
the Murnaghan EOS can be used as the relationship between the vol-
ume of a body and the pressure to which it is exposed. It is one of the
CHAPTER 2. ASAP WORKFLOWS 80

many state equations used to model the behaviour of matter under

high-pressure conditions.

A EOS project starts with the definition of the atomic structure. We re-
fer the user to section 3.1 for further information on ASAP structure
builder/viewer interface.

After the atomic structure is defined, edit the type of project by se-
lecting Equation of State from the list of possible project types imple-
mented in ASAP.

Then click on the Parameters icon to open the Equation of State param-
eters widget.
CHAPTER 2. ASAP WORKFLOWS 81

The project parameters that can be tuned are:

• Number of images. The different configurations are created by

interpolating the initial and final volume.

• Lattice constant variation (%). Parameter to select the volume

range.

To compute the Equation of State, a series of single-point calculations

are performed. Click on the Calculator icon to select the computational
engine used for those single-point calculations.

We refer the user to chapter 5 for further information on ASAP avail-

able calculators.

Click on the Run icon to open the Run widget. Then click on the Run
button to execute the Equation of State workflow.
CHAPTER 2. ASAP WORKFLOWS 82

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

After the EOS workflow is started, the tab Calculator output in Run wid-
get shows the complete EOS workflow output in real time.
CHAPTER 2. ASAP WORKFLOWS 83

In addition, the tab Task output shows the energy of each of the single-
point calculations being part of the EOS workflow.

After the calculation is completed, click on the Exit and analyse button
to open the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 84

2.7.1 Equation Of State workflow: Analysis

It is also possible to open widget analysis EOS by selecting Analyse icon

associated with a completed project.

In the left panel of the EOS analysis widget, the figure shows the en-
ergy of each of the single-point calculations represented as a function
CHAPTER 2. ASAP WORKFLOWS 85

of the crystal volume. The user can select different formulas for fitting
the data.

The equilibrium volume, bulk modulus and equilibrium energy of the

structure model are derived from the selected formula.

The right panel of the EOS analysis widget shows information of the
crystal unit cell.
CHAPTER 2. ASAP WORKFLOWS 86
CHAPTER 2. ASAP WORKFLOWS 87

2.8 Nudged Elastic Band (NEB)

ASAP facilitates all the steps involved in the workflow of running Nudged
Elastic Band (NEB) simulations with a selected calculator.

NEB is an optimisation method used for finding saddle points (transi-

tion state) and Minimum Energy Paths (MEP) between known reactants
(initial state) and products (final state). The method involves construct-
ing and optimising a selected number of intermediate images along
the reaction path. Each image finds the lowest energy possible while
maintaining equal spacing to neighbouring images.

The reaction path connects the several chemical species that evolve
during the reaction process. The connection between the chemical
species is defined as the trajectories that an ensemble of molecular/atoms
travels through the PES (Potential Energy Surface) at a given tempera-
ture until the reaction is completed. The path called MEP is obtained
by the restriction of the study to one molecule, one stationary point
and one valley of reaction without the effect of temperature. With this
restriction, the reaction path can be associated as the path by which
stationary points (initial and final states) are connected through the
lowest energy valley in the PES. The transition state of a chemical re-
action is a particular configuration along the reaction coordinate; the
state corresponding to the highest potential energy along the MEP.

In summary, the basic steps involved in a NEB simulation are:

- Starting a NEB project, see subsection 2.8.1.
- Construction of initial and final configurations, see subsection
2.8.2.
- Geometry optimisation of initial and final configurations, see sub-
sections 2.8.3 and 2.8.4.
- Interpolation of a selected number of intermediate images along
the reaction path, see subsection 2.8.5.
- Configuration of NEB: View and edit NEB images. Set up NEB and
optimisation parameters. See subsection 2.8.6.
- NEB optimisation, see subsection 2.8.7.
- NEB analysis, see subsection 2.8.8.
CHAPTER 2. ASAP WORKFLOWS 88

2.8.1 Starting a NEB project

A NEB project is started by first selecting two projects in the project
tray, and then right-click to select the option New NEB project. . .

The configuration contained in the first selected project is taken as the

initial state for the NEB. The configuration contained in the second se-
lected project is considered as the final state.

As an alternative, a NEB project can be started by selecting a single

project. In this case, the selected configuration is considered as the
initial and final state for the NEB. Initial and final configurations can be
edited afterwards.
CHAPTER 2. ASAP WORKFLOWS 89

2.8.2 Editing initial and final geometries

A widget to edit initial and final geometries is automatically opened
after the creation of a new NEB project. This widget facilitates to edit
independently both initial and final geometries.
CHAPTER 2. ASAP WORKFLOWS 90

Press the button Mirror final (Mirror initial) to use the initial (final)
structure as a starting geometry to the final (initial) one.
CHAPTER 2. ASAP WORKFLOWS 91

Press the button Swap initial and final to swap initial and final ge-
ometries.
CHAPTER 2. ASAP WORKFLOWS 92

We refer the user to section 3.1 for further information on the ASAP
structure builder/viewer interface.

Press OK button after both initial and final geometries are suitable set.
A new project is automatically created in the project tray.

2.8.3 NEB workflow: The NEB project tree

The created project contains two separately sub-projects with the ini-
tial and final geometries previously set.
CHAPTER 2. ASAP WORKFLOWS 93

Geometry optimisation of initial and final geometries is a requirement

for running a NEB in ASAP.

2.8.4 NEB workflow: Geometry optimisation of initial

and final configurations
To perform geometry optimisation of initial and final geometries, edit
the project parameters (Parameters icon),

the calculator and calculator parameters (Calculator icon),

and run the geometry optimisation of each of the two sub-projects of

the project tree.

We refer the user to section 2.5 for further information on geometry

optimisation with ASAP.
CHAPTER 2. ASAP WORKFLOWS 94

2.8.5 NEB workflow: Interpolation of intermediate im-

ages
After performing geometry optimisation of initial and final geometries,
select the main NEB project and right-click to select Interpolate NEB
images.

Interpolation of NEB images is only possible after performing geome-

try optimisation of both initial and final geometries.

Use the pop-up window to select a number of intermediate geometries

(images) along the reaction path between the initial and the final state.
CHAPTER 2. ASAP WORKFLOWS 95

ASAP offers two alternatives to generate a guess:

• Linear interpolation. It is the most simple approach. It is used

linear interpolation of the atomic coordinates.

• Image dependent pair potential interpolation (idpp). A method

that has been developed to provide an improvement to the initial
guess for the NEB path. S. Smidstrup, A. Pedersen, K. Stokbro
and H. Jonsson, Improved initial guess for minimum energy path
calculations, J. Chem. Phys. 140, 214106 (2014).

Select one of the two alternative interpolation methods and press the
button OK. A new sub-project is added to the NEB project tree. It is the
project where the NEB simulation will be executed.

2.8.6 NEB workflow: NEB configuration

Click on the Parameters icon to open the NEB parameters widget.
CHAPTER 2. ASAP WORKFLOWS 96

This widget allows for editing and visualising the NEB images. It also
allows for selecting NEB and Optimiser parameters.

Press the button Edit current image... to edit any of the interpolated
NEB images.
CHAPTER 2. ASAP WORKFLOWS 97

Press the button View all in 3D... to visualise NEB images in three
dimensions.
CHAPTER 2. ASAP WORKFLOWS 98

NEB workflow: NEB parameters

ASAP can make use of three different implementations of the NEB

method:

• aseneb: Standard NEB implementation.

• improvedtangent: A modification of the NEB for finding min-

imum energy paths. One of the images is made to climb up
along the elastic band to converge rigorously on the highest sad-
dle point. Also, variable spring constants are used to increase the
density of images near the top of the energy barrier to get an im-
proved estimate of the reaction coordinate near the saddle point.
Method reported by G. Henkelman and H. Jonsson, Chem. Phys,
113, 9978 (2000). https://doi.org/10.1063/1.1323224

• eb: Full spring force implementation. The method reported by E.

L. Kolsbjerg, M. N. Groves, and B. Hammer, J. Chem. Phys, 145,
094107 (2016) https://doi.org/10.1063/1.4961868.
CHAPTER 2. ASAP WORKFLOWS 99

Besides, the user has the possibility of selecting the following options:

• Climb image. The climbing image is a small modification to the

NEB method. This variation involves designating a specific image
to behave differently to the rest of the chain. The selected image
does not feel spring forces, and the component of the potential
force parallel to the chain is reversed, such that it moves towards
the saddle point. In general, the climbing image is not turned
on until some iterations have been run without it (generally 20 %
to 50% of the total number of iterations). It allows the adjacent
images to provide a reasonably good approximation of the cor-
rect tangent at the location of the climbing image. The required
number of iterations before the climbing image is not turned on
depends on the adjacent images providing a reasonably good ap-
proximation of the correct tangent at the location of the climbing
image.

• Parallel Parallelisation over the images of a NEB calculation

• Dynamic relaxation The convergence of images is often non-

uniform, and a significant fraction of computational resources
can be spent calculating images that are below the convergence
criterion. With a dynamic optimisation method, the convergence
of each image is carefully monitored. An image is only optimised
if the norm of the forces acting on the image is above the conver-
gence criterion. The list of the maximum forces on the images is
updated every force call; if a previously converged image goes out
of tolerance (due to spring adjustments between the image and
its neighbours), it will be optimised again. Dynamic optimisation
is only efficient working in series.

• Spring constant Parameter controlling the spring forces added

along the band between images to perform the constrained opti-
misation when running a NEB.

Optimiser parameters

Select one of the possible algorithms to perform the optimisation. Se-

lect also the maximum force (force on all individual atoms) for the con-
vergence criterion.
CHAPTER 2. ASAP WORKFLOWS 100

2.8.7 NEB workflow: NEB Optimisation

Click on the Calculator icon to open the Calculator widget.

We refer the user to Section 5 for further information on the Calculator

widget.

Click on the Run icon to open the Run widget.

CHAPTER 2. ASAP WORKFLOWS 101

Select Run button to run the NEB simulation.

We refer the user to Section 6 for further information on the Run wid-
get.

2.8.8 NEB workflow: NEB Analysis

After the successful completion of a NEB project, press the Exit and
analyse button to open the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 102

Click on the Nudged elastic band button. The analysis widget will be
opened.

The left panel of the analysis widget contains information of all NEB
converged images. Use the right (left) arrow button to play them for-
ward (backward). Select View current image..., to view the current
image in three dimensions.
CHAPTER 2. ASAP WORKFLOWS 103

Select View all in 3D... to visualise all NEB converged images in three
dimensions.

The right panel of the analysis widget shows the total energy of each
converged image represented as a function of the reaction path. The
reaction path is the continuous path connecting reactants with prod-
ucts that has been optimised by the NEB.

The following information is displayed on top of the figure,

• Ea : Activation energy of the forward barrier (eV). The energy bar-

rier is estimated based on the interpolated fit to the images.

• Er : Raw energy of the transition state (eV).

• ∆E: Reaction energy (eV).

CHAPTER 2. ASAP WORKFLOWS 104

Use right click on top of the figure to:

• Save plotting script.... Save the python script used to plot the fig-
ure.

• Show in Matplotlib.... Matplolib library allows the user an interac-

tive visualisation of the NEB figure (scale axis, zoom on specific X
and Y values ...).
CHAPTER 2. ASAP WORKFLOWS 105

• Save figure.... The supported formats are eps, pdf, pgf, png, ps,
raw, rgba, svg, svgz.

2.9 Vibrations
In this type of project, the vibrational modes are calculated from a fi-
nite difference approximation of the Dynamical matrix.

The project starts with the definition of the atomic structure. We re-
fer the user to section 3.1 for further information on ASAP structure
builder/viewer interface.

After the atomic structure is defined, edit the type of project by select-
ing Vibrations from the list of possible project types implemented in
ASAP.
CHAPTER 2. ASAP WORKFLOWS 106

Then click on the Parameters icon to open the Vibration parameters

widget.
CHAPTER 2. ASAP WORKFLOWS 107

The project parameters that can be tuned are:

• Number of points. Number of displacements per atom and carte-

sian coordinate. The number of displacements supported are 2
and 4.

– Number of points 2: Displacement of each atom by the val-

ues +∆ and -∆ for each cartesian coordinate.
– Number of points 4: Displacement of each atom by the val-
ues +∆, +two times ∆, -∆, and -two times ∆ for each carte-
sian coordinate.

Notice that the displacement is applied to each atom in the con-

figuration. When performing a vibration project, one may wish to
keep some degrees of freedom in the system fixed. We refer the
user to section 3.2 for information of setting constraints.

• Displacement magnitude h (Å). Parameter giving the magni-

tude of displacements. Unit: Å

Click on the Calculator icon to select the computational engine to be

used during vibration calculation.
CHAPTER 2. ASAP WORKFLOWS 108

We refer the user to chapter 5 for further information on ASAP avail-

able calculators.

Click on the Run icon to open Run widget. Then press the Run button
to submit the vibration calculation.

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

After submitting a job, the tab Calculator output in Run widget shows
the complete calculation output in real time.
CHAPTER 2. ASAP WORKFLOWS 109

In addition, the tab Task output in Run widget shows relevant informa-
tion of Vibration output in real-time.
CHAPTER 2. ASAP WORKFLOWS 110

2.9.1 Vibrations workflow: Analysis

When the calculation is completed, select Exit and analyse to open
the analysis widget.

Different information can be analysed after a successful run of a vibra-

tion project.
CHAPTER 2. ASAP WORKFLOWS 111

Density of vibration modes

The density of vibrational modes is defined by Density(w) = i δ(w −
P

Ei ), where w is frequency at which the density of vibrational modes is

computed, the sum runs over vibrational modes i, Ei is frequency of
the vibrational mode i. δ(w) is the Dirac δ-function.
CHAPTER 2. ASAP WORKFLOWS 112

The parameters that can be tuned in the density of vibrational modes

representation are:

• Method. Gaussian or Lorentzian representations of the Dirac δ-

function.

• Minimum and Maximum. They are the start and end values of
the Gaussian/Lorentzian in eV.

• Width at half maximum. Broadening defined by the full-width-at-

half-maximum in both representations (Gaussian and Lorentz) of
the δ-function.

Vibration modes
This analysis option provides the list of the computed vibrational modes
and their corresponding energies. The zero point vibrational energy
(ZPVE) is also provided.
CHAPTER 2. ASAP WORKFLOWS 113

To see an animation of one of the computed vibrational modes, select

it first from the list, and then click on the View animation in 3D editor
button. The following settings can be tuned before viewing the anima-
tion:

• Magnitude: Temperature (in K) associated to the energy (E(ν)) of

the selected vibrational mode.

• Force scale: Parameter only available when Set scale manually

tick-box is activated

• Number of images: Number of images that will be included in the

animation.
CHAPTER 2. ASAP WORKFLOWS 114

Play the movie to visualise the animation of the selected vibrational

mode.

We refer the user to section 3.2 for further information on the features
implemented in ASE GUI.
CHAPTER 2. ASAP WORKFLOWS 115

2.10 Phonons
We have designed the Phonon workflow to automate the computation
and analysis of phonons of a periodic system.

This type of project starts with the definition of the atomic structure.
We refer the user to section 3.1 for further information on ASAP struc-
ture builder/viewer interface.

After the atomic structure is defined, edit the type of project by se-
lecting Phonons from the list of possible project types implemented in
ASAP.
CHAPTER 2. ASAP WORKFLOWS 116

Then click on the Parameters icon to open the Phonon parameters wid-
get.

You can tune the following project parameters:

• Supercell shape. Supercell size used to calculate the force con-

stant matrix. Check Symmetric box to build a symmetric super-
cell.

• Displacement magnitude. The distance the atoms are displaced

to calculate the force constant matrix. Select units between Ang,
nm or Borh.
CHAPTER 2. ASAP WORKFLOWS 117

Click on the Calculator icon to select the code.

We refer the user to chapter 5 for further information on ASAP avail-

able calculators.

Click on the Run icon to open the Run widget.

We refer the user to chapter 6 for further information on computa-

tional resources configuration in ASAP.

Click on the Run button to execute the calculation. Please be aware

that phonon calculations with SIESTA may take a significant amount of
time to complete.
CHAPTER 2. ASAP WORKFLOWS 118

2.10.1 Phonon workflow: Analysis

After the Phonon calculation is completed, click on the Exit and anal-
yse button to open the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 119

It is also possible to open the analysis widget by selecting the Analyse

icon associated with a completed project,

By default, the analysis widget only shows the Phonon Band Structure.
CHAPTER 2. ASAP WORKFLOWS 120

The energy unit (Y-axis) used by default is cm−1 . You can change it to
meV or THz with the parameter Frequency units.

If you want to add new points to the band path, click on the button Edit
band path.... The widget shows the unit cell Brillouin zone, the band
path and the high symmetry k-points.

ASAP recognises the lattice type for a few Bravais lattice types. In this
case, the high symmetry k-points are labelled automatically. The auto-
matic k-point labelling currently supports the following Bravais lattice
types:

• Primitive cubic
CHAPTER 2. ASAP WORKFLOWS 121

• Face-centred cubic (fcc)

• Body-centred cubic (bcc)

• Primitive tetragonal

• Body centred tetragonal

• Primitive orthorhombic

The widget also provides the following information:

• Lattice. Bravais lattice type.

• Special points. The high symmetry k-points.

• Number of k-points. The total number of k-points that will be

used along the whole selected k-path.
You can edit the parameter Sampling density to modify the density of
the k-points.

Click the button Append point to add a new k-point to the band path.
Then, edit the k-point coordinates and label and add the new label to
CHAPTER 2. ASAP WORKFLOWS 122

the path.

Press the button OK and click on the button Replot to update the fig-
ure.

To visualise Density Of States in the same figure, click in the tab Den-
sity of states, check Plot density of states box and click on the button
Replot.
CHAPTER 2. ASAP WORKFLOWS 123
CHAPTER 2. ASAP WORKFLOWS 124

Notice that the energy unit (Y-axis) is cm−1 . You can change it to meV
or THz with the parameter Frequency units.

You can also tune the following parameters:

• Brillouin zone sampling: Number of k-points used to plot the

DOS.

• Full width at half maximum (FWHM): The distance used be-

tween the calculated points to perform the smearing.

• Smearing: Gaussian or Lorentzian distribution.

CHAPTER 2. ASAP WORKFLOWS 125

2.11 Interfacial energy tool (IET)

ASAP provides a flexible GUI to facilitate all the steps involved in the
workflow of computing the energy (single-point calculation) of a set of
systems built out of two subsystems placed at different relative dis-
tances (d).

An Interfacial energy tool (IET) project starts defining the two atomic
structures of the subsystems. We refer the user to section 3.1 for fur-
ther information on the ASAP structure builder/viewer interface.

To create a new IET project, select two existing projects in the project
tray containing the desired subsystems,

then, right-click to select the option Merge two structures to merge

the two selected subsystems into one.
CHAPTER 2. ASAP WORKFLOWS 126

The widget offers the possibility of visualising the system from differ-
ent views (View angles).

You can decide to Keep constrains of the existing systems, Fix or Re-
lease the position of the atoms of the first and second subsystem.

You can also indicate the relative distance (in x, y or z direction) be-
tween the two subsystems.

Additionally, you can also choose the Unit cell: Unit cell of the first
subsystem, Unit cell of the second subsystem, No unit cell or Minimal
unit cell. Finally, thick the wrap atoms into the unit cell checkbox to
bring the coordinates back to the unit cell. The periodicity of the cur-
rent unit cell is assumed.

Press the OK button to merge the two systems following your specifi-
cations, and edit the type of the project by selecting Interfacial energy
tool from the list of possible project types implemented in ASAP.
CHAPTER 2. ASAP WORKFLOWS 127

ASAP will open a window showing the composition of the interface:

CHAPTER 2. ASAP WORKFLOWS 128

Press the Yes button to proceed.

Then click on the Parameters icon to open the Parameter widget. No-
tice that for this type of project, only settings options are available.
CHAPTER 2. ASAP WORKFLOWS 129

The settings widget associated with a IET type of project offers the fol-
lowing options:

• Energy definition: The available options are

– Total energy: Total energy of the system provided directly

by the calculator.
– Interaction energy: The interaction energy defined as

∆E = E(AB)ab − E(A)ab − E(B)ab (2.1)

is calculated. E(AB)ab is the energy of the whole system (AB)

while E(A)ab and E(B)ab are the energy of the first and sec-
ond subsystems, respectively, computed using a mixed basis
set (ghost atoms).

• Distances, out of plane: Minimum and maximum relative dis-

tance between the two subsystems.

• Shifts, in-plane: Number of points to be sampled on the surface

in the x and y directions. Check the tick-box Randomise to make
a random sampling of the surface.

Press the Export to PDBs... button to export the set of built systems
as a set of PDB images.
CHAPTER 2. ASAP WORKFLOWS 130

Press the OK button to close the IET widget once the parameters are
properly set.

Click on the Calculator icon to select the computational engine to be

used during geometry optimisation. We refer the user to chapter 5 for
further information on the available calculators in ASAP.

Click on the Run icon to open the Run widget.

Then click on the Run button to submit the previously defined set of
calculations. We refer the user to chapter 6 for further information on
the computational resources configuration in ASAP.
CHAPTER 2. ASAP WORKFLOWS 131

After submitting a job (run), the Calculator output tab in the Run widget
shows the complete calculation output in real time.

In addition, the Task output tab in the Run widget shows relevant infor-
mation on the IET output in real-time. It indicates the images for which
the energy has already been computed.

2.11.1 Interfacial Energy Tool workflow: Analysis

When the calculation is completed, select Exit and analyse to open
the analysis widget.
CHAPTER 2. ASAP WORKFLOWS 132

The analysis widget shows the visualisation of the energy for each of
the calculated systems.

Click the Fit check box to fit the curve to the Morse potential equation
CHAPTER 2. ASAP WORKFLOWS 133

and to compute the Morse parameters.

Press the Definition button to get information on the interatomic in-

teraction Morse potential model.
CHAPTER 2. ASAP WORKFLOWS 134

Click the Definition lines check box to visualise the relevant quantities
in the figure.

Select View current image... to view the current image in three di-
mensions. And select View all in 3D... to visualize all IET images in
three dimensions.

Press the Export energies... button to export the data from the figure
to a text file format.
CHAPTER 2. ASAP WORKFLOWS 135

Press the Export to PDBs... button to export the set of built systems
as a set of PDB images.

Right-click on top of the figure to:

• Save figure as.... The supported formats are .pdf, .png, .jpg, .jpeg,
.ps, eps, svg.

• Open in Matplotlib.... Matplolib library allows the user an interac-

tive visualisation of the figure (scale axis, zoom on specific X and
Y values...).

• Save a Matplotlib script as.... Save the Matplotlib script used to plot
the figure.
Chapter 3

The atomic structure builder

3.1 Structure Modeling in ASAP

3.1.1 Opening a new project
A ASAP project starts with defining the atomic structure.

You can import pre-existing structures from a wide variety of file for-
mats. In this way, you can bring information on species and geometry
data into ASAP by uploading a variety of format files:

• XYZ (usually including atom numbers, element symbols and X, Y,

and Z coordinates).

• CIF (standard text file format for representing crystallographic in-

formation).

• STRUCT_OUT (SIESTA output file with cell vectors in and atomic

positions in fractional coordinates).

These are just a few examples of the many format files that ASAP can
read.

136
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 137

As an alternative, you can create the atomistic model using the struc-
ture builder/viewer interface. It allows you to construct molecular, bulk
systems and surfaces importing structures from the database and us-
ing built-in functions for structure modelling implemented in ASAP. We
have also implemented widgets for the construction of nanotubes and
nanoparticles.
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 138

3.1.2 Structure builder/viewer interface

Molecules

The molecule widget allows you to upload molecules from a list of

known molecular structures included in ASAP databases. First, you
can select the database from a drop-down menu. For each database,
we indicate the DOI to the relevant article. Next, you can choose the
molecule of interest.

Bulk

You can use the bulk widget to easily create the most common crystal
structures with arbitrary orientation and elements. You can select an
element from the periodic table (single click on the desired element).
The cell parameter is automatically updated to reference value for the
selected element.
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 139

As an alternative, you can manually type the element name and its
crystal structure. In this case, the specification of correct lattice con-
stants is user responsibility. The bulk widget automatically shows the
cell vectors associated with the indicated lattice parameters. Available
options include the possibility for the user to select among, primitive,
orthorhombic and cubic cell structure and the cell parameter.

Surface

The surface widget facilitates the construction of complex slabs.

CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 140

Press the Choose bulk structure... button to build the surface from
the bulk structure (using the bulk widget described above).
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 141
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 142

Press the OK button to close the bullk widget after the parameters are
properly set.

The surface widget offers the following options:

• Miller index. Miller indices determine the orientation of a sur-

face. The parallel crystallographic plane is defined by the integer
numbers (hkl). You can specify the desired Miller index along the
three axes of the simulation cell. The smallest periodic structure
fulfilling this specification is created.

• Layers. You can indicate the number of equivalent layers of the

slab.

• Repeat in plane. To indicate the number of repetitions of the

unit cell in x and y directions.

Click the Use vacuum check box to add vacuum in the z direction. Crys-
tal surfaces are periodic in two dimensions (x and y in ASAP). Because
periodic boundary conditions are intrinsic to SIESTA, vacuum must be
added in the non-periodic direction (z). The vacuum should be chosen
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 143

large enough to avoid spurious interactions between periodic images.

The visualisation of the surface, on the right side of the surface wid-
get, will automatically update as the Miller index, Layers or Repeat
in plane are changed.

Press the OK button to close the surface widget after the parameters
are properly set.
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 144

Nanotube

You can use this widget to create a single-walled nanotube.

CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 145

You can tune the following parameters:

• Chemical symbol: chemical element to construct the nanotube
from: C or Si
• Chiral indices: the two components of the wrapping vector (n,m)
that define the diameter and chiral angle of a nanotube.
• Linear extent: number of unit cells.
• Vacuum length: vacuum added in the non-periodic direction (z).
• Bond length: bond length between neighbouring atoms.

Nanoparticle

You can use this widget to create an icosahedral nanoparticle (cluster)

by specifying the number of layers in z direction.
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 146

You can tune the following parameters:

• Chemical symbol: the chemical element to construct the nanopar-

ticle. Select an element from the periodic table (single click on
the desired element) or the provided list. The lattice constant is
automatically updated to the reference value for the selected el-
ement.

• Lattice constant in units of Angström, Bohr or nm.

• Number of shells: number of layers in one direction.

3.2 ASE GUI in ASAP

ASAP is using a number of features implemented in ASE GUI. Those
features are described in this section.

3.2.1 Visualisation
Visualising a system with ASE GUI is straight-forward using a regular
mouse,
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 147

• The left mouse button to selects atoms

• The right mouse button to rotate atoms

• The middle button to translate the system on the screen

3.2.2 Measuring geometric quantities

Depending on the number of selected atoms, ASE GUI automatically
measures different quantities:

• Single atom: xyz position and atomic symbol left mouse button
to selects atoms

• Two atoms: interatomic distance and symbols

• Three atoms: all three internal angles and symbols

• Four atoms, selected sequentially: the dihedral angle, e.g. the

angle between bonds 12 and 34

• More than four atoms: chemical composition of selection

3.2.3 Structure Manipulation

Edit
The possible options are:

• Select all

• Invert selection

• Select constrained atoms. Constrains may be modified in Tools/settings

• Select immobile atoms

• Hide selected atoms

• Show selected atoms

• Modify. To allow modification of the atomic symbol, an attached

tag, or its magnetic moment

• Add atoms. To add single atoms to an existing structure

CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 148

• Delete selected atoms

• Edit cell. To edit cell vectors, and cell periodicity.

View

• Show unit cell

• Show axes

• Show bonds

• Show velocities. Currently disabled

• Show forces. Option only available after completion of geometry

optimisation project

• Show Labels. The options are: atom index, magnetic moments,

element symbol and initial charges

• Settings. Basic view settings

– Constraints.
– Visibility. To mark selected atoms as invisible
CHAPTER 3. THE ATOMIC STRUCTURE BUILDER 149

– Miscellaneous: scale atomic radii, force vectors and velocity

vectors

Tools

• Movie. Allows to play the current trajectory as a movie using a

number of different settings. Option only available after comple-
tion of geometry optimisation project

• Constraints. To set (or remove) constraints based on the currently

selected atoms

• Render scene. Currently disabled

• Move selected atoms. Allows selected atoms to be moved using

the arrow keys. The direction is always parallel to the plane of the
screen. Two possible movements are available:

– pressing the arrow keys: atoms will move by 0.1 Å

– shift + arrow keys: atoms will move by 0.01 Å

• Rotate selected atoms

Chapter 4

Parameters

Select a project in the project tray, and click on the Parameters icon to
open the Parameters widget.

You can use the Parameter widget to:

• Set up the input parameters related to the different type of projects
(Settings). See section 4.1.

150
CHAPTER 4. PARAMETERS 151

• Edit the masses, magnetic moments and atomic positions of the

system (Variables). See section 4.2.

• Set up the input parameters requiered to compute the target ma-

terial properties of your calculation (Properties). See section 4.3.

4.1 Settings
In the left side menu of the Parameters widget, select the Settings op-
tion. The input parameters you can introduce on this widget depend
on the project type.

• Geometry optimisation. See section 2.5.

• Equation Of State. See section 2.7.

CHAPTER 4. PARAMETERS 152

• Nudged Elastic Band. See section 2.8.

• Vibrations. See section 2.9.

CHAPTER 4. PARAMETERS 153

• Phonons. See section 2.10.

CHAPTER 4. PARAMETERS 154

4.2 Variables
In the left side menu of the Parameters widget, select the Variables op-
tion. You can use it to edit widget atom positions, magnetic moments,
atomic masses and velocities.

• Atom positions
Select Atom positions to see information on the x, y and z coordi-
nates (unit of Angström). Notice that the list of the atom indices
starts at 0. You can change it to 1 by double-clicking in the index
column.
CHAPTER 4. PARAMETERS 155

You can also use this widget to edit the atomic positions.

To add a new atom to the atomic structure, specify first the sym-
bol of the chemical element and then press the Add atom button.
Or click the ... button to choose the chemical element from the
dialog list and then press the Add atom button.

You can edit the atomic positions of the new atom.

CHAPTER 4. PARAMETERS 156

Click the Show constraints button to set up the constraints (i.e.

keep some degrees of freedom in the system fixed). You can add
constraints in any set of cartesian directions.
CHAPTER 4. PARAMETERS 157

• Magnetic moments
Select the Magnetic moments variable to see and edit the magnetic
moment of the atoms.

Open the Spin Dialog to modify the polarisation of your system.

CHAPTER 4. PARAMETERS 158

The available options are:

– collinear. To perform a calculation with collinear spin (two

spin components).
– non-collinear. To perform a calculation with non-collinear
spin (four spin components), up-down and angles.

To set the magnetic moment of a set of atoms to a specific value,

select in the magnetic moment column of all of them and edit one
CHAPTER 4. PARAMETERS 159

of the values. The magnetic moment of the rest of the selected

atoms will be automatically set to the same value.

Moreover, it is possible a batch selection/deselection of atoms ac-

cording to their chemical species by double-clicking in the Symbol
column.

• Atomic masses
The table contains information on atom index, atomic symbol
and mass (atomic mass Unit) for each of the atoms in your sys-
tem. You can edit the mass of any of the atoms on the list.
CHAPTER 4. PARAMETERS 160

Click the Use recommended averages button to set the recom-

mended average masses for each atom. By default these values
will be chosen. It can be changed one by one double-clicking on
the Mass column.

In order to change the masses of all the atoms of the same chem-
ical species at once, press the Set masses by species button.

Use double-click on the field labelled Isotopes if you want to choose

an isotope for the selected atom.
CHAPTER 4. PARAMETERS 161

4.3 Properties
In the left side menu of the Parameters widget, select the Properties
option. Then, you can edit the parameters required to compute the
target electronic material properties of your calculation. You can select
the following properties:

• Band structure

• Electronic Density Of States (DOS) and Projected Density Of States

(PDOS)

• Local Density Of States (LDOS)

CHAPTER 4. PARAMETERS 162

4.3.1 Band structure

Click on the Band Structure Property to see the band structure widget.

The left panel of the band structure widget shows the unit cell’s Bril-
louin zone. At the bottom of the figure, there are several entries:

Lattice
CHAPTER 4. PARAMETERS 163

The lattice type is recognised for a few Bravais lattice types. In that
case, several common k-points are labelled automatically. The auto-
matic k-point labelling currently supports the following Bravais lattice
types:
• Primitive cubic
• Face-centred cubic
• Body-centred-cubic
• Primitive tetragonal
• Primitive hexagonal
• Body centered tetragonal
• Primitive orthorhomobic
Number of k-points.

You can enter here the exact number of k-points that will be used along
the automatically defined k-path. The sampling density is updated af-
ter pressing the button Plot.

At the right panel of the band structure widget, there are indicated the
high-symmetry points k-points of the unit cell’s Brillouin zone.
Click the button Append point to add new k-points to the band path if
desired.
CHAPTER 4. PARAMETERS 164

Use doble-click on each of the added k-points to edit k-point coordi-

nates and label.

To incorporate the new labels to the path, add a string consisting of

high-symmetric points labels in the field Band path.

After pressing the Plot button, the figure showing the unit cell’s Bril-
louin zone is automatically updated.
CHAPTER 4. PARAMETERS 165

4.3.2 Electronic Density Of States and Projected Den-

sity Of States
Click on the Electronic DOS & POS Property to see the widget containing
the parameters needed to compute DOS and PDOS.

The widget has the following entries:

CHAPTER 4. PARAMETERS 166

• Energy units. To select the energy units.

• Minimum energy. Minimum energy for which DOS and PDOS

will be evaluated.

• Maximum energy. Maximum energy for which DOS and PDOS

will be evaluated.

• Full width at half maximum. The distance used between the

calculated points to perform the smearing.

• Brillouin zone sampling. Number of k-points used to generate

DOS and PDOS.

Press OK button to close the DOS and PDOS widget after the parame-
ters are properly set.
CHAPTER 4. PARAMETERS 167

4.3.3 Local density of states

Local Density Of States (LDOS) describes a space-resolved density of
states. The LDOS is useful in inhomogeneous systems. For example: a
slab will have a different band structure on the surface than in the bulk
region. LDOS is also useful when interpreting the data from a scanning
tunnelling microscope (STM), since this method is capable of imaging
electron densities of states with atomic resolution.

The computation of LDOS requires using of a SIESTA version compiled

with NetCDF library.

Click on the Local density of states Property to see the widget containing
the parameters needed to compute LDOS.
CHAPTER 4. PARAMETERS 168

The widget will show the computed DOS if you start from a previously
completed calculation. It will help you to decide the relevant energy
range for LDOS computation. You can tune the following parameters
related to DOS visualisation:

• Smearing: Gaussian or Lorentzian representations of the Dirac

delta function.

• FWHM: The full width at half maximum. It is the distance used

between the calculated points to perform the smearing. Click on
the Zero at Fermi level check box to center DOS at the fermi
level.

• Minimum: Minimum energy for DOS visualisation.

• Maximum: Maximum energy for DOS visualisation.

If you want to compute LDOS starting from a new calculation, you can
still select the minimum and maximum energy in eV for which LDOS
will be evaluated.
CHAPTER 4. PARAMETERS 169

Press the OK button to save and close the Parameters widget.

Chapter 5

Calculators

Calculator is the name of the GUI designed to select the computational

engine and help the user to properly prepare the input file.

ASAP 2022.1 implements the EMT calculator and the SIESTA calculator.

170
CHAPTER 5. CALCULATORS 171

5.1 The EMT Calculator

ASAP 2022.1 incorporates the Effective Medium Theory (EMT) calcula-
tor as implemented in Atomic Simulation Environment (ASE). EMT
CHAPTER 5. CALCULATORS 172

This implementation is incorporated in ASAP only for test and demon-

stration purposes. The EMT implementation supports the following
standard metals: Al, Cu, Ag, Au, Ni, Pd and Pt. For those elements, the
EMT parameters are quite realistic for many purposes. H, C, N, O are
supported but are NOT well described by EMT.

The potential takes a single argument, fixed cutoff. If this option is

selected the cutoff is chosen from the largest atom in the parameter
table. If it is unselected the global cutoff is chosen from the largest
atom present in the simulation.
CHAPTER 5. CALCULATORS 173

5.2 The SIESTA Calculator

SIESTA (Spanish Initiative for Electronic Simulations with Thousands of
Atoms) is both a method and its computer program implementation,
to perform efficient electronic structure calculations of molecules and
solids.

SIESTA’s efficiency stems from the use of strictly localised basis sets
and from the implementation of linear-scaling algorithms which can
be applied to suitable systems. A very important feature of the code
is that its accuracy and cost can be tuned in a wide range, from quick
exploratory calculations to highly accurate simulations matching the
quality of other approaches, such as plane-wave and all-electron meth-
ods.

You can find further information on SIESTA code in siesta webpage.

Here, we offer a discussion forum for SIESTA users.

Starting in the Spring of 2016, with the 4.0 version, SIESTA is released
under the terms of the GPL open-source license. You can download
SIESTA code at this website.

ASAP 2022.1 facilitates the creation of the input file for SIESTA 4.0 and
SIESTA 4.1
CHAPTER 5. CALCULATORS 174

You can specify key input variables through the SIESTA calculator graph-
ical user interface.

ASAP 2022.1 classifies SIESTA parameters in the following categories:

CHAPTER 5. CALCULATORS 175

• Physics: It aggregates parameters related with exchange correla-

tion functional and spin. See 5.2.1.

• Convergence: Real-space mesh cutoff energy and Brillouin Zone

Sampling. See 5.2.2.

• Basis set and Pseudopotentials. See 5.2.3.

• SCF. It aggregates parameters controlling Self Consistent Field (SCF)

convergence. See 5.2.4.

Click the Advanced properties button to enable advanced input pa-

rameter widget for all categories.

The SIESTA calculator also allows to preview and edit the SIESTA input
file, see sections 5.2.5 and 5.2.6.

5.2.1 SIESTA Parameters: Physics

This category has the following entries:

Exchange-correlation functionals
You can select one of the offered functional to specify the exchange-
correlation functional type. The available options are:

− LDA (Local Density Approximation)

− GGA (Generalised Gradient Approximation)

− VDW (Van der Waals)

CHAPTER 5. CALCULATORS 176

ASAP 2022.1 offers different options for the particular parametrisation

of each of the available exchange-correlation functionals.
CHAPTER 5. CALCULATORS 177

Spin multiplicity and total Spin Value You can choose to run a spin
unpolarised or spin polarised calculation.

Select the option non-polarised to perform a spin-unpolarised calcu-

lation (calculation with spin-degeneracy -only one component-).

For the spin polarised calculation, the available options are:

• collinear. To perform a calculation with collinear spin (two spin

components).

• non-collinear. To perform a calculation with non-collinear spin

(four spin components), up-down and angles.

• spin-orbit. To perform a calculation with spin-orbit coupling. This

type of calculation requires the pseudopotentials to be relativis-
tic. Option only available since Siesta version 4.1.

In the case of a spin polarised calculation, you can impose a value

to the total spin polarisation of the system (in units of the electron
CHAPTER 5. CALCULATORS 178

spin,1/2). In ASAP 2022.1, spin-polarised calculations are enabled by

default when the structure under study contains magnetic elements.
In the case the user has specified the magnetic moments of the atoms
in the Parameter widget (see section 4.2), the total default spin is a sum
of atoms’ magnetic moments.

Dipole correction (Advanced properties)

Click the Dipole correction check box to add the electric field required
to compensate for the dipole of the system. The correction is per-
formed at every iteration of the self-consistent cycle. For slabs, this ex-
actly compensates the electric field created by the dipole moment of
the system. The option is essential to treat asymmetric slabs (including
systems with an adsorbate on one surface) and compute properties
such as the work function of each of the surfaces.

Simulate doping (Advanced properties)

CHAPTER 5. CALCULATORS 179

Click the Simulate doping check box to add a background charge den-
sity to simulate doping. This calculates the net charge of the system
and adds a compensating charge to make the overall system neutral.
This background charge is constant at points of the mesh near the
atoms, and zero at points far from the atoms. This option is useful
for modelling non-stoichiometric, or doped systems with open bound-
aries, surfaces with adsorbants, and defects.

External electric field (Advanced properties)

Click the External electric field check box to specify an external elec-
tric field applied to a system with open boundary conditions such as
slabs and molecules. The external electric field is set perpendicular to
the slab.

When applied to molecules, you can specify the electric field as a vec-
tor via its cartesian components. You can change the units in the right-
CHAPTER 5. CALCULATORS 180

hand menu.

Notice that when an external field is applied, the Dipole correction

check box is automatically ticked.

5.2.2 SIESTA Parameters: Convergence

This category has the following entries:

Real-space mesh cutoff energy

This parameter determines the fineness of a finite 3D grid used by
SIESTA. The 3D grid is used for the calculation of some integrals and
the representation of charge densities and potentials. MeshCutoff op-
tion gives a plane-wave cutoff. It means that all periodic plane waves
with kinetic energy lower than this cutoff can be represented in the
grid without aliasing.
CHAPTER 5. CALCULATORS 181

Brillouin Zone Sampling

The parameter options described below are available for 2D and 3D
systems. For an isolated system (1D) only the gamma-point is used,
which corresponds to a k-points grid of 1x1x1.

Click the Parallelisation over k-points button if you want the diag-
onalisation to be parallelised over the k-points. If the button is not
selected, the parallelisation is over orbitals.

The k-point diagonalisation is close to perfectly parallel when the num-

ber of k-points is much larger than the number of processors. We rec-
ommend using this option for metals, where the unit cell is small, but
the number of k-points is substantially large.

The dialog menu placed below Brillouin zone sampling label, offers the
possibility to automatically obtain the number of k-points associated
CHAPTER 5. CALCULATORS 182

with three different values of the grid step (q) in the reciprocal space
(in units of Ang−1 ): rough (q=0.1), medium (q=0.05) and fine (q=0.02).

Select the custom option if you want to customise the k-point grid.

ASAP 2022.1 offers two alternative options for the specification of the
k-point grid used in the SCF cycle.
Click the Monkhorst-Pack button to select the real-space supercell,
whose reciprocal unit cell is that of the k-sampling grid. ASAP 2022.1
only supports diagonal matrices.

As an alternative, click the k-grid cutoff button to specify the parame-

ter which determines the fineness of the k-grid used for Brillouin zone
sampling.
CHAPTER 5. CALCULATORS 183

The two methods described above should be equivalent for a well-

converged sampling. Users are advised to check that the number of
k-points is properly converged.

5.2.3 SIESTA Parameters: Basis set and Pseudopoten-

tials
Pseudopotentials and atomic orbital basis sets are necessary tools to
run a SIESTA calculation. The quality of pseudopotentials (pseudos)
and basis sets affects the accuracy of the SIESTA calculations. Thus,
it is clear the importance of relying on a database of optimised and
tested pseudos and basis sets.

Basis set
CHAPTER 5. CALCULATORS 184

SIESTA code makes use of local atomic orbital basis set to describe the
valence electrons. SIESTA generates extended bases by applying the
Split-valence scheme for multiple-zeta. The split is based on different
radii. The user has the possibility to choose among the different op-
tions available for basis generation and basis size.
First, the kind of basis to be generated is chosen. All are based on
finite-range pseudo-atomic orbitals. PAO’s of Sankey and Niklewsky,
PRB 40, 3979 (1989).

In addition, the following parameters are available:

Energy shift
Energy shift parameter specifies the confining radii of the original (first-
zeta) PAO’s for all the species guaranteeing the compensation of the
basis.

The recommended energy shift is indicated.

Basis size
This parameters indicates the number of orbitals per atom.

• SZ or MINIMAL: minimal or single-zeta basis.

• DZ: Double zeta basis.

• SZP: Single-zeta basis plus polarisation orbitals.

• DZP: Like DZ plus polarisation orbitals. Polarisation orbitals are

constructed from perturbation theory, and they are defined so
CHAPTER 5. CALCULATORS 185

they have the minimum angular momentum l such that there

are not occupied orbitals with the same l in the valence shell of
the ground-state atomic configuration. They polarise the corre-
sponding l1 shell.

It is possible to set the same basis size for all chemical species present,

and also to use different basis size for each of the elements.
CHAPTER 5. CALCULATORS 186

Pseudopotentials
SIESTA uses pseudopotentials to represent the electron-ion interac-
tion. In particular, the pseudopotentials are of the "norm-conserving"
kind. The released versions of SIESTA use pseudopotential files in the
“Froyen” (psf) format.

SIMUNE database
SIMUNE offers highly transferable pseudopotentials for the following
elements of the periodic table: H, He, Li, Be, B, C, N, O, F, Ne, Na, Mg,
Al, Si, P, S, Cl, Ar, Ti, Fe, Zn, Pd, Ag, Te, La, W, Pb.

The pseudopotentials have been generated using SIMUNE’s optimisa-

tion protocol. Here is given an explicit description of the generation
conditions and testing procedures.

To guarantee the code to work properly for any element of the peri-
odic table, for those pseudopotentials not yet optimised by SIMUNE,
ASAP uses the revised pseudos obtained from here and here. These
pseudopotentials were generated by translating into the .psf format
a set of pseudopotentials generated with the fhi98pp program for the
Abinit project (https://www.abinit.org/psp-tables). These Pseudopo-
tentials are provided without warranty. All pseudopotentials should be
thoroughly tested before using them.

Custom
This option provides maximum flexibility in the selection of the pseu-
dopotentials. Users can use pseudopotentials from different sources
for each of the elements present in the structure.
CHAPTER 5. CALCULATORS 187

For those users looking for extended pseudopotential options, here

they can found several pseudopotential generators. A pseudopoten-
tial found in a database should be treated as just a starting point for
further refinement. We stress that these pseudopotentials should not
be used blindly.

5.2.4 SIESTA Parameters: SCF

SIESTA uses the standard Kohn-Sham self-consistent Density Functional
Method (DFT). SCF widget aggregates parameters controlling SCF con-
verge.
CHAPTER 5. CALCULATORS 188

Maximal number of iterations.

Maximum number of Self Consistent Field (SCF) iterations per time
step.

Mixing coefficient.
The proportion of output Density Matrix to be used for the input Den-
sity Matrix of next SCF cycle.

Number Pulay.
Pulay mixing is the method of choice for accelerating the convergence
of the scf cycle. The input for the next SCF step is obtained by mix-
ing several previous steps instead of only the last one. Number Pulay
controls the Pulay convergence accelerator indicating the number of
previous steps that are mixed. Pulay mixing generally accelerates the
convergence significantly, and can reach convergence in cases where
linear mixing cannot.

Click on the Density matrix check box to make use of the density ma-
trix elements as a monitor of self-consistency. When the maximum
difference between the output and the input on each element of the
DM in a SCF cycle is smaller than the indicated tolerance value, the self
consistency has been achieved.

Advanced SCF (Advanced Parameters)

The following SCF mixing options are offered to control what physical
quantity to mix in the self-consistent cycle:

• Hamiltonian. Mix the Hamiltonian matrix.

• Density. Mix the density matrix.

• Charge. Mix the real-space charge density. Note this is an exper-

imental feature in SIESTA.
CHAPTER 5. CALCULATORS 189

The advanced parameters widget offers the following additional op-

tions to control SCF convergence:
• Energy density matrix. Option only available since Siesta ver-
sion 4.1. Click on this check box to make use of the energy density
matrix elements as monitor of self-consistency. The self-consistency
is considered achieved when the maximum absolute change (dE-
max) in the energy density matrix elements is below the specified
tolerance value.
• Free energy. Click on this check box to make use of the change
in the total (free) energy between cycles of the SCF procedure as
a monitor of self-consistency. The self-consistency is achieved
when the change in the total free energy between cycles of the
SCF procedure is below the specified tolerance value and the den-
sity matrix change criterion is also satisfied.
• Hamiltonian matrix. Option only available since Siesta version
4.1. Click on this check box to make use of the Hamiltonian matrix
elements as a monitor of self-consistency. The self-consistency is
achieved when the maximum absolute change (dHmax) in the H
matrix elements is below the specified tolerance value. The actual
meaning of dHmax depends on the selected SCF mixing option:
– if mixing the Density Matrix, dHmax refers to the change in
H(in) with respect to the previous step.
CHAPTER 5. CALCULATORS 190

– if mixing the Hamiltonian matrix, dHmax refers to H(out)-

H(in) in the previous step.

• Harris SCF Convergence. Click on this check box to use the Har-
ris energy as monitor of self-consistency. The self-consistency is
achieved when the change in the Harris energy between cycles of
the SCF procedure is below the specified tolerance value.

5.2.5 Preview input file

The button Preview input file allows to view the created SIESTA .FDF in-
put file with the GUI of the SIESTA calculator.

The .FDF file (Flexible Data Format) file, developed by A. Garcia and J.M.
Soler includes physical data of the system as well as the variables to
control the approximations used in the calculation. Whereas the for-
mer parameters are mandatory, others have default values assigned
CHAPTER 5. CALCULATORS 191

and, in principle, it is not necessary to explicitly include them in the in-

put file. However, it is important to stress out that the default values
do not always guarantee an accurate and converged calculation.

5.2.6 customise
The SIESTA calculator also allows the user to directly edit SIESTA .FDF
input file.
CHAPTER 5. CALCULATORS 192

Notice that after the edition of a .FDF input file, it is marked with a star
(*).

The Customise widget offers the following options:

• Get from widget. To rewrite the input file with the data from
widgets.

• Interpret. To validate the edited input. The purpose of this func-

tion is to reduce human error when editing the .FDF input file.

• Save to widget to update the calculator.

CHAPTER 5. CALCULATORS 193

Click on the Strict checking button to review that all the parameters
introduced in the Customise widget correspond to a valid SIESTA key-
word.
Chapter 6

Runners

In this chapter we explain how to configure local and remote runners.

On the local computer, the only external requirement to run simula-

tions is to install SIESTA. If you are a SIESTA expert, you can build it
from source and point ASAP to it. If not, you can use our embedded
installer, which will fetch a pre-compiled SIESTA executable for you, as
described below.

To be able to run simulations with ASAP on remote servers, you have

to make sure that the remote environments fulfil a few requirements.
In section 6.1.2, we give you minimal instructions to configure compu-
tational resources. You can find detailed instructions on how to config-
ure remote servers in Appendix A.

We have implemented a configuration widget for runners to manage

local and remote computational resources easily. See section 6.2.

6.1 Preparing run environments

6.1.1 Installing SIESTA on the local computer
You can download a SIESTA binary through the "Help / Download Siesta..."
menu in ASAP. Please note that only a limited number of operating sys-
tems, namely Windows, Debian, Linux Mint, Ubuntu and MacOS/Darwin,
are supported for now. Many more options will be available in the near
future.

194
CHAPTER 6. RUNNERS 195

Figure 6.1: SIESTA downloader widget.

Once the download widget appears, as shown in Fig. 6.1, you can se-
lect the operating system, the SIESTA version to install, and the kind
of parallelisation to use. By default, it will download a serial binary of
SIESTA 4.0 for Windows. When clicking on the "Download binary" but-
ton, the download will start. If the operation takes too much time or
gets stalled, you can cancel it by clicking on the "Cancel" button at the
bottom of the widget.

You can of course download more than one version of SIESTA, as well
as different parallelisation flavors. They will be stored on your hard
disk with different and explicit names. In any case, we recommend
you to download both the serial and MPI versions of the SIESTA binary
that best corresponds to your operating system and your needs.

Once one or more SIESTA binaries have been downloaded, you can
click on the "Configure..." button to go directly to the runner configu-
ration widget (see section 6.2 below), or close the download widget.

Should you encounter any problem with the downloaded binary, please
contact us at info@simuneatomistics.com.

6.1.2 Preparing a remote server before the first simu-

lation
NOTE: The following steps have to be done only once on each re-
mote server and are not necessary for local simulations.
CHAPTER 6. RUNNERS 196

Remote server configuration checklist:

1. Make sure the remote server is accessible through SSH with public-
key authentication.

2. Make sure the user on the local computer can connect through
SSH to remote servers with public-key authentication.

3. Configure a Python 3 virtual environment on the remote server.

4. Install ASE on the virtual environment.

5. Install a binary executable of SIESTA on the remote server.

6. Create a file that can be sourced by the default shell on the re-
mote server to make SIESTA available and activate the virtual en-
vironment.

You can find detailed instructions on how to configure remote servers

in Appendix A.

6.2 Managing local and remote runners

Configuring runners is how ASAP becomes aware of how to use the
available computational resources. Runners can be seen as pre-set
configurations that can be saved and used to run simulations either
on your local machine or on a remote server. They consist in the com-
bination of a remote server, a calculator executable, and an execution
mode. 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.

Before launching a new simulation, you will be able to select any of the
saved runners to use the resources at your disposal. To do that, click
on the button shown in Fig. 6.2. It will open the configuration runners
widget, as shown in Fig. 6.3.
CHAPTER 6. RUNNERS 197

Figure 6.2: Main windows view. The button to access configuration

runners widget is highlighted.

Figure 6.3: Configuration runner widget.

CHAPTER 6. RUNNERS 198

The configuration runners widget offers the following options:

• New remote.... Button to access the remote configuration wid-
get. It contains a form that will let you configure the remote con-
nections to clusters/servers for remote computing. See subsec-
tion 6.2.1.
• New program.... To configure an executable on the remote server.
See subsection 6.2.2
• Edit.... To edit a previously configured remote machine.
• Delete. To delete a previously configured remote connection.

6.2.1 Adding a remote machine

Click on the New remote... button to access the remote configuration
widget. It contains a form that will let you configure the remote con-
nections to clusters/servers for remote computing, as illustrated in Fig.
6.4.

Figure 6.4: Remote configuration widget. You can set up your remote
machine here.
CHAPTER 6. RUNNERS 199

The first four fields define the required parameters to establish the
connection to a remote server/cluster. The first field tells ASAP how
to call the SSH client program installed on the local machine. The sec-
ond and third fields contain the Username on the remote host and
the server name or IP address of the remote server. The fourth field
makes it possible to adjust the network port used to connect through
SSH. At present, all these fields must be non-empty.

The remaining settings, as shown in Fig. 6.4, tell ASAP where to find
the python interpreter (Python field) and which workspace to use for
the simulations on the remote server (Remote workspace field). If no
absolute path is given, the remote workspace will be considered rela-
tive to the remote user home directory. This might not be the case by
default, which is why we provide the Remote RC command field in the
form.

Through the Remote RC command, you can tell ASAP how to set the
remote environment appropriately before running simulations. If you
have followed the recommendations described in section A.5, this field
will look like:

. /full/path/to/.simune_env

If your remote shell is not compatible with the default Unix Bourne
shell, replacing the initial dot by the source keyword will work in 95%
of the cases.

Finally it is possible to run a check to test the connection to the server

the selected python environment, by clicking on the Check this con-
figuration button.

6.2.2 Adding a program

Click on New program... to configure an executable on the remote
server, see Fig. 6.5. On top, from the drop-down menu you can se-
lect which machine you want to associate to this runner. The list con-
tains the local machine (always available) plus remote machine that
has been already configured, see Section 6.2.1 to know how to config-
ure a remote machine.
CHAPTER 6. RUNNERS 200

Figure 6.5: Widget to configure the runner on the local or on a remote

machine.

Select New/Edit queue to open the Batch Scheduler Configuration wid-

CHAPTER 6. RUNNERS 201

get.

Figure 6.6: Batch Scheduler Configuration Widget

CHAPTER 6. RUNNERS 202

It contains a form that will let you configure the Batch Scheduler pa-
rameters.

The Batch Scheduler Configuration widget offers the following options:

Figure 6.7: Batch Scheduler Configuration options

• Configuration label: The name of Batch Scheduler Configura-

tion.
• Batch scheduler vendor: ASAP supports Portable Batch System
and Torque (PBS/TORQUE) and Slurm Workload Manager (SLURM).
• 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.
CHAPTER 6. RUNNERS 203

• Number of processors per node: How many processors are re-

served 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.

• Command-line arguments: To include any other command, not

cited above, supported by the selected batch scheduler vendor.
Chapter 7

The run widget

The Run widget facilitates the submission of a calculation to a local

computer or a remote server. Before using the Run widget, see chapter
6 for information on computational resources configuration in ASAP.

Select a project in the project tray, and click on the Run icon to open
the Run widget.

204
CHAPTER 7. THE RUN WIDGET 205

The Run widget offers the following options:

• Preview input. Press this button to view the created SIESTA.FDF

input file. See subsection 5.2.5 for further information on .FDF
file.
CHAPTER 7. THE RUN WIDGET 206

• Continue if possible. Click this button to read the density matrix

stored in file SystemLabel.DM by a previous run.

• Configure. Press this button to access the configuration runner

widget. See section 6.2 for further information.
CHAPTER 7. THE RUN WIDGET 207

Select one of the configurations,

and press the Run button to execute the calculation.

CHAPTER 7. THE RUN WIDGET 208

The tab Calculator output shows the complete calculation output in

real-time.

The tab Task output shows relevant information (dependent on the

CHAPTER 7. THE RUN WIDGET 209

project type) in real-time.

Press the Open run directory... button to open the folder containing
the calculation output files.
CHAPTER 7. THE RUN WIDGET 210

Press the Reset button if you want to remove the calculation output
files.

When the calculation is completed, you can select the Exit and anal-
CHAPTER 7. THE RUN WIDGET 211

yse button to open the analysis widget.

Chapter 8

Analysis

The analysis widgets implemented in ASAP facilitate the analysis of the

project output files.

To open the analysis widget, select Exit and analyse after a calculation
is successfully completed.

It is also possible to open an analysis widget by selecting Analyse icon

associated with a completed project.

212
CHAPTER 8. ANALYSIS 213

Some of the information provided by the analysis widget depends on

the executed project type,

• Single point calculation. See section 2.2.1.

• Geometry optimisation. See section 2.5.1.

CHAPTER 8. ANALYSIS 214

• Molecular Dynamics. See section 2.6.1.

• Equation Of State. See section 2.7.1.

CHAPTER 8. ANALYSIS 215

• Nudget Elastic Band. See section 2.8.8.

• Vibrations. See section 2.9.1.

CHAPTER 8. ANALYSIS 216

• Phonons. See section 2.10.1.

General notes:
• You can benefit from all features implemented in ASE GUI to vi-
sualise and measure geometries quantities, see section 3.2.
• You can save figures shown in the analysis widget by using right-
click on top of them.
CHAPTER 8. ANALYSIS 217

8.1 Properties
The information provided by the analysis widget also depends on the
properties that were selected on the Parameters widget, see section
4.3.

8.1.1 Density of States

Density Of States describes the number of states per interval of en-
ergy, at each energy level, that are available to be occupied.

Click the DOS... button to visualise the density of states of the system.
ASAP shows the DOS originated from the single-particle (Kohn-Sham)
eigenvalues computed during self-consisted field loop. To visualise the
DOS and PDOS computed after self-consistent field (SCF) loop with a
custom BZ sampling, see subsection 8.1.3.
CHAPTER 8. ANALYSIS 218

You can adjust the binding energy range (x-axis) by tuning the mini-
mum and maximum energies (in eV) shown at the bottom of the figure.

You can also tune the following parameters:

• Method. Gaussian or Lorentzian representations of the Dirac

delta function.

• Full width at half maximum The broadening is defined by the

full-width-at-half-maximum in both representations (Gaussian and
Lorentz) of the Dirac delta function.

Right-click on the density of states figure to make available the follow-

ing options:
CHAPTER 8. ANALYSIS 219

• Save figure as.... We support the following formats: eps, pdf, pgf,
png, ps, raw, rgba, svg and svgz.

• Open in Matplotlib... Open with Matplotlib the python script

used to plot the figure.

• Save a Matplotlib script as... Save the python script used to plot
the figure.

• Export data... Export the data from the density of states figure
to a text file format.

• Vicinity of Fermi level. Show the density of states near the Fermi
level (plus/minus 1.5 eV).

• Default energy range. Reset the figure to default values.

CHAPTER 8. ANALYSIS 220

8.1.2 Band Structure

Option only valid for infinite-size systems. The electronic band struc-
ture of a solid describes the range of energies that an electron within
the solid may have (energy bands) and the ranges of energy that it may
not have (band gaps).
Click the Band structure and DOS... button to visualise the band
structure and DOS of the system.
CHAPTER 8. ANALYSIS 221

Notice that you can adjust the band structure energy range (y-axis) by
tuning the minimum and maximum energies (in eV) shown at the bot-
tom of the figure.

Right-click on the band structure figure to make available the following

options:
CHAPTER 8. ANALYSIS 222

• Vicinity of Fermi level. Show bands and band gaps with energies
near the Fermi level (plus/minus 1.5 eV).

• Default range. Reset graphic to default values.

• Export Data. . . . Export the data from the band structure figure
to a text file format.

• Save Figure. We support the following formats: eps, pdf, pgf,

png, ps, raw, rgba, svg and svgz.

8.1.3 Partial DOS

Click the Partial DOS analyse... button to visualise the partial density
of states of the system.
CHAPTER 8. ANALYSIS 223
CHAPTER 8. ANALYSIS 224

To visualise the projected DOS on specific atoms, select them by their

chemical species or choose a range of atom indices.

You can also select the angular momenta of the atomic orbitals that
will be included in the PDOS visualisation.

ASAP allows you to change the label at your convenience. Press the
CHAPTER 8. ANALYSIS 225

Add button to incorporate each of your selections. Then click the Up-
date plot button to update the figure.
CHAPTER 8. ANALYSIS 226

You can adjust the binding energy range (x-axis) by tuning the mini-
mum and maximum energies shown at the top of the figure.

8.1.4 LDOS
Press the LDOS button to visualise the local density of states of the
system.
CHAPTER 8. ANALYSIS 227

You can tune the following parameters:

• Plane. The plane defined by two of the unit cell vectors.

CHAPTER 8. ANALYSIS 228

• Position. The position of the plot plane along the cut unit-cell
vector. The user can choose the index of the stored data.
CHAPTER 8. ANALYSIS 229

• Interpolation. The interpolation method. ASAP offers the inter-

polation methods implemented in matplotlib.

• Color. The color map to be used for the density plot.

CHAPTER 8. ANALYSIS 230

• Atom opacity. The opacity of the discs representing the atoms

in the plot.

Press the Export button to export the volumetric data of LDOS to .cube
file.
Bibliography

1. José M Soler, Emilio Artacho, Julian D Gale, Alberto García, Javier

Junquera, Pablo Ordejón, and Daniel Sánchez-Portal. The SIESTA
method for ab initio order-N materials simulation. Journal of Physics:
Condensed Matter, 14(11):2745–2779, 2002.

231
Appendix A

Preparing a remote server

before the first simulation

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 com-
patible 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 re-
mote server and are not necessary for local simulations.

1. Make sure the user on the local computer can connect through
SSH to remote servers with public-key authentication. See section
A.1.

2. Configure a Python 3 virtual environment on the remote server.

See section A.2.

3. Install ASE on the virtual environment. See section A.3.

4. Install a binary executable of SIESTA on the remote server. See

section A.4.

232
APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION233

5. Provide the user with a file that can be sourced by the default
shell on the remote server to make SIESTA available and activate
the virtual environment. We recommend to save it as .simune_env
in the user home directory for consistency with the rest of this
manual. See section A.5.

A.1 OpenSSH
The first step in configuring a remote server for ASAP is to connect to it
through SSH. Make sure your local computer can connect through SSH
to remote servers with public-key authentication.

In the next subsections, we give you instructions on how to install a

SSH client on the local machine and configure an SSH public-key au-
thentication access.

A.1.1 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 in-
stallation instructions.
APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION234

A.1.2 SSH public-key authentication

For the moment, SSH connections must 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.

When establishing the connection to the remote server through SSH,

please check that the remote server does not ask you for a password.
Instead, the local SSH client may ask you for a passphrase if your SSH
private key is still locked. Once you have made sure that this is the
case, you can proceed with the configuration of the remote server us-
ing this connection.

If you are required to input the password to access the cluster, please
follow the steps below in order to configure an SSH public-key authen-
tication 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.
APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION235

Create the authorized_keys file if it does not exist.

Note: Be careful to append your key to the file, preserving its previous con-
tents, 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.

A.2 Configure a Python 3 virtual environment

on the remote server
Independently of the program used to run remote simulations, the re-
mote server must provide a working Python 3 environment. It is due
to the fact that ASAP uses the Atomistic Simulation Environment (ASE)
to run simulations. ASE is a Python 3 package developed by the Tech-
nical University of Denmark and to which Simune is a contributor. It
has to be installed on the remote server else ASAP will not be able to
run remote simulations. See section A.3.

In this section, we provide you instructions to create a Python 3 virtual

environment on the remote server.

A.2.1 Python interpreter

Please note that Python version 3.6 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:

APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION236

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 al-
ternative. 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 sys-
tem at the bottom of the .simune_env file. See Section A.5 for more de-
tails.

A.2.2 Python 3 virtual environment

To create a Python 3 virtual environment, we suggest you to type the
following:

mkdir -p $HOME/venvs
python -m venv $HOME/venvs/simune

On some systems, you may have to replace python with python3 for
this to work.

Once the virtual environment has been created, check that it works by
typing:

source $HOME/venvs/simune/bin/activate

If your remote shell is a strict POSIX shell and does not support the
source built-in keyword, you can replace it by a dot ("."). In this case, be
careful to preserve the space between the dot and the path to the file,
as follows:

. $HOME/venvs/simune/bin/activate

Once this is done, you can write down the corresponding command at
the bottom of the .simune_env file. See section A.5 for more details.

Please note that you will have to restart from this point should
the connection to the remote server be interrupted in any way,
APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION237

which means typing the above command again. Indeed, when re-
connecting to the remote server, your console environment will be re-
set, which means that the server will have forgotten about the Python
virtual environment described above.

A.3 Install ASE

ASAP uses the Atomistic Simulation Environment (ASE) to run simula-
tions. ASE is a Python 3 package developed by the Technical University
of Denmark and to which Simune is a contributor. It has to be installed
on the remote server else ASAP will not be able to run remote simula-
tions.
If your remote server is connected to the internet, you can install ASE
by copying the following link to the clipboard:
Right-click this text and click on "Copy Link Address"
and typing:
pip install PASTE_LINK_HERE
where you replace PASTE_LINK_HERE by the pasted link (Ctrl-V on Linux/Windows,
or Cmd-V on Mac).

If this last command is successful, your remote server is now ready to

run simulations from ASAP.

If your remote server is not connected to the internet, you can request
a tarball of ASE to Simune by sending an email to info@simuneatomistics.com.
Once uploaded to the remote server, you can install it by typing:
tar xf ase_for_simune.tar.gz
cd ase_for_simune
pip install *.tar.gz
One last check you can do to validate this configuration is to run again
the Python interpreter,
$ python
and type the following in the Python console:
import ase
If this produces no error, you’re good to go.
APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION238

A.4 Install SIESTA on the remote server

If you want to run simulations with SIESTA, the next step is to install a
SIESTA binary on the remote server. For this, you can either ask your
server administrator to install SIESTA for you and explain how to access
it, or request a SIESTA binary for your architecture to Simune.

Please note that Simune can provide binary executables for a limited
set of operating systems, namely Windows 10, MacOS X Yosemite and
Catalina, as well as Debian, Fedora, and Ubuntu Linux. It will also
soon be possible to get Singularity images. Please send a request to
info@simuneatomistics.com mentioning the operating system and ar-
chitecture of the server to receive download instructions. If you already
requested a tarball of ASE, you will likely have received this executable
at the same time.

Once SIESTA is installed, you may receive instructions on how to adjust

the server environment so that the SIESTA executable can be found
by the operating system. Write down any command required to make
SIESTA visible to your system in the .simune_env file. See section A.5.

A.5 Set up .simune_env configuration file

We highly recommend you to track ASAP-related changes on each re-
mote server through a configuration file stored in your remote home
directory. For convenience, we will call it .simune_env in this section but
you are free to give it any valid filename.

The ASAP-related changes we recommend you to track through .simune_env

are:

• Any command required to make Python visible to your system.

Write it down at the bottom of the .simune_env file.

• The command required to activate Python 3 virtual environment.

Write down the corresponding command at the bottom of the
.simune_env file.

source $HOME/venvs/simune/bin/activate
APPENDIX A. PREPARING A REMOTE SERVER BEFORE THE FIRST SIMULATION239

• Any command required to make SIESTA visible to your system.

Once SIESTA is installed, you may receive instructions on how
to adjust the server environment so that the SIESTA executable
can be found by the operating system. Simply write down any
command required to make SIESTA visible to your system in the
.simune_env file.

Our recommendation is that you store .simune_env directly in your re-

mote home directory but any location accessible to your remote ac-
count will be fine. The only important aspect of this step is that you
remember correctly where this file is located.

Below you can find an example of a .simune_env file.

export PATH="$HOME/siesta/4.0.2:$PATH"
source $HOME/venvs/simune/bin/activate

The first command add the path-to-SIESTA executable to the PATH list.
The second activate the python 3 environment. Please send a request
to info@simuneatomistics.com should you require assistance to set up
the .simune_env configuration file.
SIMUNE is a company expert in Atomistic Simulations. We offer ser-
vices for leading industrial, academic, and research customers work-
ing 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 acceler-
ate 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 mod-
ules developed around atomistic simulation codes to facilitate their
use for industrial users. ASAP 2022.1 includes a SIESTA calculator in-
terface. 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 inter-
face, in order to improve their usability.

• Automate the existing workflows for the simulation of materials

properties and industrial problems of interest.