Ctrl+K
Ctrl+K

Running a pw.x calculation

Running a pw.x calculation#

Running a pw.x calculation through the CLI#

The simplest way to run a first pw.x calculation with aiida-quantumespresso is through the command line interface (CLI) that ships with the package.

aiida-quantumespresso calculation launch pw -X pw@locahost -F SSSP/1.1/PBE/efficiency

If everything is setup correctly, you should output that looks something like the following:

Running a PwCalculation...
PwCalculation<59517> terminated with state: finished [0]

Output link               Node pk and type
------------------------------------------------------------
output_band               BandsData<59520>
output_parameters         Dict<59522>
output_trajectory         TrajectoryData<59521>
remote_folder             RemoteData<59518>
retrieved                 FolderData<59519>

The command ran a PwCalculation, with the identifier 59517 and it finished correctly.

Note

We can know that the job finished correctly because it says its state is finished [0]. The 0 is the exit status of the job, which means it was successful. A non-zero exit code means the primary objective of the calculation was not (fully) achieved or an error occurred.

The outputs that were generated by the calculation are printed to screen. To obtain more information about the calculation that ran, such as its inputs, run verdi process show <IDENTIFIER>

verdi process show 59517

Property     Value
-----------  ------------------------------------
type         PwCalculation
state        Finished [0]
pk           59517
uuid         982e6b36-bdf6-4525-8fd3-86e546afcd7f
label
description
ctime        2022-10-09 16:39:49.026195+02:00
mtime        2022-10-09 16:39:51.543732+02:00
computer     [1] localhost

Inputs      PK     Type
----------  -----  -------------
pseudos
    Si      56785  UpfData
code        56729  Code
kpoints     59515  KpointsData
parameters  59516  Dict
structure   56731  StructureData

Outputs               PK  Type
-----------------  -----  --------------
output_band        59520  BandsData
output_parameters  59522  Dict
output_trajectory  59521  TrajectoryData
remote_folder      59518  RemoteData
retrieved          59519  FolderData

The calculation received a number of inputs: pseudos, code, kpoints, parameters and a structure. The code was specified through the -X option when we invoked the CLI command to launch the calculation. Other inputs, such as structure, parameters etc. were created automatically by the CLI command.

The inputs can be introspected through the verdi CLI that ships with aiida-core. For example, the structure can be visualized using the command:

verdi data core.structure show 56731

This should open a new dialog with a visualization of the silicon crystal structure that was automatically created for this calculation. Similarly, the parameters can be shown using:

verdi node attributes 59516

PK: 59516
{
    "CONTROL": {
        "calculation": "scf"
    },
    "SYSTEM": {
        "ecutrho": 240.0,
        "ecutwfc": 30.0
    }
}

Likewise, the output parameters (output_parameters), which are of the same type (Dict) of the input parameters (parameters) can also be shown:

verdi node attributes 59522

PK: 59522
{
    "beta_real_space": false,
    "convergence_info": {
        "scf_conv": {
            "convergence_achieved": true,
            "n_scf_steps": 6,
            "scf_error": 2.1572731407236e-07
        }
    },
    "creator_name": "pwscf",
    "creator_version": "6.6",
    "energy": -308.19211637089,
    ...
    "energy_accuracy": 5.850447441879e-06,
    "energy_accuracy_units": "eV",
    "fermi_energy": 6.508401516556,
    "fermi_energy_units": "eV",
    "number_of_atoms": 2,
    "number_of_bands": 4,
    "number_of_bravais_symmetries": 48,
    "number_of_electrons": 8.0,
    "number_of_k_points": 3,
    "number_of_species": 1,
    "number_of_spin_components": 1,
    "number_of_symmetries": 48,
    "scf_iterations": 6,
    "volume": 40.02575122515,
    "wall_time_seconds": 1.23,
}

The output will show a number of parameters that have been automatically parsed from the output of the pw.x calculation. Note that the output has been shortened for clarity and not all parsed output parameters are shown.

Running a pw.x calculation through the API#

The following minimal example shows how to run a pw.x calculation through AiiDA’s Python API. For the purposes of this demonstration, the electronic ground state of an fcc silicon crystal structure is computed.

Tip

The code that is shown below in snippets can be downloaded as a script. Save the script to a file, make it executable and then simply execute it to run the example calculation.

First, import the required classes and functions:

