Attention
These pages are under construction — come back soon!
Input format
Koopmans input files define the structure, workflow settings, k-points, and calculator
parameters for a calculation. They can be written in either json or yaml format as per the following example:
{
"workflow": {
"task": "wannierize",
"pseudo_library": "PseudoDojo/0.4/LDA/SR/standard/upf"
},
"atoms": {
"cell_parameters": {
"periodic": true,
"ibrav": 2,
"celldms": {"1": 10.2622}
},
"atomic_positions": {
"units": "crystal",
"positions": [["Si", 0.00, 0.00, 0.00],
["Si", 0.25, 0.25, 0.25]]
}
},
"kpoints": {
"grid": [2, 2, 2],
"offset": [0, 0, 0],
"path": "LGXKG"
},
"calculator_parameters": {
"ecutwfc": 60.0,
"wannier90": {
"bands_plot": true,
"projections": [[{"fractional_site": [ 0.25, 0.25, 0.25 ], "ang_mtm": "sp3"}],
[{"fractional_site": [ 0.25, 0.25, 0.25 ], "ang_mtm": "sp3"}]],
"dis_froz_max": 10.6,
"dis_win_max": 16.9
}
}
}
The formats of each of the sections are defined as follows
- pydantic model KoopmansInput[source]
Input schema for
koopmansinput files.- field version: int = 1
Version of the input file format (older files are upgraded automatically when loaded from disk)
- field workflow: WorkflowConfig [Required]
Configuration specifying the workflow to be executed
- field atoms: AtomsInput [Required]
Atomic structure information
- field kpoints: KpointsInput [Optional]
k-point sampling information
- field calculator_parameters: CalculatorParametersInput [Required]
Parameters for the individual electronic structure calculators (
pw.x, etc…)
- field parallelization: ParallelizationInput [Optional]
Per-code parallelization settings (MPI ranks and k-point pools)
- resolve_paths(base_dir: str | Path) None[source]
Resolve file-path input fields against the input file’s directory.
ml.model_fileandatoms.snapshotsboth name files on disk. A relative path in the input file is interpreted relative to the file’s own location, not the process working directory. Absolute paths are left untouched.
Specifications for all elements of the input file
Input file schema for koopmans.
- pydantic model AtomicPositionsInput[source]
Input schema for specifying atomic positions in a structure.
- pydantic model AtomsInput[source]
Input model for specifying the cell and atomic positions.
- field atomic_positions: AtomicPositionsInput | None = None
- field cell_parameters: CellParametersViaIbrav | CellParametersViaVectors | CellParametersViaAlat [Required]
- pydantic model CalculatorParametersInput[source]
Calculator-specific input parameters.
- field kcp: KCPInputParameters [Optional]
- field pw: PWInputParameters [Optional]
- field pw2wannier90: PW2Wannier90InputParameters [Optional]
- field unfold_and_interpolate: UnfoldAndInterpolateConfig [Optional]
- field wannier90: Wannier90InputParametersWithUpDown [Optional]
- pydantic model CellParametersViaAlat[source]
Cell parameters specified via
celldmsand explicit vectors inalatunits.- field celldms: Annotated[dict[int, float], AfterValidator(func=_require_celldm1)] [Required]
- Constraints:
func = <function _require_celldm1 at 0x724f1737ade0>
- pydantic model CellParametersViaIbrav[source]
Cell parameters specified via
ibravandcelldms.
- pydantic model CellParametersViaVectors[source]
Cell parameters specified via explicit vectors in
bohrorangunits.
- pydantic model GammaOnlyKpointsInput[source]
K-points configuration for gamma-only calculations.
- field gamma_only: Literal[True] = True
- field offset: tuple[NoOffset, NoOffset, NoOffset] = (0.0, 0.0, 0.0)
A gamma-only calculation samples Gamma itself, so it cannot be shifted.
- field overrides: KpointsOverridesInput [Optional]
Per-step k-point sampling, which a gamma-only calculation cannot have.
- field path: Literal['G'] = 'G'
- pydantic model GridKpointsInput[source]
K-points configuration for calculations with explicit grid.
- field gamma_only: Literal[False] = False
- field offset: tuple[KpointOffset, KpointOffset, KpointOffset] = (0.0, 0.0, 0.0)
Per-axis fraction of a grid step to shift the mesh by.
- field overrides: KpointsOverridesInput [Optional]
Per-step k-point sampling, in place of
gridandoffset.
- INPUT_FILE_FORMAT_VERSION = 1
Current version of the input file format.
Bump this (and register a migration in
_MIGRATIONS) only when the format changes incompatibly. Adding new optional fields does not require a bump.
- pydantic model KCPInputParameters[source]
Complete input parameters for
kcp.x.- field cell: CellNamelist [Optional]
- field control: ControlNamelist [Optional]
- field ee: EENamelist [Optional]
- field electrons: ElectronsNamelist [Optional]
- field ions: IonsNamelist [Optional]
- field nksic: NKSICNamelist [Optional]
- field system: SystemNamelist [Optional]
- KpointOffset
One axis of a k-point mesh offset: 0 leaves it Gamma-centred, 0.5 half-shifts it, and nothing else is expressible.
alias of
Annotated[float,AfterValidator(func=_expressible_shift)]
- pydantic model KpointsOverridesInput[source]
K-point sampling for individual steps, in place of the top-level values.
Steps left out sample the top-level
gridandoffset.- field nscf: StepKpointsInput | None = None
The Gamma-centred mesh the Wannier functions are built from.
- field scf: StepKpointsInput | None = None
The mesh the ground-state calculation converges the density on.
- pydantic model MLConfig[source]
Configuration for machine learning models used to predict screening parameters.
- field descriptor: MLDescriptor = MLDescriptor.POWER_SPECTRUM
What to use as the descriptor for the ML model
- field mode: MLMode = MLMode.NONE
‘train’ fits a screening model on the computed alphas, ‘test’ scores an existing model against them, ‘predict’ applies an existing model in place of the alpha calculation
- field model: int | str | None = None
reuse a model trained in this database: the identifier a mode=’train’ run prints on completion (‘Trained model stored as node <pk> …’). If you have a model.json file instead, use model_file
- field model_file: str | None = None
path to a trained model’s JSON file (a mode=’train’ run writes model.json next to its other outputs)
- field n_max: int = 4
the maximum expansion coefficient n for radial basis functions
- Constraints:
gt = 0
- NoOffset
One axis of a gamma-only offset.
Literal[0.0]cannot express this: PEP 586 admits int, str, bytes, bool, Enum and None, but not float.alias of
Annotated[float,AfterValidator(func=_no_shift)]
- pydantic model PW2Wannier90InputParameters[source]
Input parameters for
pw2wannier90.xcalculations (theINPUTPPnamelist).
- pydantic model PWInputParameters[source]
Input parameters for
pw.xcalculations.- field control: ControlNamelist [Optional]
- field electrons: ElectronsNamelist [Optional]
- field system: SystemNamelist [Optional]
- pydantic model ParallelizationInput[source]
Per-code parallelization settings.
A mapping of code name to
CodeParallelization. Only the codes listed here are recognised; any other key is rejected. Codes left unset inherit the QE/AiiDA defaults (a single MPI rank, no pools).- as_dict() dict[str, CodeParallelization][source]
Return the configured (non-
None) code entries as a plain dict.
- as_mapping() dict[Literal['pw', 'kcp', 'kcw', 'ph', 'projwfc', 'pw2wannier90', 'wann2kcp', 'wannier90'], CodeParallelization][source]
Return the per-code settings as the mapping the workgraphs consume.
Each configured code maps to its set (non-
None) fields via pydantic’s own dump; a code with no set field is omitted. This is theParallelizationDictshapeaiida-koopmansexpects.
- pydantic model Projection[source]
Wannier90 projections input parameter.
- field ang_mtm: QuantumNumbers [Required]
Angular momentum of the projection
- field cartesian_site: Annotated[list[float], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=3), MaxLen(max_length=3)])] | None = None
Cartesian coordinates of the projection
- field fractional_site: Annotated[list[Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=1.0)])]], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=3), MaxLen(max_length=3)])] | None = None
Site of the projection (fractional coordinates)
- classmethod from_string(proj_str: str) Projection[source]
Create a Projection object from a string.
- field quant_dir: tuple[int, int, int] | None = None
Quantization axis for non-collinear calculations
- pydantic model RestrictedWannier90InputParameters[source]
Wannier90 input parameters, excluding those that
koopmansmanages itself.The structure and k-points are stored centrally in the input file, the band/projection bookkeeping is derived by the workflow, and automatic projections are requested via
workflow.auto_projections, so those keywords are demoted to class variables to drop them from the pydantic schema (seepw.pyfor the ClassVar rationale and the mypy ignores).- kpoints: ClassVar[list[Annotated[list[Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0.0), Le(le=1.0)])]], FieldInfo(annotation=NoneType, required=True, metadata=[MinLen(min_length=3), MaxLen(max_length=3)])]] | None] = None
- field projections: list[list[Projection]] [Optional]
- pydantic model SpinSpecificWannierInput[source]
Spin-specific Wannier90 input parameters.
- field projections: list[list[Projection]] [Optional]
- pydantic model StepKpointsInput[source]
K-point sampling for one step, in place of the top-level values.
Every attribute is absolute and every one left unset is taken from the top-level
kpoints.- field grid: tuple[int, int, int] | None = None
Monkhorst-Pack dimensions of the mesh this step samples.
- pydantic model UnfoldAndInterpolateConfig[source]
Input parameters for unfold-and-interpolate post-processing.
- field do_dos: bool = True
if True, the density-of-states is interpolated along the k-point path specified in the kpoints block. The DOS is written to a file called “dos_interpolated.dat”
- field smooth_int_factor: tuple[int, int, int] = (1, 1, 1)
if this is > 1 (or is a 3-element list with at least one entry > 1), the smooth interpolation method is used. This consists of removing the DFT part of the Hamiltonian from the full Koopmans Hamiltonian and adding the DFT Hamiltonian from a calculation with a denser k-points mesh, where this keyword defines how many times denser to make the mesh. (If this is set to a scalar a, the new k-grid will be [a*kx_old, a*ky_old, a*kz_old]. If it is a list [a, b, c], the dense k-grid will be [a*kx_old, b*ky_old, c*kz_old].) This works only for a non self-consistent Koopmans calculation using Wannier since, to be consistent, all the Hamiltonians must be in the same gauge, i.e. the Wannier gauge
- field use_ws_distance: bool = True
if True, the real Wigner-Seitz distance between the Wannier functions centers is considered as in the Wannier90 code. In particular, this accounts for the periodic boundary conditions and it is crucial for a good interpolation when using coarse MP meshes or, equivalently, small supercells
- pydantic model Wannier90InputParametersWithUpDown[source]
Wannier90 input parameters with optional spin-up/spin-down configuration.
- field down: SpinSpecificWannierInput | None = None
- field up: SpinSpecificWannierInput | None = None
- pydantic model WorkflowConfig[source]
Model for the configuration of a Workflow.
- field alpha_conv_thr: float = 0.001
convergence threshold for $|Delta E_i - epsilon_i|$; if below this threshold, the corresponding alpha value is not updated
- field alpha_from_file: bool = False
if True, uses the file_alpharef.txt from the base directory as a starting guess
- field alpha_guess: float | list[float] = 0.6
starting guess for alpha (overridden if alpha_from_file is true)
- field auto_projections: bool = False
if True, derive the Wannier projections automatically from the pseudopotentials’ atomic orbitals (or, if pw2wannier90.atom_proj_ext is set, from external projector files) instead of requiring explicit projections in calculator_parameters.w90.projections. Setting pw2wannier90.atom_proj_ext requires this too: the projector files choose where the projector functions come from, not whether the projections are derived automatically
- field block_wannierization_threshold: float | None = None
blocks of bands separated by this threshold will be Wannierized separately
- field correction: Correction = Correction.KI
orbital-density-dependent-functional/density-functional to use
- field dfpt_coarse_grid: tuple[int, int, int] | None = None
The coarse k-point grid on which to perform the DFPT calculations
- field eps_inf: Annotated[float, FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=1.0)])] | str | None = None
dielectric constant of the system used by the Gygi-Baldereschi and Makov-Payne corrections; either provide an explicit value or set to “auto” to calculate it ab initio
- field fix_spin_contamination: bool = False
if True, steps will be taken to try and avoid spin contamination. This is only sensible when performing a non-spin-polarized calculation, and is turned on by default for such calculations
- field frozen_orbitals: bool | None = None
if True, freeze the variational orbitals for the duration of the calculation once they’ve been initialized
- field gb_correction: bool | None = None
if True, apply the Gygi-Baldereschi scheme to deal with the q->0 divergence of the Coulomb interation for periodic systems
- field group_orbitals_by: GroupOrbitalsBy | None = None
criterion for grouping orbitals so they share a screening parameter: “self_hartree” (energies within group_orbitals_tol, in eV), “spread” (wannier90 spreads within group_orbitals_tol, in Angstrom^2), or “none”. The criterion is independent of the screening method, though not every combination is wired up yet (currently self_hartree on DSCF and spread on DFPT). Left unset, resolves to “self_hartree” for Wannier-initialised DSCF runs (supercell images of one primitive orbital are physically equivalent) and “none” otherwise; the resolved value is recorded on the parsed input
- field group_orbitals_tol: float | None = None
tolerance for the group_orbitals_by criterion (units set by the criterion, e.g. eV for self_hartree, Angstrom^2 for spread). Left unset, takes the criterion’s default (1e-4 for self_hartree, 0.05 for spread)
- field init_empty_orbitals: VariationalOrbitalType [Required]
which orbitals to use as an initial guess for the empty variational orbitals
- field init_orbitals: VariationalOrbitalType = VariationalOrbitalType.PZ
which orbitals to use as an initial guess for the variational orbitals
- field initialize_with_smearing: bool = False
if True, the first step of the workflow will use smearing. This can help convergence in some difficult cases.
- field max_time: int | float | None = None
maximum time in seconds to wait for the workflow to complete; if None, no timeout is applied
- field mp_correction: bool | None = None
if True, apply the Makov-Payne correction for charged periodic systems
- field mt_correction: bool | None = None
if True, apply the Martyna-Tuckerman correction for charged aperiodic systems
- field orbital_groups: list[list[int]] | None = None
a list of integers the same length as the total number of bands, denoting which bands to assign the same screening parameter to
- field pseudo_library: str [Required]
the pseudopotential library to use (for valid options, run koopmans pseudos list)
- field screening_method: CalculateScreeningMethod = CalculateScreeningMethod.DSCF
the method to calculate the screening parameters: either with ΔSCF or DFPT
- field spin: SpinType = SpinType.NONE
how to treat the spin degrees of freedom: ‘none’ (spin-unpolarized), ‘collinear’ (the system may break spin symmetry i.e. $n^{up}(r) != n^{down}(r)$), ‘non_collinear’ (spinor wavefunctions), or ‘spin_orbit’ (spinor wavefunctions with spin-orbit coupling)
- field task: Task = Task.SINGLEPOINT
Task to perform
- migrate_input_dict(input_dict: dict[str, Any]) dict[str, Any][source]
Upgrade a raw input dict to the current input file format version.
A missing
versionkey is treated as version 1 (the format predates the key).- Args:
input_dict: The raw input file contents.
- Returns:
The input dict, upgraded to
INPUT_FILE_FORMAT_VERSION.- Raises:
- ValueError: If the version is invalid or newer than this version of
koopmanssupports.
- read_input_file(filename: str | Path) KoopmansInput[source]
Read and parse a
koopmansinput file.- Args:
filename: Path to the input file (JSON or YAML format).
- Returns:
Parsed
KoopmansInputobject.- Raises:
ValueError: If the input file contains validation errors.