PAOFLOW.models.edtb_params#

Attributes#

`CURRENT_VERSION`
`SK_PARAM_NAMES`
`L_ORBITALS`
`LPAIR_LABELS`
`LPAIR_SK_NAMES`

Classes#

EDTBModel

User-facing interface for environment-dependent tight-binding models.

Functions#

`species_pair_key`(sp1, sp2)	Return the canonical species-pair key (alphabetically sorted, hyphen-separated).
`active_sk_names_for_basis`(l_channels_a, l_channels_b)	Return the SK parameter names active for a given species-pair basis.
`active_gamma_labels`(l_channels_a, l_channels_b)	Return the active screening-exponent (γ) labels for a species-pair basis.
`validate_params`(params)	Validate an EDTB parameter dict against the schema.
`validate_geometry`(geometry)	Validate a geometry dict against the schema.
`write_params`(filepath, params, *[, validate])	Write EDTB parameters to a JSON file.
`read_params`(filepath, *[, validate])	Read EDTB parameters from a JSON file.
`write_geometry`(filepath, geometry, *[, validate])	Write a geometry file (JSON).
`read_geometry`(filepath, *[, validate])	Read a geometry file (JSON).
`compute_shell_distances`(a_vectors, tau_list[, ...])	Compute neighbor-shell distances from lattice vectors and atomic basis.
`compute_pair_shell_distances`(a_vectors, atoms, sp1, sp2)	Compute neighbor-shell distances for a specific species pair.
`from_model_dict`(model_dict[, shell_distances])	Convert a PAOFLOW model dict to the new schema.
`to_model_dict`(params, geometry)	Convert new-format params + geometry to a model dict.
`summarize_params`(params)	Return a human-readable summary of an EDTB parameter dict.

Module Contents#

PAOFLOW.models.edtb_params.CURRENT_VERSION = '1.0'[source]#

PAOFLOW.models.edtb_params.SK_PARAM_NAMES = ['sss', 'sps', 'pps', 'ppp', 'sds', 'pds', 'pdp', 'dds', 'ddp', 'ddd'][source]#

PAOFLOW.models.edtb_params.L_ORBITALS[source]#

PAOFLOW.models.edtb_params.LPAIR_LABELS = ['ss', 'sp', 'sd', 'pp', 'pd', 'dd'][source]#

PAOFLOW.models.edtb_params.LPAIR_SK_NAMES[source]#

PAOFLOW.models.edtb_params.species_pair_key(sp1, sp2)[source]#

Return the canonical species-pair key (alphabetically sorted, hyphen-separated).

Parameters:

sp1 (str) – Species names (order does not matter).
sp2 (str) – Species names (order does not matter).

Returns:

Sorted, hyphen-joined key, e.g. 'Ge-Si'.

Return type:

str

Examples

>>> species_pair_key("Ge", "Si")
'Ge-Si'
>>> species_pair_key("Pt", "Pt")
'Pt-Pt'

PAOFLOW.models.edtb_params.active_sk_names_for_basis(l_channels_a, l_channels_b)[source]#

Return the SK parameter names active for a given species-pair basis.

Determines which Slater-Koster integrals are needed from the angular-momentum channels of the two species, preserving canonical ordering and avoiding duplicates.

Parameters:

l_channels_a (list of str) – Angular-momentum channels of species A (e.g. ['s', 'p', 'd']).
l_channels_b (list of str) – Angular-momentum channels of species B.

Returns:

Ordered SK parameter names from SK_PARAM_NAMES that are relevant for the given basis combination (e.g. ['sss', 'sps', 'pps', 'ppp'] for sp–sp).

Return type:

list of str

PAOFLOW.models.edtb_params.active_gamma_labels(l_channels_a, l_channels_b)[source]#

Return the active screening-exponent (γ) labels for a species-pair basis.

Analogous to active_sk_names_for_basis() but returns angular-momentum-pair labels (e.g. 'ss', 'pp') rather than individual SK integral names.

Parameters:

l_channels_a (list of str) – Angular-momentum channels of species A.
l_channels_b (list of str) – Angular-momentum channels of species B.

Returns:

Ordered, deduplicated l-pair labels from LPAIR_LABELS (e.g. ['ss', 'sp', 'pp'] for an sp-basis pair).

Return type:

list of str

PAOFLOW.models.edtb_params.validate_params(params)[source]#

Validate an EDTB parameter dict against the schema.

Checks for required top-level keys (edtb_version, basis, onsite, hoppings), orbital-to-l-channel consistency, correct SK parameter names per species pair, and optional screening entries.

Parameters:: params (dict) – EDTB parameter dict to validate.
Returns:: Human-readable error messages. An empty list means the dict is valid.
Return type:: list of str

PAOFLOW.models.edtb_params.validate_geometry(geometry)[source]#

Validate a geometry dict against the schema.

Checks for required keys alat, a_vectors (3×3 nested list), and atoms (each entry must have species and a 3-element tau).