from aiida.engine import run
from aiida.orm import Dict, KpointsData, StructureData, load_code, load_group

Then, load the code that was setup in AiiDA for pw.x and get an instance of the process builder:

# Load the code configured for ``pw.x``. Make sure to replace this string
# with the label that you used in the setup of the code.
code = load_code('pw@localhost')
builder = code.get_builder()

The process builder can be used to assign the inputs that are to be used for the calculation. When an input is assigned, it is automatically validated. Let’s first define a structure and assign it to the builder:

# Create a silicon fcc crystal
from ase.build import bulk
structure = StructureData(ase=bulk('Si', 'fcc', 5.43))
builder.structure = structure

To construct a crystal structure, we use the bulk method of the ASE library. This is then wrapped in a StructureData node such that it can be stored in AiiDA’s provenance graph, and assigned to the builder.

Next, we need to define the pseudopotentials. If the pseudopotentials were installed using the aiida-pseudo package, as described in the installation guide, that can be done as follows:

# Load the pseudopotential family.
pseudo_family = load_group('SSSP/1.1/PBE/efficiency')
builder.pseudos = pseudo_family.get_pseudos(structure=structure)

The parameters of the input file that will be read by pw.x are defined through the parameters input. A minimal setup to run an SCF calculation is shown below:

# Request the recommended wavefunction and charge density cutoffs
# for the given structure and energy units.
cutoff_wfc, cutoff_rho = pseudo_family.get_recommended_cutoffs(
    structure=structure,
    unit='Ry'
)

parameters = Dict({
    'CONTROL': {
        'calculation': 'scf'
    },
    'SYSTEM': {
        'ecutwfc': cutoff_wfc,
        'ecutrho': cutoff_rho,
    }
})
builder.parameters = parameters

Note

The pw.x code actually requires more input parameters than have been specified in the example above. The other required parameters are actually automatically defined by the PwCalculation plugin, based on for example the input structure. To find out what other parameters can be specified, please refer to the documentation of Quantum ESPRESSO. Note that certain parameters cannot be manually specified as these are reserved for the plugin to be set.

The k-points to be used for the calculation are defined using the KpointsData class:

# Generate a 2x2x2 Monkhorst-Pack mesh
kpoints = KpointsData()
kpoints.set_kpoints_mesh([2, 2, 2])
builder.kpoints = kpoints

Finally, specify the amount of CPUs that the calculation should use and how long it can run before it should be killed:

# Run the calculation on 1 CPU and kill it if it runs longer than 1800 seconds.
# Set ``withmpi`` to ``False`` if ``pw.x`` was compiled without MPI support.
builder.metadata.options = {
    'resources': {
        'num_machines': 1,
    },
    'max_wallclock_seconds': 1800,
    'withmpi': False,
}

All required inputs have now been defined. The calculation can be started by launching the process builder:

results, node = run.get_node(builder)

When the calculation is finished, run.get_node will return a tuple of two values: results and node. The results will be a dictionary of all the output nodes that were produced and the node will hold a reference to the node that represents the calculation in AiiDA’s provenance graph. When the calculation is finished, check whether it was successful through its exit status:

node.exit_status

If the calculation finished successfully, this will return 0. A non-zero exit code means the primary objective of the calculation was not (fully) achieved or an error occurred.

The results variable contains a dictionary of the created output nodes. Print it to see exactly which outputs were created and what their identifiers are:

print(results)
{
    'output_band': <BandsData: uuid: a82526b7-fb7f-4638-a1e1-f72ad04a5f13 (pk: 59537)>,
    'output_trajectory': <TrajectoryData: uuid: 4122ba08-6318-4029-9892-55b29e89a39c (pk: 59538)>,
    'output_parameters': <Dict: uuid: 82fe2b57-0dc0-4031-81a0-e80ed34db680 (pk: 59539)>,
    'remote_folder': <RemoteData: uuid: 672113fd-7177-4688-ad77-674703b8f611 (pk: 59535)>,
    'retrieved': <FolderData: uuid: 5f44b880-4c74-4194-9484-0c51ec4f1a34 (pk: 59536)>
}

To show the parsed output parameters, call:

results['output_parameters'].base.attributes.all
{
    'energy': -153.30519007432,
    'volume': 40.02575122515,
    ....
}

The complete output that was written by pw.x to stdout, can be retrieved as follows:

results['retrieved'].base.repository.get_object_content('aiida.out')
Contents