Skip to content

Analysis API

High-throughput parameter scanning for materials screening.

ParameterScanner

Main class for running parameter sweeps over ΔQ, ΔE, and phonon frequencies.

carriercapture.analysis.parameter_scan.ParameterScanner

High-throughput parameter scanner for materials screening.

Scans parameter space (ΔQ, ΔE, ℏω) to compute capture coefficients for many material configurations. Supports parallel execution.

Parameters:

Name Type Description Default
params ScanParameters

Scan configuration

 required
verbose bool

Print progress information

 True

Examples:

>>> params = ScanParameters(
...     dQ_range=(0, 25, 25),
...     dE_range=(0, 2.5, 10),
... )
>>> scanner = ParameterScanner(params)
>>> results = scanner.run_harmonic_scan(n_jobs=4)
>>> results.save("scan_results.npz")

run_harmonic_scan(n_jobs=1, show_progress=True)

Run parameter scan with harmonic potentials.

Parameters:

Name Type Description Default
n_jobs int

Number of parallel jobs. Use -1 for all cores.

 1
show_progress bool

Show progress bar

 True

Returns:

Type Description
ScanResult

Scan results with capture coefficients and barrier heights

Examples:

>>> scanner = ParameterScanner(params)
>>> results = scanner.run_harmonic_scan(n_jobs=4)
>>> print(f"Computed {results.capture_coefficients.size} points")

ScanParameters

Configuration dataclass for defining parameter scan ranges.

carriercapture.analysis.parameter_scan.ScanParameters dataclass

Container for parameter scan configuration.

Attributes:

Name Type Description
dQ_range tuple

(min, max, n_points) for ΔQ grid (amu^0.5·Å)
dE_range tuple

(min, max, n_points) for ΔE grid (eV)
hbar_omega_i float or tuple

ℏω for initial state (eV). If tuple: (min, max, n_points)
hbar_omega_f float or tuple

ℏω for final state (eV). If tuple: (min, max, n_points)
temperature float or NDArray

Temperature(s) for calculation (K)
volume float

Supercell volume (cm³)
degeneracy int

Degeneracy factor
sigma float

Gaussian delta width (eV)
cutoff float

Energy cutoff for overlaps (eV)

ScanResult

Container for scan results with save/load functionality.

carriercapture.analysis.parameter_scan.ScanResult dataclass

Container for parameter scan results.

Attributes:

Name Type Description
dQ_grid NDArray

ΔQ values tested
dE_grid NDArray

ΔE values tested
capture_coefficients NDArray

Capture coefficient array, shape (n_dQ, n_dE) or (n_dQ, n_dE, n_temp)
barrier_heights NDArray

Classical barrier heights, shape (n_dQ, n_dE)
parameters ScanParameters

Parameters used for scan
metadata dict

Additional metadata

save(filepath, format='npz')

Save scan results to file.

Parameters:

Name Type Description Default
filepath str or Path

Output file path

 required
format str

File format: "npz" or "hdf5"

 "npz"

load(filepath, format='npz') classmethod

Load scan results from file.

Parameters:

Name Type Description Default
filepath str or Path

Input file path

 required
format str

File format: "npz" or "hdf5"

 "npz"

Returns:

Type Description
ScanResult

Loaded scan results

Usage Example

from carriercapture.analysis import ParameterScanner, ScanParameters
import numpy as np

# Define scan parameters
params = ScanParameters(
    dQ_range=(0, 25, 25),    # ΔQ: 0-25 amu^0.5·Å, 25 points
    dE_range=(0, 2.5, 10),   # ΔE: 0-2.5 eV, 10 points
    hbar_omega_i=0.008,      # Initial phonon energy
    hbar_omega_f=0.008,      # Final phonon energy
    temperature=300.0,       # Temperature (K)
    volume=1e-21,            # Supercell volume (cm³)
    degeneracy=1,
    nev_initial=180,
    nev_final=60,
)

# Create scanner
scanner = ParameterScanner(params, verbose=True)

# Run scan (use all CPU cores)
results = scanner.run_harmonic_scan(n_jobs=-1, show_progress=True)

# Save results
results.save('scan_results.npz', format='npz')

# Analyze results
print(f"Scanned {results.capture_coefficients.size} parameter combinations")
print(f"Max capture: {np.nanmax(results.capture_coefficients):.3e} cm³/s")
print(f"Min capture: {np.nanmin(results.capture_coefficients):.3e} cm³/s")

See Also