PAOFLOW.models.dual_params

Attributes

ANGSTROM_AU

Classes

MultiParamModel	Multi-parameter tight-binding model with site-labeled atoms.
DualParamModel	Dual-parameter tight-binding model (backward-compatible wrapper).

Functions

label_atoms_coordination(geometry[, r_cut_bohr, ...])	Label atoms as 'bulk' or 'surface' based on coordination number.
label_atoms_geometric(geometry[, n_surface_layers, ...])	Label atoms based on distance from the vacuum surface.
label_atoms_manual(n_atoms, surface_indices)	Label atoms from an explicit list of surface atom indices.

Module Contents

PAOFLOW.models.dual_params.ANGSTROM_AU = 1.8897261328856432

PAOFLOW.models.dual_params.label_atoms_coordination(geometry, r_cut_bohr=8.0, threshold=None, r_taper_frac=0.8)

Label atoms as ‘bulk’ or ‘surface’ based on coordination number.

The smooth coordination number is defined as:

Z_i = Σ_{k ≠ i} f_c(d_{ik})

where f_c is a cosine-tapered cutoff function. Atoms with Z_i ≥ threshold are labeled ‘bulk’; others ‘surface’.

Parameters:

• geometry (dict) – Geometry dict (alat, a_vectors, atoms).

• r_cut_bohr (float) – Cutoff radius in Bohr for the smooth cutoff.

• threshold (float, optional) – Coordination threshold. If None, uses (max + min) / 2.

• r_taper_frac (float) – Fraction of r_cut at which tapering begins (default 0.8).

Returns:

• labels (list of str) – ‘bulk’ or ‘surface’ for each atom.

• coord (ndarray) – Smooth coordination numbers.

PAOFLOW.models.dual_params.label_atoms_geometric(geometry, n_surface_layers=2, surface_normal=None)

Label atoms based on distance from the vacuum surface.

For slab geometries, atoms near the top/bottom surfaces are labeled ‘surface’. The surface normal is identified from the longest lattice vector (slab direction).

Parameters:

• geometry (dict) – Geometry dict.

• n_surface_layers (int) – Number of atomic layers from each surface to label ‘surface’.

• surface_normal (ndarray, optional) – Explicit surface normal. If None, uses the longest a_vector.

Returns:

• labels (list of str)

• projections (ndarray) – Signed distances along the surface normal.

PAOFLOW.models.dual_params.label_atoms_manual(n_atoms, surface_indices)

Label atoms from an explicit list of surface atom indices.

Parameters:

• n_atoms (int) – Total number of atoms.

• surface_indices (list of int) – Indices of atoms to label as ‘surface’.

Returns:

labels

Return type:

list of str

class PAOFLOW.models.dual_params.MultiParamModel(params_map, geometry, labels, *, mixing='geometric', ref_label=None)

Multi-parameter tight-binding model with site-labeled atoms.

Uses an arbitrary number of independently fitted parameter sets, with atoms labeled by environment. Supports multi-species systems. Interface bonds (between atoms with different labels) are handled with configurable mixing rules.

Construction

model = MultiParamModel(
    params_map={
        'Si_bulk': si_bulk_params,
        'Ge_bulk': ge_bulk_params,
        'interface': sige_params,
    },
    geometry=superlattice_geometry,
    labels=['Si_bulk']*8 + ['Ge_bulk']*8,
)

From files:

model = MultiParamModel.from_files(
    params_files={'bulk': 'Si_params.json', 'surface': 'Si_surf_params.json'},
    geometry='slab_geometry.json',
    labels=[...],
)

Hamiltonian

HRs, meta = model.build_hamiltonian()
model_dict = model.to_model_dict()
pao = PAOFLOW(model=model_dict)
arry, attr = pao.data_controller.data_dicts()
arry['HRs'] = HRs
pao.bands(ibrav=0, band_path='G-X-M-G', nk=500)

classmethod from_files(params_files, geometry, labels, **kwargs)

Load from JSON files.

Parameters:

