mag4.vasp

VASP input generation: per-config POSCAR / INCAR / KPOINTS for the four-state pipeline.

Layer: VASP-specific (one of the two DFT back-ends; see also wien2k.py).

Module Attributes

`FUNCTIONAL_CHOICES`	Recognised values for the `functional` argument of `incar_content()`.
`XC_CHOICES`	Backward-compatible alias (the historic flag was `--xc`).
`DEFAULT_KSPACING`	Default reciprocal-space k-point spacing (Å⁻¹), VASP-style.

Functions

`build_magmom_lines`(unique_groups, crystal, ...)	Return one MAGMOM string per unique configuration.
`create_config_dirs`(unique_groups, crystal, ...)	Create one directory per unique configuration with POSCAR (+ optional INCAR + KPOINTS).
`incar_content`(magmom, cfg_label, *[, ...])	Return the INCAR file content as a string for a given config label.
`resolve_kmesh`(lat_mat, *[, kspacing, kdens])	Resolve the Γ-mesh and how it was chosen.
`write_incar`(magmom, name, total_atoms, **kwargs)	Write an INCAR for Config #1.
`write_kpoints`(lat_mat, path, *[, kspacing, ...])	Write a Γ-centred automatic KPOINTS file.

mag4.vasp.build_magmom_lines(unique_groups, crystal, spin_magnitude)[source]

Return one MAGMOM string per unique configuration.

Atom order matches the POSCAR (crystal.all_species order). Magnetic atoms get ±spin_magnitude; all others get 0.

Return type:

List[str]

Parameters:

unique_groups (List[List[FourStateConfig]])
crystal (CrystalData)
spin_magnitude (float)

mag4.vasp.FUNCTIONAL_CHOICES = ('PBE', 'PBE+U', 'PBE0', 'R2SCAN', 'METAGGA')

Recognised values for the functional argument of incar_content().

PBE — plain GGA, no on-site Hubbard term, no exact exchange.
PBE+U — Dudarev/Liechtenstein DFT+U on the magnetic element only.
PBE0 — unscreened hybrid, AEXX=0.25 by default.
R2SCAN — convenience alias forcing METAGGA=R2SCAN.
METAGGA — meta-GGA family; --metagga selects the flavour (R2SCAN / SCAN / RSCAN / …).

mag4.vasp.XC_CHOICES = ('PBE', 'PBE+U', 'PBE0', 'R2SCAN', 'METAGGA'): Backward-compatible alias (the historic flag was --xc).

mag4.vasp.incar_content(magmom, cfg_label, *, functional=None, xc=None, elements=None, magnetic_element=None, ldaul=None, ldauu=None, ldauj=0.0, aexx=0.25, encut=500.0, metagga='R2SCAN', lmaxtau='auto', ldau_l=None, ldau_u=None, ldau_j=None)[source]

Return the INCAR file content as a string for a given config label.

Parameters:

magmom (str) – Pre-built MAGMOM string for this configuration.
cfg_label (str) – Human-readable tag printed in SYSTEM.
functional (Optional[str]) – Exchange-correlation choice. One of FUNCTIONAL_CHOICES (PBE, PBE+U, PBE0, R2SCAN, METAGGA). Case-insensitive.
xc (Optional[str]) – Backward-compatible alias for functional (the historic flag was --xc). functional takes precedence when both are supplied.
elements (Optional[List[str]]) – POSCAR element order — needed when functional == "PBE+U" so the LDAU arrays carry one slot per element, and used by the meta-GGA LMAXTAU heuristic.
magnetic_element (Optional[str]) – Symbol of the magnetic species (Cu, Ni, Gd, …). The LDAU values apply only to this element; every other element gets -1 / 0.0 / 0.0.
ldaul (Optional[int]) – Hubbard parameters for the magnetic element. ldaul is the orbital quantum number (2 for d, 3 for f); ldauu and ldauj are in eV. Required when functional == "PBE+U".
ldauu (Optional[float]) – Hubbard parameters for the magnetic element. ldaul is the orbital quantum number (2 for d, 3 for f); ldauu and ldauj are in eV. Required when functional == "PBE+U".
ldauj (float) – Hubbard parameters for the magnetic element. ldaul is the orbital quantum number (2 for d, 3 for f); ldauu and ldauj are in eV. Required when functional == "PBE+U".
aexx (float) – Fraction of exact exchange in the PBE0 hybrid (default 0.25). Ignored for non-hybrid functionals.
encut (float) – Plane-wave cut-off in eV written to ENCUT (default 500).
metagga (str) – Meta-GGA flavour written to the METAGGA tag when functional == "METAGGA" (default R2SCAN, but typical choices include SCAN, RSCAN, R2SCAN, R2SCANL). When functional == "R2SCAN" the value is forced to R2SCAN.
lmaxtau (Union[int, str]) – Meta-GGA LMAXTAU tag (s→2, p→4, d→6, f→8). "auto" (default): 8 if a lanthanide/actinide is present, else VASP’s default 6 is used (line commented out). Force 6 explicitly for f-in-core POTCARs (RE_3, La_s) where the 4f is not in the valence.
ldau_l (Optional[int]) – Deprecated hyphen-style aliases for ldaul/ldauu/ldauj — kept so older callers (and tests) keep working.
ldau_u (Optional[float]) – Deprecated hyphen-style aliases for ldaul/ldauu/ldauj — kept so older callers (and tests) keep working.
ldau_j (Optional[float]) – Deprecated hyphen-style aliases for ldaul/ldauu/ldauj — kept so older callers (and tests) keep working.

