PAOFLOW.pyskeaf.orbits

Detection of closed extremal orbits in one 2D slice.

Modernised replacement for the Fortran sliceext walking algorithm (skeaf_v1p3p0_r149.F90 lines 3768–4445). Instead of the pixel-by-pixel boundary walk we use skimage.measure.find_contours to obtain the iso-EF level sets of the slice in one vectorised pass, then compute the same per-orbit observables (area, centroid, std, bbox, orbit type, effective mass) that sliceext populates into the global slfs* arrays.

Outputs match the Fortran semantics:

• areas in Å^-2

• frequencies in kT (= Tesla × 1000) via CONV_FSAREA_TO_KT

• effective mass in electron masses via CONV_FSDADE_TO_MSTAR

• fractional supercell coordinates avg_xy_frac, std_xy_frac, min/max_xy_frac in [0, 1]

• orbit type +1 electron-like, -1 hole-like, 0 ambiguous

Phase 4 additions (cross-slice matching, extremum detection, averaging) appear after find_closed_orbits_in_slice() below. They are direct translations of the main-program loops in skeaf_v1p3p0_r149.F90 lines 1410–2700, preserving the 19-condition matching predicate, the bifurcation detection (forward + reverse), the floater-displacement loop (capped at 500 iterations), the supercell→RUC centroid mapping, the same-centre grouping with periodic ±1 wrap, and the freq-similarity averaging.

Classes

SliceOrbit	One closed FS contour found in a single slice.
Chunk	A trajectory of one orbit through consecutive slices.
ExtremalOrbit	One extremum found inside a chunk (one local min/max of area vs slice).
AveragedOrbit	One physical extremal orbit (after averaging supercell copies).

Functions

find_closed_orbits_in_slice(slice2d, fermi_energy, *)	Locate every closed FS orbit in one slice and compute its observables.
match_chunks(per_slice_orbits)	Build chunks from a list of per-slice orbit lists.
find_extremal(chunks, geom, *[, min_freq_kT, ...])	Find extremal orbits within each chunk (Fortran lines 1965–2050).
average_orbits(extrema, *[, freq_same_frac, avg_same_frac])	Group supercell-copy extrema, average each group, and return sorted-by-frequency.

Module Contents

class PAOFLOW.pyskeaf.orbits.SliceOrbit

One closed FS contour found in a single slice.

slice_index: int

contour_xy: numpy.ndarray

area: float

inside_area: float

frequency_kT: float

effective_mass: float

orbit_type: int

avg_xy_frac: numpy.ndarray

std_xy_frac: numpy.ndarray

min_xy_frac: numpy.ndarray

max_xy_frac: numpy.ndarray

n_points: int

is_open: bool

is_too_small: bool

PAOFLOW.pyskeaf.orbits.find_closed_orbits_in_slice(slice2d, fermi_energy, *, keep_too_small=False, keep_open=False)

Locate every closed FS orbit in one slice and compute its observables.

Parameters:

• slice2d (PAOFLOW.pyskeaf.slice_ops.Slice2D) – Energies sampled on the (numx × numy) supercell slice.

• fermi_energy (float) – Fermi level in Rydbergs.

• keep_too_small (bool) – If True, retain orbits whose area is below minarea = 2 Δkx Δky (Fortran minarea) or that touch the supercell boundary. These are flagged via is_too_small / is_open while their area / frequency / mass fields remain populated for diagnostics. Default behaviour mirrors Fortran (drops them).

• keep_open (bool) – If True, retain orbits whose area is below minarea = 2 Δkx Δky (Fortran minarea) or that touch the supercell boundary. These are flagged via is_too_small / is_open while their area / frequency / mass fields remain populated for diagnostics. Default behaviour mirrors Fortran (drops them).

class PAOFLOW.pyskeaf.orbits.Chunk

A trajectory of one orbit through consecutive slices.

Mirrors the Fortran c* arrays (carea, cavgx, cnobif, cfsfromslice…) indexed by chunk number and per-chunk position. orbits[i] is the SliceOrbit at the i-th step in the chunk; no_bif[i] mirrors cnobif at that position. slice_indices[i] is the 1-based slice that orbit was found on.

orbits: List[SliceOrbit]

no_bif: List[bool]

property slice_indices: List[int]

class PAOFLOW.pyskeaf.orbits.ExtremalOrbit

One extremum found inside a chunk (one local min/max of area vs slice).

slice_orbit: SliceOrbit

chunk_index: int

cfs_index: int

curvature_kT_A2: float

avg_xyz_ruc: numpy.ndarray

class PAOFLOW.pyskeaf.orbits.AveragedOrbit

One physical extremal orbit (after averaging supercell copies).

frequency_kT: float

frequency_std_kT: float

effective_mass: float

effective_mass_std: float

curvature_kT_A2: float

curvature_std_kT_A2: float

orbit_type: float

orbit_type_std: float

avg_xyz_ruc: numpy.ndarray

avg_xyz_ruc_std: numpy.ndarray

num_copies: int

representative: ExtremalOrbit

PAOFLOW.pyskeaf.orbits.match_chunks(per_slice_orbits)

Build chunks from a list of per-slice orbit lists.

per_slice_orbits[s-1] (1-based slice s) is the output of find_closed_orbits_in_slice() for slice s. Returns the list of chunks (in order of creation).

Implements the full matching logic of skeaf lines 1410–1953 including forward/reverse bifurcation detection and the floater displacement loop (capped at 500 iterations per slice-orbit, matching Fortran).

PAOFLOW.pyskeaf.orbits.find_extremal(chunks, geom, *, min_freq_kT=0.0, allow_near_walls=False)

Find extremal orbits within each chunk (Fortran lines 1965–2050).

For each interior position in a chunk (i.e. not at chunk endpoints), flag the orbit as extremal if its area is a local min, local max, or equals its predecessor’s. Compute curvature from the 3-point neighbourhood and convert centroid to RUC fractional coords. Apply minextfreq cutoff and (optionally) reject orbits whose bbox lies within 2·std of a supercell wall (matching Fortran’s allowextnearwalls default-no behaviour).

PAOFLOW.pyskeaf.orbits.average_orbits(extrema, *, freq_same_frac=0.01, avg_same_frac=0.05)

Group supercell-copy extrema, average each group, and return sorted-by-frequency.

Combines the same-centre grouping (lines 2188–2266) with the per-group frequency clustering (lines 2284–2453) and the final global frequency sort (lines 2474–2538).