Skip to content

Commit 4fb7fb9

Browse files
committed
Update inputs customization docs.
1 parent 13616b4 commit 4fb7fb9

File tree

1 file changed

+64
-2
lines changed

1 file changed

+64
-2
lines changed

docs/source/howto/customize_inputs.md

Lines changed: 64 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Interacting with the workchain builder
44

5-
Workchain builder is a dictionary that specifies all the inputs of the workflow and all called calculations. It is the main object to interact with in order to change the default settings/parameters. Every workchain class includes `get_builder()` method to initialize an empty builder with the correct namespaces as well as `get_builder_from_protocol()` method returning a builder, prepopulated with default parameters defined in the simulation protocols ('fast', 'balanced' or 'stringent', cite Gabriel's paper: https://arxiv.org/pdf/2504.03962).
5+
Workchain builder is a dictionary that specifies all the inputs of the workflow and all called calculations. It is the main object to interact with in order to change the default settings/parameters. Every workchain class includes `get_builder()` method to initialize an empty builder with the correct namespaces as well as `get_builder_from_protocol()` method returning a builder, prepopulated with default parameters defined in the simulation protocols ('fast', 'balanced' or 'stringent' as defined in https://arxiv.org/pdf/2504.03962).
66

77
To check the builder structure in the interactive shell use the following commands for the relevant WorkChain:
88

@@ -67,7 +67,31 @@ builder.pw.parameters["SYSTEM"]["ecutwfc"] = 40.0
6767

6868
**Crystal structure** needs to be provided using AiiDA StructureData. More information on the relevant [documentation page](https://aiida.readthedocs.io/projects/aiida-core/en/stable/topics/data_types.html#topics-data-types-materials-structure).
6969

70-
**Pseudopotentials** have to be provided as [UpfData](https://aiida.readthedocs.io/projects/aiida-core/en/stable/topics/data_types.html#upfdata) data type. Usually they would be installed as part of the pseudopotential family via [aiida-pseudo](https://github.com/aiidateam/aiida-pseudo) package. As explained in [the package documentation](https://aiida-pseudo.readthedocs.io/en/latest/), pseudopotential families can be installed via a command line interface, either from the provided libraries ([SSSP](https://www.materialscloud.org/discover/sssp/table/efficiency) and [PseudoDojo](http://www.pseudo-dojo.org/)) or by importing from a custom archive or folder.
70+
**Pseudopotentials**
71+
72+
Pseudopotentials are provided as [UpfData](https://aiida.readthedocs.io/projects/aiida-core/en/stable/topics/data_types.html#upfdata) data type. Usually they would be installed as part of the pseudopotential family via [aiida-pseudo](https://github.com/aiidateam/aiida-pseudo) package. As explained in [the package documentation](https://aiida-pseudo.readthedocs.io/en/latest/), pseudopotential families can be installed via a command line interface, either from the provided libraries ([SSSP](https://www.materialscloud.org/discover/sssp/table/efficiency) and [PseudoDojo](http://www.pseudo-dojo.org/)) or by importing from a custom archive or folder.
73+
74+
- By default, AiiDA-QuantumESPRESSO workchains are using pseudopotentials from SSSP v1.3 Efficiency
75+
76+
- To use a different pseudopotential family installed via AiiDA-Pseudo, pass the requred label with the `pseudo_family` keyword of `get_builder_from_protocol()`:
77+
78+
```python
79+
from aiida import orm
80+
from aiida_quantumespresso.workflows.pw.base import PwBaseWorkChain
81+
82+
from ase.build import bulk
83+
84+
builder = PwBaseWorkChain.get_builder_from_protocol(
85+
code = orm.load_code('pw@localhost'),
86+
structure = orm.StructureData(ase=bulk('Si', 'fcc', 5.43)),
87+
pseudo_family = "PseudoDojo/0.4/PBEsol/SR/standard/upf"
88+
)
89+
```
90+
91+
#TODO:
92+
93+
- how to change cutoffs
94+
- setting the pseudos via family.get_pseudos https://github.com/mikibonacci/tutorials-aiida-yambo/blob/main/prerequisites/0_2_QE_starting_point.ipynb
7195

7296
**K-points** are specified through [KpointsData](https://aiida.readthedocs.io/projects/aiida-core/en/stable/topics/data_types.html#kpointsdata) that supports k-point meshes as well as custom k-point lists, and also features symmetry-based automatic calculation of k-point paths for electronic band structure calculation.
7397

@@ -100,6 +124,44 @@ builder.metadata["options"]["resources"]["tot_num_mpiprocs"] = 12
100124

101125
Full list of metadata available can be found at [AiiDA documentation page](link to this section of the real-world tips and tricks)
102126

127+
## Overrides
128+
129+
If many default inputs need to be overwritten, it is convenient to use the `overrides` keyword, provided by `get_builder_from_protocol()` function of the required workchain.
130+
It is necessary to arrange the custom parameters into a dictionary respecting the structure of the builder of the workchain.
131+
132+
```python
133+
from aiida import orm
134+
from aiida_quantumespresso.workflows.pw.base import PwBaseWorkChain
135+
136+
from ase.build import bulk
137+
138+
overrides = {
139+
"pw": {
140+
"parameters": {
141+
"SYSTEM": {
142+
"ecutrho": 300.0,
143+
"ecutwfc": 40.0
144+
}
145+
}
146+
},
147+
"metadata": {
148+
"options": {
149+
"queue_name": "normal",
150+
"resources": {
151+
"num_machines": 1,
152+
"tot_num_mpiprocs": 12
153+
}
154+
}
155+
}
156+
}
157+
158+
builder = PwBaseWorkChain.get_builder_from_protocol(
159+
code = orm.load_code('pw@localhost'),
160+
structure = orm.StructureData(ase=bulk('Si', 'fcc', 5.43)),
161+
protocol='balanced'
162+
)
163+
```
164+
103165
## Accessing the simulation directory and all files
104166

105167
In order to go to the calculation folder and see all the files you can use the following command for a given calculation with pk `<pk>`:

0 commit comments

Comments
 (0)