Parameters:: geometry (dict) – Geometry dict to validate.
Returns:: Human-readable error messages. An empty list means the dict is valid.
Return type:: list of str

PAOFLOW.models.edtb_params.write_params(filepath, params, *, validate=True)[source]#

Write EDTB parameters to a JSON file.

Parameters:

filepath (str or Path) – Output path.
params (dict) – EDTB parameter dict conforming to the schema.
validate (bool) – If True, validate before writing.

Raises:

ValueError – If validate is True and the dict has schema violations.

PAOFLOW.models.edtb_params.read_params(filepath, *, validate=True)[source]#

Read EDTB parameters from a JSON file.

Parameters:

filepath (str or Path) – Input path.
validate (bool) – If True, validate after reading.

Returns:

EDTB parameter dict.

Return type:

dict

PAOFLOW.models.edtb_params.write_geometry(filepath, geometry, *, validate=True)[source]#

Write a geometry file (JSON).

Parameters:

filepath (str or Path) – Output path.
geometry (dict) – Geometry dict with keys alat, a_vectors, atoms.
validate (bool) – Validate before writing.

PAOFLOW.models.edtb_params.read_geometry(filepath, *, validate=True)[source]#

Read a geometry file (JSON).

Parameters:

filepath (str or Path) – Input path.
validate (bool) – If True (default), validate after reading.

Returns:

Geometry dict with keys alat, a_vectors, atoms.

Return type:

dict

Raises:

ValueError – If validate is True and the file has schema violations.

PAOFLOW.models.edtb_params.compute_shell_distances(a_vectors, tau_list, n_shells=3, r_max=20.0, tol=0.01)[source]#

Compute neighbor-shell distances from lattice vectors and atomic basis.

Parameters:

a_vectors (array-like, shape (3, 3)) – Lattice vectors in Bohr (already scaled by alat).
tau_list (list of array-like, shape (natoms, 3)) – Atomic positions in Bohr.
n_shells (int) – Number of distinct shells to return.
r_max (float) – Cutoff for neighbor search (Bohr).
tol (float) – Distance tolerance for grouping into shells (Bohr).

Returns:

Sorted shell distances (length ≤ n_shells).

Return type:

list of float

PAOFLOW.models.edtb_params.compute_pair_shell_distances(a_vectors, atoms, sp1, sp2, n_shells=3, r_max=20.0, tol=0.01)[source]#

Compute neighbor-shell distances for a specific species pair.

Unlike compute_shell_distances (which pools all atom pairs), this considers only bonds from sp1 atoms to sp2 atoms.

Parameters:

a_vectors (array-like, shape (3, 3)) – Lattice vectors in Bohr (already scaled by alat).
atoms (list of dict) – Atom dicts with "species" and "tau" keys (positions in Bohr).
sp1 (str) – Species names.
sp2 (str) – Species names.
n_shells (int) – Number of distinct shells to return.
r_max (float) – Cutoff for neighbor search (Bohr).
tol (float) – Distance tolerance for grouping into shells (Bohr).

Returns:

Sorted shell distances for the sp1–sp2 pair (length <= n_shells).

Return type:

list of float

PAOFLOW.models.edtb_params.from_model_dict(model_dict, shell_distances=None)[source]#

Convert a PAOFLOW model dict to the new schema.

Accepts both the old shell-tag-keyed format:

"hoppings": {"nn": {"sss": ...}, "nnn": {...}}

and the new species-pair-keyed format:

"hoppings": {"Pt-Pt": [{"r_ref": 5.247, "params": {"sss": ...}}, ...]}

Format detection is automatic.

Parameters:

model_dict (dict) – Model dict with keys label, alat, model.{a_vectors, atoms, hoppings, screening}.
shell_distances (dict, optional) – (Old format only) Shell tag → reference distance (Bohr), e.g. {"nn": 5.247, "nnn": 7.420, "nnnn": 9.090}. If None, distances are computed automatically from the lattice.

Returns:

params (dict) – New-format EDTB parameter dict.
geometry (dict) – New-format geometry dict.

PAOFLOW.models.edtb_params.to_model_dict(params, geometry)[source]#

Convert new-format params + geometry to a model dict.

Emits the species-pair-keyed hopping format, consistent with sk_fitting.build_model_dict.

Parameters:

params (dict) – EDTB parameter dict (new format).
geometry (dict) – Geometry dict (new format).

Returns:

Model dict with species-pair-keyed hoppings.

Return type:

dict

PAOFLOW.models.edtb_params.summarize_params(params)[source]#

Return a human-readable summary of an EDTB parameter dict.

Prints species, orbital counts, on-site energies, hopping shells (or distance-dependent channel coefficients), and screening exponents when present.

Parameters:: params (dict) – EDTB parameter dict (need not be valid; missing keys produce '?' placeholders).
Returns:: Multi-line formatted summary string.
Return type:: str

class PAOFLOW.models.edtb_params.EDTBModel(params, geometry, *, validate=True)[source]#

User-facing interface for environment-dependent tight-binding models.