Return type:

str

mag4.vasp.write_incar(magmom, name, total_atoms, **kwargs)[source]

Write an INCAR for Config #1. Returns the file path.

Extra keyword arguments are forwarded to incar_content() (functional / xc, elements, magnetic_element, ldaul/ldauu/ldauj, aexx, encut, metagga, lmaxtau).

Return type:

str

Parameters:

magmom (str)
name (str)
total_atoms (int)

mag4.vasp.DEFAULT_KSPACING = 0.3: Default reciprocal-space k-point spacing (Å⁻¹), VASP-style. Denser than VASP’s own 0.5 Å⁻¹ default — well converged for the magnetic insulators / semiconductors this is usually applied to. METALS need a finer mesh (smaller KSPACING, ~0.15–0.2 Å⁻¹, with appropriate smearing): pass –kspacing explicitly for those.

mag4.vasp.resolve_kmesh(lat_mat, *, kspacing=None, kdens=None)[source]

Resolve the Γ-mesh and how it was chosen.

kspacing (VASP-style, Å⁻¹) takes precedence; else kdens (legacy, Å); else DEFAULT_KSPACING. Returns (mesh, mode, value) with mode in {"kspacing", "kdens"}.

Return type:

Tuple[Tuple[int, int, int], str, float]

Parameters:

lat_mat (ndarray)
kspacing (float | None)
kdens (float | None)

mag4.vasp.write_kpoints(lat_mat, path, *, kspacing=None, kdens=None)[source]

Write a Γ-centred automatic KPOINTS file.

The mesh follows VASP’s KSPACING rule by default (denser than VASP’s 0.5 Å⁻¹); pass kdens to use the legacy real-space density instead.

Return type:

str

Parameters:

lat_mat (ndarray)
path (str)
kspacing (float | None)
kdens (float | None)

mag4.vasp.create_config_dirs(unique_groups, crystal, magmom_lines, name, kdens=None, compound='', write_vasp_extras=True, *, kspacing=None, functional=None, xc=None, magnetic_element=None, ldaul=None, ldauu=None, ldauj=0.0, aexx=0.25, encut=500.0, metagga='R2SCAN', lmaxtau='auto', ldau_l=None, ldau_u=None, ldau_j=None)[source]

Create one directory per unique configuration with POSCAR (+ optional INCAR + KPOINTS).

Layout:

<compound>/config1/POSCAR
<compound>/config1/INCAR        (only if write_vasp_extras)
<compound>/config1/KPOINTS      (only if write_vasp_extras)
<compound>/config2/...

Parameters:

write_vasp_extras (bool, default True) – When False, only POSCAR is written (useful for the WIEN2k workflow, where POSCAR is later converted to case.struct via WIEN2k’s xyz2struct tool, and the magnetic information lives in case.inst instead).
unique_groups (List[List[FourStateConfig]])
crystal (CrystalData)
magmom_lines (List[str])
name (str)
kdens (float | None)
compound (str)
kspacing (float | None)
functional (str | None)
xc (str | None)
magnetic_element (str | None)
ldaul (int | None)
ldauu (float | None)
ldauj (float)
aexx (float)
encut (float)
metagga (str)
lmaxtau (int | str)
ldau_l (int | None)
ldau_u (float | None)
ldau_j (float | None)

Return type:

None