Phonon band structure tutorial#
In this tutorial you will learn how to use the main workflows of aiida-quantumespresso-ph
Let’s get started!
Defining a structure#
We need to create or load the structure for which to compute the dynamical matrix. This must be a StructureData.
Here, we define the structure of NaCl salt, which has only 2 atoms in its primitive cell.
Let’s define the silicon structure using the ASE module:
import numpy as np
from ase import Atoms
# Lattice parameter for NaCl (Angstrom)
a = 5.64
# Define primitive cell vectors (in Angstrom)
cell = a * np.array([
[0.0, 0.5, 0.5],
[0.5, 0.0, 0.5],
[0.5, 0.5, 0.0]
])
# Fractional (scaled) positions of basis atoms in the primitive cell
positions = [
(0.0, 0.0, 0.0), # Na
(0.5, 0.5, 0.5) # Cl
]
# Corresponding atomic symbols
symbols = ['Na', 'Cl']
# Create the primitive NaCl structure
nacl_primitive = Atoms(
symbols=symbols,
scaled_positions=positions,
cell=cell,
pbc=True
)
structure = StructureData(ase=nacl_primitive)
# Print information about the structure
print(nacl_primitive)
print("Cell vectors (Angstrom):\n", nacl_primitive.get_cell())
print("Atomic positions (Angstrom):\n", nacl_primitive.get_positions())
Atoms(symbols='NaCl', pbc=True, cell=[[0.0, 2.82, 2.82], [2.82, 0.0, 2.82], [2.82, 2.82, 0.0]])
Cell vectors (Angstrom):
Cell([[0.0, 2.82, 2.82], [2.82, 0.0, 2.82], [2.82, 2.82, 0.0]])
Atomic positions (Angstrom):
[[0. 0. 0. ]
[2.82 2.82 2.82]]
Run the DynamicalMatrixWorkChain workflow#
Let’s define the inputs:
pw_code: theCodewhich will run thepw.xbinaryph_code: theCodewhich will run theph.xbinarystructure: the StructureData node containing the information regarding the crystal structure
from aiida.orm import load_code, Dict
from aiida_quantumespresso.common.types import RelaxType, ElectronicType
from aiida_quantumespresso_ph.workflows.dynamical_matrix import DynamicalMatrixWorkChain
pw_code = load_code('pw@localhost')
ph_code = load_code('ph@localhost')
# to make the example run even faster than the 'fast' protocol, we override some parameters
overrides = {
'relax': {
'base': {
'kpoints_distance': 0.6,
},
},
'ph_main': {
'parallelize_qpoints': False,
'qpoints_distance': 1.2,
}
}
builder = DynamicalMatrixWorkChain.get_builder_from_protocol(
pw_code=pw_code,
ph_code=ph_code,
structure=structure,
protocol="fast",
overrides=overrides,
**{
'relax_type': RelaxType.NONE, # do not perform geometry optimization
'electronic_type': ElectronicType.INSULATOR # NaCl is an insulator
}
)
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/workflows/protocols/utils.py:147: UserWarning: Found unrecognised key in overrides: parallelize_qpoints
warnings.warn(f'Found unrecognised key in overrides: {full_key}')
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/workflows/protocols/utils.py:147: UserWarning: Found unrecognised key in overrides: ph.qpoints
warnings.warn(f'Found unrecognised key in overrides: {full_key}')
And now submit the calculation!
from aiida.engine import run_get_node
dynmat_results, dynmat_node = run_get_node(builder)
12/19/2025 06:15:58 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [126|DynamicalMatrixWorkChain|setup]: no parent given
12/19/2025 06:15:59 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [126|DynamicalMatrixWorkChain|run_relax]: launching PwRelaxWorkChain<128>
12/19/2025 06:15:59 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [128|PwRelaxWorkChain|setup]: No change in volume possible for the provided base input parameters. Meta convergence is turned off.
12/19/2025 06:15:59 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [128|PwRelaxWorkChain|setup]: Work chain will not run final SCF when `calculation` is set to `scf` for the relaxation `PwBaseWorkChain`.
12/19/2025 06:15:59 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [128|PwRelaxWorkChain|run_relax]: launching PwBaseWorkChain<131>
12/19/2025 06:16:00 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [131|PwBaseWorkChain|run_process]: launching PwCalculation<136> iteration #1
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:517: AiidaDeprecationWarning: `Code.get_remote_computer` method is deprecated, use the `computer` attribute instead. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:507: AiidaDeprecationWarning: `Code.get_remote_exec_path` method is deprecated, use `InstalledCode.filepath_executable` instead. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/parsers/parse_xml/pw/parse.py:15: AiidaDeprecationWarning: The parse_xml.versions module is deprecated and will be removed in aiida-quantumespresso v5.0.
Use get_schema_filepath() from parse_xml.parse instead.
from aiida_quantumespresso.parsers.parse_xml.versions import QeXmlVersion, get_xml_file_version
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/parsers/parse_xml/legacy.py:18: AiidaDeprecationWarning: This module has been deprecated and will be removed in aiida-quantumespresso v5.0.
If you are seeing this warning, you will have to update your Quantum ESPRESSO version (v6.6 or above).
warnings.warn(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/parsers/parse_xml/pw/legacy.py:27: AiidaDeprecationWarning: This module has been deprecated and will be removed in aiida-quantumespresso v5.0.
If you are seeing this warning, you will have to update your Quantum ESPRESSO version (v6.6 or above).
warnings.warn(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/parsers/parse_xml/pw/parse.py:19: AiidaDeprecationWarning: The parse_xml.pw.parse module has been deprecated and will be removed in aiida-quantumespresso v5.0.
Use parse_xml() from parse_xml.parse directly. Legacy XML format support will be dropped.
warnings.warn(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida_quantumespresso/parsers/parse_xml/pw/parse.py:35: AiidaDeprecationWarning: parse_xml_post_6_2() is deprecated. Use parse_xml() instead which takes a file-like object.
This function will be removed in aiida-quantumespresso v5.0.
parsed_data, logs = parse_xml_post_6_2(xml_parsed)
12/19/2025 06:16:17 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [131|PwBaseWorkChain|results]: work chain completed after 1 iterations
12/19/2025 06:16:17 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [131|PwBaseWorkChain|on_terminated]: remote folders will not be cleaned
12/19/2025 06:16:18 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [128|PwRelaxWorkChain|results]: workchain completed after 1 iterations
12/19/2025 06:16:18 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [128|PwRelaxWorkChain|on_terminated]: remote folders will not be cleaned
12/19/2025 06:16:19 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [126|DynamicalMatrixWorkChain|run_ph]: launching PhWorkChain<143>
12/19/2025 06:16:19 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [143|PhWorkChain|run_serial]: running in serial, launching PhBaseWorkChain<145>
12/19/2025 06:16:20 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [145|PhBaseWorkChain|run_process]: launching PhCalculation<150> iteration #1
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:517: AiidaDeprecationWarning: `Code.get_remote_computer` method is deprecated, use the `computer` attribute instead. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:507: AiidaDeprecationWarning: `Code.get_remote_exec_path` method is deprecated, use `InstalledCode.filepath_executable` instead. (this will be removed in v3)
warn_deprecation(
12/19/2025 06:21:23 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [145|PhBaseWorkChain|results]: work chain completed after 1 iterations
12/19/2025 06:21:23 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [145|PhBaseWorkChain|on_terminated]: remote folders will not be cleaned
12/19/2025 06:21:23 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [143|PhWorkChain|results]: workchain completed, output in FolderData<152>
12/19/2025 06:21:24 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [126|DynamicalMatrixWorkChain|results]: workchain succesfully completed
12/19/2025 06:21:24 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [126|DynamicalMatrixWorkChain|on_terminated]: cleaned remote folders of calculations: 136 150
Inspect the outputs and results#
You can now look into the outputs of the workflow.
print("Is the workflow finished correctly?", dynmat_node.is_finished_ok)
Is the workflow finished correctly? True
dynmat_results['ph_output_parameters'].get_dict()
{'code_version': '7.2',
'wall_time_seconds': 300.6,
'dynamical_matrix_1': {'q_point': [0.0, 0.0, 0.0],
'q_point_units': '2pi/lattice_parameter',
'frequencies': [-15.076839,
-15.076839,
-15.076839,
159.466829,
159.466829,
159.466829],
'frequencies_units': 'cm-1',
'mode_symmetry': ['G_4-', 'G_4-', 'G_4-', 'G_4-', 'G_4-', 'G_4-'],
'point_group': 'O_h (m-3m)'},
'dynamical_matrix_2': {'q_point': [-0.353553391, -0.353553391, 0.353553391],
'q_point_units': '2pi/lattice_parameter',
'frequencies': [110.634947,
110.634947,
130.666507,
130.666507,
167.426896,
212.052184],
'frequencies_units': 'cm-1',
'mode_symmetry': ['L_3', 'L_3', "L_3'", "L_3'", 'L_1', "L_2'"],
'point_group': 'D_3d (-3m)'},
'dynamical_matrix_3': {'q_point': [-0.707106781, 0.0, 0.0],
'q_point_units': '2pi/lattice_parameter',
'frequencies': [79.522092,
79.522092,
135.056358,
167.256172,
167.256172,
177.385127],
'frequencies_units': 'cm-1',
'mode_symmetry': ["M_5'", "M_5'", "M_4'", "M_5'", "M_5'", "M_4'"],
'point_group': 'D_4h(4/mmm)'},
'number_of_qpoints': 3,
'number_of_atoms': 2,
'number_of_irr_representations_for_each_q': [2, 4, 4],
'done_electric_field': True,
'dielectric_constant': [[2.5981951648943,
-2.2204460492503e-16,
6.6613381477509e-16],
[-2.2204460492503e-16, 2.5981951648943, -4.4408920985006e-16],
[5.5511151231258e-16, -1.1102230246252e-16, 2.5981951648943]],
'done_effective_charge_eu': True,
'effective_charges_eu': [[[1.1051962471257,
8.8817841970013e-16,
2.6645352591004e-15],
[2.6645352591004e-15, 1.1051962471257, -1.3322676295502e-15],
[2.6645352591004e-15, 0.0, 1.1051962471257]],
[[-1.1256184823348, 1.7763568394003e-15, -8.8817841970013e-16],
[0.0, -1.1256184823348, 0.0],
[0.0, 0.0, -1.1256184823348]]]}
Run the PhInterpolateWorkChain workflow#
Let’s define the inputs:
q2r_code: theCodewhich will run theq2r.xbinarymatdyn_code: theCodewhich will run thematdyn.xbinaryretrieved: the FolderData node containing the dynamical matrices
from aiida_quantumespresso_ph.workflows.ph_interpolate import PhInterpolateWorkChain
q2r_code_label = 'q2r@localhost'
matdyn_code_label = 'matdyn@localhost'
Band path#
Define the q-points path using seekpath
from aiida_quantumespresso.calculations.functions.seekpath_structure_analysis import seekpath_structure_analysis
inputs = {
'structure': structure,
'reference_distance': Float(0.02),
}
seekpath_results = seekpath_structure_analysis(**inputs)
band_qpoints = seekpath_results['explicit_kpoints']
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/seekpath/hpkot/__init__.py:156: DeprecationWarning: dict interface is deprecated. Use attribute interface instead
conv_lattice = dataset['std_lattice']
Define the inputs#
inputs = {
'dynmat_folder': dynmat_node.outputs.ph_retrieved,
'q2r': {
'q2r': {
'code': load_code(q2r_code_label),
'parameters': Dict({
'INPUT': {}
}),
'metadata': {
'options': {
'resources': {
'num_machines': 1,
'num_cores_per_mpiproc':1
},
'max_wallclock_seconds': 10*60,
},
},
},
},
'matdyn': {
'matdyn': {
'code': load_code(matdyn_code_label),
'parameters': Dict({
'INPUT': {
'asr': 'simple',
},
}),
'kpoints': band_qpoints,
'metadata': {
'options': {
'resources': {
'num_machines': 1,
'num_cores_per_mpiproc': 1
},
'max_wallclock_seconds': 10*60,
},
},
},
},
}
Run the interpolation#
interpolation_results, interpolation_node = run_get_node(PhInterpolateWorkChain, **inputs)
12/19/2025 06:21:26 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [166|PhInterpolateWorkChain|run_q2r]: launching Q2rBaseWorkChain<167>
12/19/2025 06:21:26 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [167|Q2rBaseWorkChain|run_process]: launching Q2rCalculation<168> iteration #1
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:517: AiidaDeprecationWarning: `Code.get_remote_computer` method is deprecated, use the `computer` attribute instead. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:507: AiidaDeprecationWarning: `Code.get_remote_exec_path` method is deprecated, use `InstalledCode.filepath_executable` instead. (this will be removed in v3)
warn_deprecation(
12/19/2025 06:21:27 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [167|Q2rBaseWorkChain|results]: work chain completed after 1 iterations
12/19/2025 06:21:27 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [167|Q2rBaseWorkChain|on_terminated]: remote folders will not be cleaned
12/19/2025 06:21:28 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [166|PhInterpolateWorkChain|run_matdyn]: launching MatdynBaseWorkChain<173>
12/19/2025 06:21:28 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [173|MatdynBaseWorkChain|run_process]: launching MatdynCalculation<174> iteration #1
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:517: AiidaDeprecationWarning: `Code.get_remote_computer` method is deprecated, use the `computer` attribute instead. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:556: AiidaDeprecationWarning: `Code.is_local` method is deprecated, use a `PortableCode` instance and check the type. (this will be removed in v3)
warn_deprecation(
/home/docs/checkouts/readthedocs.org/user_builds/aiida-quantumespresso-ph/conda/latest/lib/python3.12/site-packages/aiida/orm/nodes/data/code/legacy.py:507: AiidaDeprecationWarning: `Code.get_remote_exec_path` method is deprecated, use `InstalledCode.filepath_executable` instead. (this will be removed in v3)
warn_deprecation(
12/19/2025 06:21:30 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [173|MatdynBaseWorkChain|results]: work chain completed after 1 iterations
12/19/2025 06:21:31 PM <3125> aiida.orm.nodes.process.workflow.workchain.WorkChainNode: [REPORT] [173|MatdynBaseWorkChain|on_terminated]: remote folders will not be cleaned
Plot the phonon band dispersion#
interpolation_results['output_phonon_bands'].show_mpl()
Inspect other results#
interpolation_node.called[0].outputs.force_constants
<ForceConstantsData: uuid: 5eb9f510-c2d2-493d-a076-ab84717314ed (pk: 172)>
bands = interpolation_results['output_phonon_bands']
bands.get_bands()[0]
array([-0. , -0. , -0. , 4.80954042, 4.80954042,
7.54903491])