PAOFLOW.inputs.basis_presets#

Automated internal-basis (configuration) presets for PAOFLOW.

This module turns string presets such as "minimal" and "extended" into the per-species {element: [shell_labels]} dictionary consumed by PAOFLOW.projection.do_atwfc_proj.build_aewfc_basis().

"minimal" — the set of occupied pseudo-atomic wavefunctions found in each species’ UPF pseudopotential (PP_PSWFC/PP_CHI entries with positive occupation).
"standard" — the minimal set with each angular channel doubled by adding the next principal-quantum-number shell (e.g. 3S, 3P → 3S, 3P, 4S, 4P). Roughly doubles the orbital count of "minimal".
"extended" — the minimal set augmented by a small, rule-based set of polarization shells, drawn from the all-electron wavefunctions shipped in BASIS/<element>/*.dat.

The user-facing dispatch lives in PAOFLOW.PAOFLOW.projections(); this module is intentionally side-effect-free and easy to unit test.

Attributes#

SUPPORTED_PRESETS

Functions#

`element_block`(elem)	Return the periodic-table block (`'s'`, `'p'`, `'d'` or `'f'`).
`available_ae_shells`(basispath, elem)	List the AE shell labels available for `elem` in `basispath`.
`minimal_shells_from_upf`(data_controller, elem)	Return the PP_PSWFC shell labels shipped with `elem`'s UPF.
`standard_augmentation`(elem, minimal_shells)	Augmentation rule for the `"standard"` preset.
`extended_augmentation`(elem, minimal_shells)	Rule-based AE polarization shells to add to `minimal_shells`.
`resolve_configuration`(data_controller, preset)	Turn a string preset into a `{element: [augment_shells]}` dict.
`resolve_configuration_dict`(data_controller, spec)	Resolve a per-element `configuration` dict.

Module Contents#

PAOFLOW.inputs.basis_presets.SUPPORTED_PRESETS = ('minimal', 'standard', 'extended')[source]#

PAOFLOW.inputs.basis_presets.element_block(elem)[source]#

Return the periodic-table block ('s', 'p', 'd' or 'f').

Parameters:: elem (str) – Chemical symbol, case-sensitive (e.g. 'Fe').
Raises:: KeyError – If elem is not in the internal element table.

PAOFLOW.inputs.basis_presets.available_ae_shells(basispath, elem)[source]#

List the AE shell labels available for elem in basispath.

Globs <basispath>/<elem>/*.dat and returns the orbital labels (e.g. ['1S', '2S', '2P', '3S', '3P', '3D', ...]) sorted by principal quantum number then by angular momentum.

Returns an empty list if the directory is missing or contains no recognisable nL.dat files.

PAOFLOW.inputs.basis_presets.minimal_shells_from_upf(data_controller, elem)[source]#

Return the PP_PSWFC shell labels shipped with elem’s UPF.

Reads the species’ UPF file and returns the labels of every PP_CHI entry, preserving the order in which they appear in the pseudopotential. Duplicates (rare, but possible for spin-orbit pseudos where two j-channels share a label) are collapsed.

All PSWFC entries are included regardless of occupation: an unoccupied PSWFC (e.g. Pt 6P, occ=0) is still a physical pseudo-atomic orbital generated together with the pseudopotential, and is typically the dominant bonding/conduction channel. Excluding such shells leaves the corresponding QE bands unprojectable, which silently lowers the AE-basis standard/extended Pn>0.95 band count below that of the minimal preset (which reads every PSWFC unconditionally via build_pswfc_basis_all()).

Raises:: RuntimeError – If no UPF can be located for elem.

PAOFLOW.inputs.basis_presets.standard_augmentation(elem, minimal_shells)[source]#

Augmentation rule for the "standard" preset.

Builds on top of the minimal valence set with two complementary additions:

Polarization (next missing L) — append the next angular momentum channel beyond the highest one present in the minimal set, at the largest principal quantum number nmax of the minimal set. For Si (minimal 3S, 3P) this adds 3D; for a transition metal with minimal 4S, 3D this adds 4F (only when elem is in the f-block) or 4F is skipped otherwise. The added shell is also clamped to the physical minimum n for that L (nP ≥ 2, nD ≥ 3, nF ≥ 4).
Radial doubling (next n, same L) — for each nL in the minimal set append (n+1)L. This roughly doubles the radial freedom of every occupied angular channel.

The result is intermediate between "minimal" (only the occupied valence) and "extended" (generous multi-row polarization). For Si the standard set becomes [3S, 3P, 3D, 4S, 4P].

Duplicates and shells already in minimal_shells are skipped. Unknown elements or an empty minimal set yield an empty list. The F-channel polarization is only added for f-block elements; on s/p/d-block elements the augmentation stops at the D channel.

PAOFLOW.inputs.basis_presets.extended_augmentation(elem, minimal_shells)[source]#

Rule-based AE polarization shells to add to minimal_shells.

The "extended" preset is built on top of the all-electron basis in basispath (build_aewfc_basis), so augmentation must be generous: AE radial functions carry core-region nodes and the Loewdin orthogonalization needs enough variational freedom to span both the valence and a few conduction-like channels. This rule targets roughly the hand-tuned configurations that ship with the PAOFLOW examples (≈ 11 shells per atom for GaAs).

Augmentation per block (nmax = largest principal quantum number present in minimal_shells):

s/p/d/f blocks — append S and P shells for n = nmax, nmax+1, nmax+2 (clamped to n ≥ 1 for S and n ≥ 2 for P).
D channel — append nD for n = max(3, nmax) … nmax+1 (skips sub-valence D rows, which are either genuine semicore shells already present in minimal_shells or frozen-core shells the pseudopotential cannot represent).
F channel — only for f-block elements; append nF for n = max(4, nmax−1) … nmax.

Shells already present in minimal_shells are skipped. Unknown elements or an empty minimal set yield an empty list.

PAOFLOW.inputs.basis_presets.resolve_configuration(data_controller, preset)[source]#

Turn a string preset into a {element: [augment_shells]} dict.

In the current “mixed” scheme the pseudo-atomic wavefunctions from the UPF always serve as the baseline projection set; presets only control which extra all-electron shells are loaded from basispath on top of that baseline.

"minimal" — returns the occupied PSWFC shells read from the UPF for each species. The caller should build a pure pseudo basis with build_pswfc_basis_all(); the returned dict is kept for diagnostics.
"extended" — returns the minimal valence set plus a generous rule-based augmentation drawn from basispath (see extended_augmentation()). The caller should feed this dict to build_aewfc_basis() (AE-only path). Shells that are not present on disk are dropped with a RuntimeWarning.

To choose exactly which orbitals enter the basis, pass a per-element dict instead of a preset string (handled by resolve_configuration_dict()). Each value may independently be a preset name or an explicit list of shells, e.g. {'Ga': 'standard', 'As': ['4S', '4P', '3D']}.

Notes

A mixed scheme combining pseudo PSWFC with AE polarization is implemented in build_mixed_basis() but currently not wired through this preset: raw AE orbitals carry core-region oscillations that the smooth QE pseudo Bloch states cannot project onto, producing ill-conditioned overlaps. Re-enabling the mixed scheme requires AE pseudization first.

Parameters:

data_controller (DataController) – Populated controller; needs data_arrays['atoms'], data_arrays['species'] and data_attributes['fpath']. data_attributes['basispath'] is additionally required for "extended".
preset (str) – One of SUPPORTED_PRESETS (case-insensitive).

Returns:

Mapping {element: [shells]} suitable for assignment to arry['configuration'].

Return type:

dict

Raises:

ValueError – If preset is not recognised, or if "extended" is requested without data_attributes['basispath'] being set.

PAOFLOW.inputs.basis_presets.resolve_configuration_dict(data_controller, spec)[source]#

Resolve a per-element configuration dict.

Each value may independently be a preset name string or an explicit list of shell labels, so the user can ask for a curated preset on some species while hand-picking orbitals on others:

configuration = {
    'Ga': 'standard',                   # rule-based augmentation
    'As': ['4S', '4P', '3D'],           # only these orbitals
}

Explicit lists are taken verbatim (only the angular-momentum letter is upper-cased).

Parameters:

data_controller (DataController) – Populated controller (see resolve_configuration()).
spec (dict) – Mapping {element: (preset_name | [shells])}.

Returns:

Mapping {element: [shells]}.

Return type:

dict