Skip to content

📚 workflows: Improve help strings for input parameters #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ymzhang0 wants to merge 2 commits into
base: main
Choose a base branch
from
+132 −31
Open

📚 workflows: Improve help strings for input parameters #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a3af4cc
Improve help text for all workflow inputs
ymzhang0 Dec 5, 2025
baed0c9
improve doc
ymzhang0 Dec 8, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 12 additions & 13 deletions src/aiida_epw/workflows/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,8 +94,7 @@ def define(cls, spec):
required=True,
serializer=to_aiida_type,
help=(
"The options dictionary for the calculation."
"It must be defined in the top-level as a solution of the conflict between `metadata_calculation` of the WorkChain and `metadata` of the Calculation."
"Dictionary containing the `metadata.options` for the `EpwCalculation`."
)
)

Expand All @@ -104,12 +103,9 @@ def define(cls, spec):
valid_type=orm.StructureData,
required=False,
help=(
"The structure data to use for the generation of k/q points by `create_kpoints_from_distance` calcfunction."
"In principle, we should take the structure as the one we used in the previous calculation."
"However, it is a bit difficult to take all the restart cases into account if we have a long chain of EPW calculations."
"Therefore, for now we just provide it manually as an input."
"But in the future, it will be removed."
"In cases that the coarse and fine k/q points are explicitly speficied, this input is not necessary anymore."
"Structure used to generate k-point and q-point meshes. Should match the "
"one used in the previous `Wannier90BandsWorkChain`. Only required when "
"fine k/q meshes are built from a distance."
)
)

Expand All @@ -119,9 +115,10 @@ def define(cls, spec):
serializer=to_aiida_type,
required=False,
help=(
"The q-points distance to generate the find qpoints"
"If specified, the fine qpoints will be generated from `create_kpoints_from_distance` calcfunction."
"If not specified, the fine qpoints will be read from the inputs.qfpoints input."
"Distance between q-points in the fine mesh. Mutually exclusive with "
"`qfpoints`; provide only one. When set, fine q-points are generated "
"from the input structure and this distance. Otherwise, supply fine "
"q-points explicitly."
)
)

Expand All @@ -132,8 +129,10 @@ def define(cls, spec):
serializer=to_aiida_type,
required=False,
help=(
"The factor to multiply the q-point mesh to get the fine k-point mesh"
"If not specified, the fine kpoints will be generated from the parent folder of the nscf calculation."
"Factor applied to each dimension of the fine q-point mesh to obtain the "
"fine k-point mesh. Mutually exclusive with `kfpoints`; provide only one. "
"For example, a fine q-mesh [40, 40, 40] with `kfpoints_factor=2` becomes "
"[80, 80, 80]."
)
)

Expand Down
69 changes: 60 additions & 9 deletions src/aiida_epw/workflows/prep.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,23 +38,59 @@ def define(cls, spec):
"""Define the work chain specification."""
super().define(spec)

spec.input("structure", valid_type=orm.StructureData)
spec.input(
"clean_workdir", valid_type=orm.Bool, default=lambda: orm.Bool(False)
"structure",
valid_type=orm.StructureData,
help=(
"Structure used to generate k-point and q-point meshes and passed to all "
"child workflows (`Wannier90BandsWorkChain`/`Wannier90OptimizeWorkChain`, "
"`PhBaseWorkChain`, and `EpwBaseWorkChain`)."
)
)
spec.input(
"qpoints_distance", valid_type=orm.Float, default=lambda: orm.Float(0.5)
"clean_workdir",
valid_type=orm.Bool,
default=lambda: orm.Bool(False),
help=(
"Whether the remote working directories of all child calculations will be "
"cleaned up after the workchain terminates."
)
)
spec.input(
"qpoints_distance",
valid_type=orm.Float,
default=lambda: orm.Float(0.5),
help=(
"Distance between q-points in the coarse q-point mesh used for the `PhBaseWorkChain`."
)
)
spec.input(
"kpoints_distance_scf",
valid_type=orm.Float,
default=lambda: orm.Float(0.15),
help=(
"Distance between k-points in the k-point mesh used for the "
"`Wannier90OptimizeWorkChain`/`Wannier90BandsWorkChain`."
)
)
spec.input(
"kpoints_factor_nscf", valid_type=orm.Int, default=lambda: orm.Int(2)
"kpoints_factor_nscf",
valid_type=orm.Int,
default=lambda: orm.Int(2),
help=(
"Factor applied to each dimension of the coarse q-point mesh to build the "
"coarse k-point mesh for the `Wannier90OptimizeWorkChain`/`Wannier90BandsWorkChain`. "
"For example, a q-mesh [4, 4, 4] with `kpoints_factor_nscf=2` becomes a k-mesh [8, 8, 8]. "
)
)
spec.input(
"w90_chk_to_ukk_script", valid_type=(orm.RemoteData, orm.SinglefileData)
"w90_chk_to_ukk_script",
valid_type=(orm.RemoteData, orm.SinglefileData),
help=(
"Julia script that converts `prefix.chk` from `wannier90.x` to the "
"`epw.x`-readable `prefix.ukk` (and adapts `prefix.mmn` for EPW >= v6.0). "
"Run as a prepend command before launching `epw.x`."
)
)