• params_files (dict[str, str|Path]) – {label: path_to_params_json}.

• geometry (str or Path) – Path to geometry JSON file.

• labels (list of str) – Per-atom environment labels.

• **kwargs – Passed to constructor (mixing, ref_label).

Return type:

MultiParamModel

classmethod from_edtb_models(models, geometry, labels, **kwargs)

Create from a dict of EDTBModel objects and a new geometry.

Parameters:

• models (dict[str, EDTBModel]) – {label: fitted_model}.

• geometry (dict) – Target geometry.

• labels (list of str) – Per-atom environment labels.

• **kwargs – Passed to constructor.

Return type:

MultiParamModel

to_model_dict()

Return a PAOFLOW-compatible model dict.

Uses the reference label’s parameters for metadata. Replace arry['HRs'] with the multi-parameter H(R) from build_hamiltonian() before calling pao.bands().

build_hamiltonian(verbose=True)

Build the real-space Hamiltonian H(R).

Returns:

• HRs (ndarray, complex, shape (nawf, nawf, nk1, nk2, nk3, 1))

• meta (dict)

property labels: List[str]

Per-atom environment labels.

property mixing: str

Mixing rule for interface bonds.

property geometry: dict

Geometry dict (deep copy).

property n_atoms: int

property unique_labels: List[str]

Sorted list of unique labels.

property params_map: Dict[str, dict]

Parameter sets (deep copy).

label_counts()

Return a dict of {label: count}.

label_summary()

Return a summary of atom labels.

class PAOFLOW.models.dual_params.DualParamModel(params_bulk, params_surf, geometry, *, labels=None, mixing='geometric', labeling='coordination', label_kwargs=None)

Dual-parameter tight-binding model (backward-compatible wrapper).

Thin wrapper around MultiParamModel that preserves the original two-parameter (P_bulk, P_surf) API with automatic ‘bulk’/’surface’ labeling.

Construction

From files:

model = DualParamModel.from_files(
    params_bulk="Si_SK_params.json",
    params_surf="Si_surface_EDTB_params.json",
    geometry="Surface_Si/Si_111_slab_geom.json",
)

Labeling is applied automatically (default: coordination-based). Override with labeling='geometric', labeling='manual', or pass explicit labels=[...].

Hamiltonian

HRs, meta = model.build_hamiltonian()
model_dict = model.to_model_dict()
pao = PAOFLOW(model=model_dict)
arry, attr = pao.data_controller.data_dicts()
arry['HRs'] = HRs
pao.bands(ibrav=0, band_path='G-M-K-G', nk=500)

classmethod from_files(params_bulk, params_surf, geometry, **kwargs)

Load bulk and surface parameters and geometry from JSON files.

Parameters:

• params_bulk (str or Path) – Path to the bulk EDTB parameter JSON file.

• params_surf (str or Path) – Path to the surface EDTB parameter JSON file.

• geometry (str or Path) – Path to the geometry JSON file.

• **kwargs – Forwarded to the constructor (mixing, labeling, labels, label_kwargs).

Return type:

DualParamModel

classmethod from_edtb_models(model_bulk, model_surf, geometry, **kwargs)

Create a dual-parameter model from two fitted EDTBModel objects.

Parameters:

• model_bulk (EDTBModel) – Fitted model for the bulk environment.

• model_surf (EDTBModel) – Fitted model for the surface environment.

• geometry (dict) – Target geometry dict (may differ from training geometry).

• **kwargs – Forwarded to the constructor.

Return type:

DualParamModel

to_model_dict()

Return a PAOFLOW-compatible model dict (using bulk parameters).

build_hamiltonian(verbose=True)

Build the real-space Hamiltonian H(R).

property labels: List[str]

Atom labels (‘bulk’ or ‘surface’).

property coord: numpy.ndarray | None

Coordination numbers (if coordination labeling was used).

property mixing: str

property geometry: dict

property n_atoms: int

property n_bulk: int

property n_surface: int

label_summary()

Return a summary of atom labels with coordination numbers.