Holds validated parameter and geometry data and provides a clean API for saving, loading, converting, and computing band structures.

Construction#

Direct:

model = EDTBModel(params_dict, geometry_dict)

From files:

model = EDTBModel.from_files("params.json", "geometry.json")

From a PAOFLOW model dict (old or new format):

model = EDTBModel.from_model_dict(model_dict)

From a fitted SKFitter / SKFitterEDTB:

model = EDTBModel.from_fitter(fitter, p_opt)

Serialisation#

model.save("params.json", "geometry.json")
md = model.to_model_dict()  # for PAOFLOW.PAOFLOW(model=md)

Band computation#

result = model.compute_bands(ibrav=2, nk=500)
print(result["bands_file"])   # path to bands_0.dat

Transferability#

new_model = model.with_geometry(new_geometry)  # same params, new cell

classmethod from_files(params_path, geometry_path, *, validate=True)[source]#

Load an EDTB model from JSON parameter and geometry files.

Parameters:

params_path (str or Path) – Path to the parameter file.
geometry_path (str or Path) – Path to the geometry file.
validate (bool) – Validate after loading (default True).

Return type:

EDTBModel

classmethod from_model_dict(model_dict, *, shell_distances=None)[source]#

Convert a PAOFLOW model dict to an EDTBModel.

Accepts both the old shell-tag-keyed format ("nn"/"nnn"/"nnnn" keys) and the new species-pair-keyed format. Detection is automatic.

Parameters:

model_dict (dict) – PAOFLOW model dict with label, alat, model.{a_vectors, atoms, hoppings, [screening]}.
shell_distances (dict, optional) – (Old format only) Shell tag → distance mapping (Bohr). If None, distances are computed from the lattice geometry.

Return type:

EDTBModel

classmethod from_fitter(fitter, p_opt)[source]#

Build an EDTBModel from a fitted SKFitter or SKFitterEDTB.

Calls fitter.build_model_dict(p_opt) internally and converts the result to the new schema.

Parameters:

fitter (SKFitter | SKFitterEDTB | MultiGeomEDTB) – Fitted fitter object.
p_opt (array-like) – Optimised parameter vector.

Return type:

EDTBModel

save(params_path, geometry_path=None, *, validate=True)[source]#

Write parameter (and optionally geometry) files.

Parameters:

params_path (str or Path) – Output path for the parameter file.
geometry_path (str or Path, optional) – Output path for the geometry file. If None, only the parameter file is written.
validate (bool) – Validate before writing (default True).

to_model_dict()[source]#

Convert to a PAOFLOW model dict.

The returned dict can be passed directly to PAOFLOW.PAOFLOW(model=...).

Returns:: Model dict with species-pair-keyed hoppings.
Return type:: dict

with_geometry(geometry)[source]#

Return a new EDTBModel with the same parameters but a different geometry.

This is the main transferability mechanism: train once, apply to arbitrary cells / strains / defects with the same species.

Parameters:: geometry (dict) – New geometry dict (alat, a_vectors, atoms).
Returns:: New model sharing the same parameters.
Return type:: EDTBModel
Raises:: ValueError – If the new geometry contains species not in the model.

classmethod from_geometry_file(params_path, geometry_path)[source]#

Load parameters from one file and geometry from another.

Identical to from_files(); provided for readability in transferability workflows where the same parameter file is reused with different geometries.

Parameters:

params_path (str or Path) – Path to the EDTB parameter JSON file.
geometry_path (str or Path) – Path to the geometry JSON file.

Return type:

EDTBModel

compute_bands(*, ibrav=0, nk=500, outputdir=None, band_path=None, high_sym_points=None, smearing='gauss', verbose=False)[source]#

Compute the band structure using PAOFLOW.

Parameters:

ibrav (int) – Bravais lattice type (default 0).
nk (int) – Number of k-points along the path (default 500).
outputdir (str, optional) – Directory for output files. If None, a temporary directory is used (based on the model label and alat).
band_path (str, optional) – Custom band path (e.g. "L-G-X").
high_sym_points (dict, optional) – Custom high-symmetry point coordinates.
smearing (str) – Smearing type (default "gauss").
verbose (bool) – Print PAOFLOW output (default False).

Returns:

bands_file : str — path to bands_0.dat sym_file : str — path to kpath_points.txt paoflow : PAOFLOW object (for further analysis)

Return type:

dict

property params: dict[source]#: The EDTB parameter dict (read-only copy).

property geometry: dict[source]#: The geometry dict (read-only copy).

property species: List[str][source]#: Sorted list of species in the model.

property n_species: int[source]#: Number of distinct species.

property n_shells: int[source]#: Maximum number of neighbor shells across species pairs.

property has_screening: bool[source]#: Whether screening (EDTB) parameters are present.

property label: str[source]#

'SK_EDTB' or 'Slater_Koster'.

Type:: Model label

property alat: float[source]#: Lattice parameter from the geometry (Bohr).

summary()[source]#: Return a human-readable summary of the model.