PAOFLOW.models.surface_project#
surface_project.py — Projected bulk band structure onto arbitrary surface planes.
Given a bulk tight-binding model (via PAOFLOW model dictionary) and a surface normal direction, this module:
Identifies the shortest reciprocal-lattice vector G₀ parallel to the surface normal — this sets the k⊥ periodicity.
Finds the two shortest in-plane real-space lattice vectors, defining the 2D surface lattice and its reciprocal (surface Brillouin zone).
Auto-detects the surface-BZ type (square, hexagonal, rectangular, oblique) and provides default high-symmetry paths.
For each k∥ along the surface-BZ path, sweeps k⊥ over one full period and collects all bulk eigenvalues.
Computes per-band envelopes (min / max over k⊥) and identifies projected gaps and lens-shaped features.
Produces a shaded figure of the projected band structure.
Public API#
project_bulk_bands — main computation project_from_model — convenience wrapper for EDTBModel objects find_absolute_gaps — locate energy gaps persistent at all k∥ plot_projected — shaded band-projection figure SurfaceProjectionResult — dataclass container
Pre-defined constants#
SURFACE_001, SURFACE_110, SURFACE_111 — common surface normals SURFACE_SYM_SQUARE, SURFACE_SYM_HEX, SURFACE_SYM_RECT — surface BZ points
References
F. J. Himpsel and D. E. Eastman, J. Vac. Sci. Technol. 16, 1297 (1979). M. C. Desjonquères and D. Spanjaard, Concepts in Surface Physics (Springer, 1996).
Attributes#
Classes#
Container for projected bulk band structure results. |
Functions#
|
Compute the projected bulk band structure onto a surface plane. |
|
Project bulk bands using an EDTBModel object directly. |
|
Find energy gaps that persist at every k∥ point. |
|
Find projected band gaps at each individual k∥ point. |
|
Plot the projected bulk band structure as a shaded E-vs-k∥ figure. |
|
Identify "lens" features where a gap opens and closes along k∥. |
Module Contents#
- class PAOFLOW.models.surface_project.SurfaceProjectionResult[source]#
Container for projected bulk band structure results.
- Variables:
kdist ((nk_par,) cumulative k∥ distance along the surface path.)
sym_ticks (list of (distance, label) for surface-BZ symmetry ticks.)
band_min ((nk_par, nawf) minimum eigenvalue of band n over k⊥.)
band_max ((nk_par, nawf) maximum eigenvalue of band n over k⊥.)
nawf (number of Wannier functions (bands).)
nk_perp (number of k⊥ sample points.)
surface_normal ((3,) unit surface-normal direction (Cartesian / alat).)
G_perp ((3,) shortest reciprocal vector along normal (1/alat).)
surf_vectors ((2, 3) primitive surface real-space lattice vectors.)
surf_recip ((2, 3) surface reciprocal-lattice vectors.)
a_bulk ((3, 3) bulk lattice vectors (rows).)
lattice_2d (str — detected 2D lattice type.)
- kdist: numpy.ndarray[source]#
- band_min: numpy.ndarray[source]#
- band_max: numpy.ndarray[source]#
- all_evals: numpy.ndarray[source]#
- surface_normal: numpy.ndarray[source]#
- G_perp: numpy.ndarray[source]#
- surf_vectors: numpy.ndarray[source]#
- surf_recip: numpy.ndarray[source]#
- a_bulk: numpy.ndarray[source]#
- PAOFLOW.models.surface_project.project_bulk_bands(model_dict, surface_normal, *, surface_sym_points=None, surface_path=None, nk_par=100, nk_perp=100, verbose=True)[source]#
Compute the projected bulk band structure onto a surface plane.
For each k∥ along a high-symmetry path in the 2D surface Brillouin zone, the function sweeps k⊥ over one full period (the 1D BZ perpendicular to the surface) and collects all bulk eigenvalues. The per-band envelopes (min / max over k⊥) define the projected band structure.
- Parameters:
model_dict (PAOFLOW-compatible model dictionary for the bulk) – crystal. Must contain
'model'key with'a_vectors'and'atoms'.surface_normal ((3,) array-like — Cartesian direction perpendicular) – to the surface. Common choices for cubic crystals:
[0,0,1]for (001),[1,1,0]for (110),[1,1,1]for (111). Need not be a unit vector.surface_sym_points (dict, optional — high-symmetry points in the) – surface BZ as
{label: [f1, f2]}fractional coordinates in the surface reciprocal basis. If None, auto-detected from the 2D lattice type.surface_path (str, optional — path string, e.g.
'Γ-X-M-Γ'.) – If None, auto-detected.nk_par (int — number of k∥ points per path segment.)
nk_perp (int — number of k⊥ sample points.)
verbose (bool — print progress information.)
- Returns:
SurfaceProjectionResult dataclass with band envelopes, eigenvalues,
and surface geometry metadata.
- PAOFLOW.models.surface_project.project_from_model(model, surface_normal, **kwargs)[source]#
Project bulk bands using an EDTBModel object directly.
- Parameters:
model (EDTBModel for the bulk crystal.)
surface_normal ((3,) Cartesian surface-normal direction.)
**kwargs (forwarded to
project_bulk_bands().)
- Return type:
- PAOFLOW.models.surface_project.find_absolute_gaps(result, y_lim=(-12, 6), tol=0.01)[source]#
Find energy gaps that persist at every k∥ point.
A gap is a contiguous energy interval in which no bulk state exists at any k∥. These are the “absolute” or “true” projected band gaps where surface states may reside.
- Parameters:
result (SurfaceProjectionResult from
project_bulk_bands().)y_lim (energy window to consider, (E_min, E_max) in eV.)
tol (merge tolerance for near-touching intervals (eV).)
- Returns:
gaps
- Return type:
list of
(E_lo, E_hi)for each absolute gap, sorted by energy.
- PAOFLOW.models.surface_project.find_gaps_at_kpar(result, y_lim=(-12, 6), tol=0.01)[source]#
Find projected band gaps at each individual k∥ point.
- Returns:
gaps_per_k –
(E_lo, E_hi)gap intervals at that k∥.- Return type:
list of length nk_par. Each element is a list of
- PAOFLOW.models.surface_project.plot_projected(result, *, y_lim=(-12, 6), color='steelblue', alpha=0.45, gap_color='lightyellow', show_gaps=True, mode='fill', ne=500, surface_bands=None, surface_kdist=None, figsize=(10, 6), title=None, show=True, ax=None)[source]#
Plot the projected bulk band structure as a shaded E-vs-k∥ figure.
- Parameters:
result (SurfaceProjectionResult from
project_bulk_bands().)y_lim (energy window (eV).)
color (fill colour for bulk-band regions.)
alpha (opacity (used in
'fill'mode).)gap_color (background colour for gap regions (
'image'mode).)show_gaps (if True, highlight absolute gaps.)
mode (
'fill'—fill_betweenper band (overlapping bands) – appear darker, giving a qualitative DOS indication);'image'— binary contour-fill (uniform colour inside bulk regions, clean edges).ne (energy resolution for
'image'mode.)surface_bands ((nk_par, n_surf_bands) array of surface-state) – eigenvalues to overlay (optional).
surface_kdist ((nk_par,) k-distances for surface bands (optional;) – defaults to
result.kdist).figsize (figure size for a new figure.)
title (plot title.)
show (call
plt.show().)ax (existing matplotlib Axes (optional).)
- Return type:
fig, ax
- PAOFLOW.models.surface_project.find_band_lenses(result, y_lim=(-12, 6), tol=0.01)[source]#
Identify “lens” features where a gap opens and closes along k∥.
A band lens occurs when two adjacent projected bands have a gap at some k∥ values but overlap at others, producing a lens-shaped gap region in the (k∥, E) plane.
- Parameters:
result (SurfaceProjectionResult)
y_lim (energy window.)
tol (energy tolerance for gap detection (eV).)
- Returns:
lenses –
'gap_center'— (float) mean energy of the lens midpoint,'max_gap'— (float) maximum gap width (eV),'k_range'— (float, float) k-distance range where gap exists,'k_indices'— (int, int) index range in kdist.- Return type:
list of dicts, each with keys: