Update pw_tutorial.rst (#769)

Start with job submission example to demonstrate the goal of this tutorial (+ allow people who can immediately grasp how things work to skip most of it).

Co-authored-by: Sebastiaan Huber <mail@sphuber.net>
Co-authored-by: Marnik Bercx <mbercx@gmail.com>

docs/source/user_guide/get_started/examples/pw_short_example.py

@@ -8,55 +8,26 @@
 # For further information on the license, see the LICENSE.txt file #
 # For further information please visit http://www.aiida.net #
 ###########################################################################
-from aiida import load_profile
-
-from aiida.orm import Code
-from aiida.plugins import DataFactory
-from aiida.engine import submit
-from aiida.orm.nodes.data.upf import get_pseudos_from_structure
+# start-marker for docs
 
+from aiida import load_profile, orm, plugins, engine
 load_profile()
 
-StructureData = DataFactory('structure')
-Dict = DataFactory('dict')
-KpointsData = DataFactory('array.kpoints')
-
-###############################
-# Set your values here
-codename = 'pw-6.3@TheHive'
-pseudo_family = 'SSSP_efficiency'
-###############################
-
-code = Code.get_from_string(codename)
-builder = code.get_builder()
+builder = orm.load_code('pw-6.3@TheHive').get_builder()
 
 # BaTiO3 cubic structure
 alat = 4. # angstrom
-cell = [
- [
- alat,
- 0.,
- 0.,
- ],
- [
- 0.,
- alat,
- 0.,
- ],
- [
- 0.,
- 0.,
- alat,
- ],
-]
-s = StructureData(cell=cell)
+cell = [[alat, 0., 0.], [0., alat, 0.], [0., 0., alat]]
+s = plugins.DataFactory('structure')(cell=cell)
 s.append_atom(position=(0., 0., 0.), symbols='Ba')
 s.append_atom(position=(alat / 2., alat / 2., alat / 2.), symbols='Ti')
 s.append_atom(position=(alat / 2., alat / 2., 0.), symbols='O')
 s.append_atom(position=(alat / 2., 0., alat / 2.), symbols='O')
 s.append_atom(position=(0., alat / 2., alat / 2.), symbols='O')
+builder.structure = s
+builder.pseudos = orm.load_group('SSSP/1.1/PBE/efficiency').get_pseudos(structure=s)
 
-parameters = Dict(
+builder.parameters = plugins.DataFactory('dict')(
  dict={
  'CONTROL': {
  'calculation': 'scf',
@@ -73,21 +44,13 @@
  }
 )
 
-kpoints = KpointsData()
+kpoints = plugins.DataFactory('array.kpoints')()
 kpoints.set_kpoints_mesh([4, 4, 4])
+builder.kpoints = kpoints
 
-builder.pseudos = get_pseudos_from_structure(s, pseudo_family)
-
+builder.metadata.label = 'BaTiO3 test run'
 builder.metadata.options.resources = {'num_machines': 1}
 builder.metadata.options.max_wallclock_seconds = 1800
 
-builder.metadata.label = 'My generic title'
-builder.metadata.description = 'My generic description'
-
-builder.structure = s
-builder.parameters = parameters
-builder.kpoints = kpoints
-
-calc = submit(builder)
-
+calc = engine.submit(builder)
 print(f'created calculation with PK={calc.pk}')

docs/source/user_guide/get_started/examples/pw_tutorial.rst

@@ -12,16 +12,14 @@ It is assumed that you have already performed the installation, and that you alr
  - setup a computer (with ``verdi``);
  - installed Quantum ESPRESSO on your machine or a cluster;
  - setup the code and computer you want to use.
-
-Although the code could be quite readable, a basic knowledge of Python and object programming is useful.
+ - installed pseudo potentials (with ``aiida-pseudo install sssp``)
 
 The classic ``pw.x`` input file
 --------------------------------
 
 This is the input file of Quantum ESPRESSO that we will try to execute.
-It consists in the total energy calculation of a 5 atom cubic cell of BaTiO\ :sub:`3`\.
-Note also that AiiDA is a tool to use other codes:
-if the following input is not clear to you, please refer to the Quantum ESPRESSO documentation.
+It consists in the total energy calculation of a 5-atom cubic cell of BaTiO\ :sub:`3`\.
+If the following input is not clear to you, please refer to the `Quantum ESPRESSO documentation <https://www.quantum-espresso.org/>`_.
 
 ::
 
@@ -61,9 +59,15 @@ if the following input is not clear to you, please refer to the Quantum ESPRESSO
  0.0000000000 4.0000000000 0.0000000000
  0.0000000000 0.0000000000 4.0000000000
 
-Without AiiDA, not only you would have to prepare 'manually' this file,
-but also prepare the scheduler submission script, send everything on the cluster, etc.
-We are going instead to prepare everything in a more programmatic way.
+Using the ``aiida-quantumespresso`` plugin, you can submit the same calculation via the following Python script:
+
+.. literalinclude:: pw_short_example.py
+ :language: python
+ :start-after: start-marker
+
+Not only will AiiDA track the provenance of the entire calculation, it will also take care of preparing the scheduler submission script, submitting the calculation on the cluster, and getting the results back when it's done.
+
+In the following sections, we explain all aspects of this script step-by-step.
 
 Running a pw calculation with AiiDA
 -----------------------------------