spec.expose_inputs(
Expand All @@ -65,7 +101,10 @@ def define(cls, spec):
"clean_workdir",
),
namespace_options={
"help": "Inputs for the `Wannier90OptimizeWorkChain/Wannier90BandsWorkChain`."
"help": (
"Inputs forwarded to `Wannier90OptimizeWorkChain / Wannier90BandsWorkChain` "
"that handle Wannierisation independently of the `epw.x` calculation."
)
},
)
spec.inputs["w90_bands"].validator = validate_inputs_bands
Expand All @@ -79,7 +118,9 @@ def define(cls, spec):
"qpoints_distance",
),
namespace_options={
"help": "Inputs for the `PhBaseWorkChain` that does the `ph.x` calculation."
"help": (
"Inputs forwarded to `PhBaseWorkChain` for running the `ph.x` calculation."
)
},
)
spec.expose_inputs(
Expand All @@ -99,7 +140,12 @@ def define(cls, spec):
"parent_folder_epw",
"parent_folder_chk",
),
namespace_options={"help": "Inputs for the `EpwBaseWorkChain`."},
namespace_options={
"help": (
"Inputs forwarded to `EpwBaseWorkChain` for the `epw.x` calculation that "
"bridges coarse Bloch and Wannier representations."
)
},
)
spec.expose_inputs(
EpwBaseWorkChain,
Expand All @@ -115,7 +161,12 @@ def define(cls, spec):
"kfpoints_factor",
"parent_folder_epw",
),
namespace_options={"help": "Inputs namespace for `EpwBaseWorkChain` that runs the `epw.x` calculation in interpolation mode, i.e. the interpolated electron and phonon band structures."},
namespace_options={
"help": (
"Inputs for the `EpwBaseWorkChain` that performs the `epw.x` calculation "
"for the interpolation of electron and phonon band structures. "
)
},
)
spec.output("retrieved", valid_type=orm.FolderData)
spec.output("epw_folder", valid_type=orm.RemoteStashFolderData)
Expand Down
69 changes: 60 additions & 9 deletions src/aiida_epw/workflows/supercon.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,17 +54,59 @@ def define(cls, spec):
"""Define the work chain specification."""
super().define(spec)

spec.input("structure", valid_type=orm.StructureData)
spec.input(
"clean_workdir", valid_type=orm.Bool, default=lambda: orm.Bool(False)
"structure",
valid_type=orm.StructureData,
help=(
"Structure used for this `SuperConWorkChain`. Should match the structure "
"used in the parent `EpwBaseWorkChain` or `EpwPrepWorkChain` that "
"produced `parent_folder_epw`."
)
)
spec.input(
"clean_workdir",
valid_type=orm.Bool,
default=lambda: orm.Bool(False),
help=(
"Whether the remote working directories of all child calculations "
"will be cleaned up after the workchain terminates."
)
)
spec.input(
"parent_folder_epw", valid_type=(orm.RemoteData, orm.RemoteStashFolderData)
"parent_folder_epw",
valid_type=(orm.RemoteData, orm.RemoteStashFolderData),
help=(
"Remote folder with outputs from a previous `epw.x` run (typically from "
"`EpwBaseWorkChain` or `EpwPrepWorkChain`). Must contain files such as "
"`out/prefix.epmatwp`, `crystal.fmt`, `dmedata.fmt`, `vmedata.fmt`, etc., "
"needed by the next `EpwBaseWorkChain` calculations."
)
)
spec.input("interpolation_distance", valid_type=(orm.Float, orm.List))
spec.input("convergence_threshold", valid_type=orm.Float, required=False)
spec.input(
"always_run_final", valid_type=orm.Bool, default=lambda: orm.Bool(False)
"interpolation_distance",
valid_type=(orm.Float, orm.List),
help=(
"Distance (or list of distances) between q-points in the fine mesh used "
"to converge the Allen-Dynes critical temperature."
)
)
spec.input(
"convergence_threshold",
valid_type=orm.Float,
required=False,
help=(
"Stopping threshold for the Allen-Dynes critical temperature: the loop "
"stops when consecutive values differ by less than this amount."
)
)
spec.input(
"always_run_final",
valid_type=orm.Bool,
default=lambda: orm.Bool(False),
help=(
"Run the final isotropic and anisotropic `EpwBaseWorkChain`s even if the "
"Allen-Dynes temperature has not yet converged."
)
)

spec.expose_inputs(
Expand All @@ -79,7 +121,10 @@ def define(cls, spec):
"kfpoints",
),
namespace_options={
"help": "Inputs for the interpolation `EpwBaseWorkChain`s."
"help": (
"Inputs forwarded to `EpwBaseWorkChain` for the `epw.x` runs used in "
"the Allen-Dynes Tc convergence."
)
},
)
spec.expose_inputs(
Expand All @@ -94,7 +139,10 @@ def define(cls, spec):
"kfpoints_factor",
),
namespace_options={
"help": "Inputs for the final isotropic `EpwBaseWorkChain`."
"help": (
"Inputs forwarded to the final `EpwBaseWorkChain` for the isotropic "
"Migdal-Eliashberg calculation."
)
},
)
spec.expose_inputs(
Expand All @@ -109,7 +157,10 @@ def define(cls, spec):
"kfpoints_factor",
),
namespace_options={
"help": "Inputs for the final anisotropic `EpwBaseWorkChain`."
"help": (
"Inputs forwarded to the final `EpwBaseWorkChain` for the anisotropic "
"Migdal-Eliashberg calculation."
)
},
)
spec.outline(
Expand Down