greenWTE.green

Green-operator utilities for WTE in the relaxation-time approximation (RTA).

Classes

DiskGreenOperator(container, omg_ft, k_ft, ...)

Disk-backed Green operator loaded from a GreenContainer.

GreenOperatorBase()

Abstract base class for Green operators \(\mathcal{G} = \mathcal{L}^{-1}\).

GreenWTESolver(omg_ft_array, k_ft, material, ...)

Wigner Transport Equation solver using precomputed Green's operators.

RTAGreenOperator(wigner_operator)

Green operator in RTA computed by inverting a RTAWignerOperator.

RTAWignerOperator(omg_ft, k_ft, material)

Wigner operator in the relaxation-time approximation (RTA).

class greenWTE.green.DiskGreenOperator(container: GreenContainer, omg_ft: float, k_ft: float, material: Material, atol: float = 0.0)

Bases: GreenOperatorBase

Disk-backed Green operator loaded from a GreenContainer.

Loads a single slab (nq, m, m) for the requested \(\omega\) and \(k\) into GPU memory on demand, allowing the solver to operate without recomputing or storing all Green operators simultaneously.

Parameters:
  • container (GreenContainer) – Container object that manages the disk storage of Green’s operators.

  • omg_ft (float) – Temporal Fourier variable in rad/s.

  • k_ft (float) – Spatial Fourier variable in rad/m.

  • material (Material) – Material object containing the necessary material properties.

  • atol (float, optional) – Absolute tolerance for matching stored \(\omega\) and \(k\) values.

material

Material associated with the Green’s operator.

Type:

Material

nq

Number of q-points.

Type:

int

nat3

Number of phonon modes (3 times the number of atoms in the unit cell).

Type:

int

dtyper

Data type for the real-valued arrays.

Type:

cupy.dtype

dtypec

Data type for the complex-valued arrays.

Type:

cupy.dtype

__getitem__(iq: int) ndarray

Allow indexing to access the Green’s function for a specific q-point.

__init__(container: GreenContainer, omg_ft: float, k_ft: float, material: Material, atol: float = 0.0) None

Initialize the disk-based Green’s operator. No I/O is performed here.

__iter__() Self

Allow iteration over the Green’s function q-points.

_abc_impl = <_abc._abc_data object>
_require_ready() None

Ensure the Green’s operator is computed before accessing it.

compute(recompute: bool = False) None

Load the Green’s operator from disk.

Parameters:

recompute (bool, optional) – If False and the data is already present, do nothing. If True, reload from disk.

property dtype: dtype

Return the dtype of the Green’s function.

free() None

Free the memory used by the Green’s operator.

property shape: tuple[int, int, int]

Return the shape of the Green’s function.

squeeze() ndarray

Return the Green’s function with singleton dimensions removed.

class greenWTE.green.GreenOperatorBase

Bases: ABC

Abstract base class for Green operators \(\mathcal{G} = \mathcal{L}^{-1}\).

Provides a common interface for Green’s operators, whether computed or loaded from disk.

See also

RTAGreenOperator

Green’s operator computed from the RTA Wigner operator.

DiskGreenOperator

Disk-based Green’s operator that loads.

__getitem__(iq: int) ndarray

Allow indexing to access the Green’s function for a specific q-point.

__iter__() Self

Allow iteration over the Green’s function q-points.

_abc_impl = <_abc._abc_data object>
_require_ready() None

Ensure the Green’s operator is computed before accessing it.

abstractmethod compute(recompute: bool = False, **kwargs) None

Compute or load the Green’s function from disk.

property dtype: dtype

Return the dtype of the Green’s function.

free() None

Free the memory used by the Green’s operator.

property shape: tuple[int, int, int]

Return the shape of the Green’s function.

squeeze() ndarray

Return the Green’s function with singleton dimensions removed.

class greenWTE.green.GreenWTESolver(omg_ft_array: ndarray, k_ft: ndarray, material: Material, greens: list[RTAGreenOperator], source: ndarray, source_type: str = 'energy', dT_init: complex = 1 + 1j, max_iter: int = 100, conv_thr_rel: float = 1e-12, conv_thr_abs: float = 0, outer_solver: str = 'root', command_line_args: Namespace = Namespace(), print_progress: bool = False)

Bases: SolverBase

Wigner Transport Equation solver using precomputed Green’s operators.

This solver implements the mapping from a temperature change dT to the Wigner distribution function n via direct matrix multiplication with precomputed Green’s function operators. The approach bypasses the need for iterative inner solvers such as GMRES and can be significantly faster when the Green’s functions are available.

Parameters:
  • omg_ft_array (cupy.ndarray) – 1D array of temporal Fourier variables in rad/s for which the WTE will be solved.

  • k_ft (float) – Magnitude of the spatial Fourier variable in rad/m.

  • material (Material) – Material object containing the necessary material properties.

  • greens (list of RTAGreenOperator) – List of precomputed Green’s function operators, one for each omg_ft value in omg_ft_array. Each operator must implement matrix multiplication to map the source term to the Wigner distribution function.

  • source (cupy.ndarray) – Source term of the WTE, with shape (nq, nat3, nat3).

  • source_type (str) – The type of the source term, either “energy” or “gradient”. When injecting energy through the source term, there is no additional factor of dT for the offdiagonals of the source. For the temperature gradient type source terms, the offdiagonal elements are scaled by dT.

  • dT_init (complex, optional) – Initial guess for \(\Delta T\) used by the outer solver.

  • max_iter (int, optional) – Maximum number of iterations for the outer solver.

  • conv_thr_rel (float, optional) – The relative convergence threshold for the solver.

  • conv_thr_abs (float, optional) – The absolute convergence threshold for the solver.

  • outer_solver ({'plain', 'aitken', 'root', 'none'}, optional) – Outer-solver strategy. 'root' uses scipy.optimize.root(), 'plain' is fixed-point, 'aitken' applies AitkenAccelerator, and 'none' performs a single mapping.

  • command_line_args (argparse.Namespace, optional) – Optional namespace of parsed command-line arguments to be added to the results file.

  • print_progress (bool, optional) – If True, prints progress while solving.

Raises:

ValueError – If the number of supplied Green’s operators does not match the length of omg_ft_array.

Notes

  • This implementation calls dT_to_N_matmul() to apply the Green’s operator for the given frequency index. No residuals are generated, and the second return value of _dT_to_N() is always a list of empty lists (one per nq).

  • Since there is no iterative inner solver, performance is largely determined by the cost of the Green’s operator matrix multiplication.

See also

SolverBase

Parent class that provides the outer-solver infrastructure.

IterativeWTESolver

WTE solver using iterative methods.

__init__(omg_ft_array: ndarray, k_ft: ndarray, material: Material, greens: list[RTAGreenOperator], source: ndarray, source_type: str = 'energy', dT_init: complex = 1 + 1j, max_iter: int = 100, conv_thr_rel: float = 1e-12, conv_thr_abs: float = 0, outer_solver: str = 'root', command_line_args: Namespace = Namespace(), print_progress: bool = False) None

Initialize GreenWTESolver.

_abc_impl = <_abc._abc_data object>
_dT_converged(dT: complex, dT_new: complex) bool

Check whether two successive \(\Delta T\) iterates meet the thresholds.

Parameters:
  • dT (complex) – The previous and current temperature changes dT.

  • dT_new (complex) – The previous and current temperature changes dT.

Returns:

True absolute and relative convergence criteria are met.

Return type:

bool

_dT_to_N(dT: complex, omg_ft: float, omg_idx: int, sol_guess: ndarray | None = None) tuple[ndarray, list]

Map a temperature change to a Wigner distribution n.

Subclasses must implement this method.

_flux = None
_kappa = None
_kappa_c = None
_kappa_p = None
_run_solver_aitken(omg_idx: int, omg_ft: float) tuple[float, complex, complex, ndarray, int, list[float], list[complex], list[float], list[float]]

Run the WTE solver using Aitken’s delta-squared process for acceleration.

Parameters:
  • omg_idx (int) – The index of the temporal Fourier variable for which the WTE will be solved.

  • omg_ft (float) – The temporal Fourier variable in rad/s for which the WTE will be solved.

Returns:

  • omg_ft (float) – The input temporal Fourier variable in rad/s.

  • dT (complex) – The calculated temperature change dT in K for the given omg_ft.

  • dT_init (complex) – The initial temperature change dT in K estimated for the given omg_ft.

  • n (cupy.ndarray) – The wigner distribution function n for the given omg_ft, shape (nq, nat3, nat3).

  • niter (int) – The number of iterations taken for the outer solver to converge for the given omg_ft.

  • iter_times (list) – A list of iteration times for the outer solver for the given omg_ft.

  • dT_iterates (list) – A list of iteration values for the temperature changes dT for the given omg_ft.

  • n_norms (list) – A list of norms for the wigner distribution function n for the given omg_ft.

  • gmres_residual (list) – A list of GMRES residuals for the given omg_ft. Empty if the inner solver is not GMRES.

_run_solver_none(omg_idx: int, omg_ft: float) tuple[float, complex, complex, ndarray, int, list[float], list[complex], list[float], list[float]]

Run the WTE solver without outer iterations, performing a single mapping from dT to n.

Parameters:
  • omg_idx (int) – The index of the temporal Fourier variable for which the WTE will be solved.

  • omg_ft (float) – The temporal Fourier variable in rad/s for which the WTE will be solved.

Returns:

  • omg_ft (float) – The input temporal Fourier variable in rad/s.

  • dT (complex) – The calculated temperature change dT in K for the given omg_ft.

  • dT_init (complex) – The initial temperature change dT in K estimated for the given omg_ft.

  • n (cupy.ndarray) – The wigner distribution function n for the given omg_ft, shape (nq, nat3, nat3).

  • niter (int) – The number of iterations taken for the outer solver to converge for the given omg_ft.

  • iter_times (list) – A list of iteration times for the outer solver for the given omg_ft.

  • dT_iterates (list) – A list of iteration values for the temperature changes dT for the given omg_ft.

  • n_norms (list) – A list of norms for the wigner distribution function n for the given omg_ft.

  • gmres_residual (list) – A list of GMRES residuals for the given omg_ft. Empty if the inner solver is not GMRES.

Notes

The lengthy return signature is to maintain compatibility with the other outer solvers.

_run_solver_plain(omg_idx: int, omg_ft: float) tuple[float, complex, complex, ndarray, int, list[float], list[complex], list[float], list[float]]

Run the WTE solver using simple fixed-point iteration.

Parameters:
  • omg_idx (int) – The index of the temporal Fourier variable for which the WTE will be solved.

  • omg_ft (float) – The temporal Fourier variable in rad/s for which the WTE will be solved.

Returns:

  • omg_ft (float) – The input temporal Fourier variable in rad/s.

  • dT (complex) – The calculated temperature change dT in K for the given omg_ft.

  • dT_init (complex) – The initial temperature change dT in K estimated for the given omg_ft.

  • n (cupy.ndarray) – The wigner distribution function n for the given omg_ft, shape (nq, nat3, nat3).

  • niter (int) – The number of iterations taken for the outer solver to converge for the given omg_ft.

  • iter_times (list) – A list of iteration times for the outer solver for the given omg_ft.

  • dT_iterates (list) – A list of iteration values for the temperature changes dT for the given omg_ft.

  • n_norms (list) – A list of norms for the wigner distribution function n for the given omg_ft.

  • gmres_residual (list) – A list of GMRES residuals for the given omg_ft. Empty if the inner solver is not GMRES.

_run_solver_root(omg_idx: int, omg_ft: float) tuple[float, complex, complex, ndarray, int, list[float], list[complex], list[float], list[float]]

Run the WTE solver using SciPy’s root-finding algorithm :py:mod:scipy.optimize.root`.

Parameters:
  • omg_idx (int) – The index of the temporal Fourier variable for which the WTE will be solved.

  • omg_ft (float) – The temporal Fourier variable in rad/s for which the WTE will be solved.

Returns:

  • omg_ft (float) – The input temporal Fourier variable in rad/s.

  • dT (complex) – The calculated temperature change dT in K for the given omg_ft.

  • dT_init (complex) – The initial temperature change dT in K estimated for the given omg_ft.

  • n (cupy.ndarray) – The wigner distribution function n for the given omg_ft, shape (nq, nat3, nat3).

  • niter (int) – The number of iterations taken for the outer solver to converge for the given omg_ft.

  • iter_times (list) – A list of iteration times for the outer solver for the given omg_ft.

  • dT_iterates (list) – A list of iteration values for the temperature changes dT for the given omg_ft.

  • n_norms (list) – A list of norms for the wigner distribution function n for the given omg_ft.

  • gmres_residual (list) – A list of GMRES residuals for the given omg_ft. Empty if the inner solver is not GMRES.

_solution_lists_to_arrays() None

Convert the lists of iteration times, dT iterates, n norms, and GMRES residuals into cupy arrays.

We can only do that after all omg_ft have been solved, since the lengths of the lists can vary. All entries in the lists are padded with NaNs.

property flux: ndarray

Energy flux tensor J computed from n and the velocity operator.

Returns:

The thermal flux in W/m^2 for each omg_ft, shape (n_omg_ft, nq, nat3, nat3).

Return type:

cupy.ndarray

inner_solver = 'None'
property kappa: ndarray

Total thermal conductivity \(\kappa(\omega)\).

Compute kappa from the Wigner distribution function n and the temperature change dT.

Returns:

The thermal conductivity in W/m/K for each omg_ft, shape (n_omg_ft,).

Return type:

cupy.ndarray

property kappa_c: ndarray

Coherence thermal conductivity \(\kappa_\mathrm{C}(\omega)\).

Compute kappa_C from the Wigner distribution function n and the temperature change dT.

Returns:

The coherence thermal conductivity in W/m/K for each omg_ft, shape (n_omg_ft,).

Return type:

cupy.ndarray

property kappa_p: ndarray

Ppopulation thermal conductivity \(\kappa_\mathrm{P}(\omega)\).

Compute kappa_P from the Wigner distribution function n and the temperature change dT.

Returns:

The population thermal conductivity in W/m/K for each omg_ft, shape (n_omg_ft,).

Return type:

cupy.ndarray

run(free: bool = True) None

Run the WTE solver at each \(\omega \in\) omg_ft_array.

The outer iteration chosen by outer_solver is used to find self-consistent solutions for the temperature changes \(\Delta T(\omega)\) and the Wigner distribution. After running, the results are stored in the class attributes dT, dT_init, n, niter, n_norms, iter_time, dT_iterates, and gmres_residual.

class greenWTE.green.RTAGreenOperator(wigner_operator: RTAWignerOperator)

Bases: GreenOperatorBase

Green operator in RTA computed by inverting a RTAWignerOperator.

Parameters:

wigner_operator (RTAWignerOperator) – Wigner operator to be inverted to obtain the Green’s operator.

omg_ft

Temporal Fourier variable in rad/s.

Type:

float

k_ft

Magnitude of the spatial Fourier variable in rad/m.

Type:

float

material

Material associated with the Green’s operator.

Type:

Material

nq

Number of q-points.

Type:

int

nat3

Number of phonon modes (3 times the number of atoms in the unit cell).

Type:

int

dtyper

Data type for the real-valued arrays.

Type:

cupy.dtype

dtypec

Data type for the complex-valued arrays.

Type:

cupy.dtype

__getitem__(iq: int) ndarray

Allow indexing to access the Green’s function for a specific q-point.

__init__(wigner_operator: RTAWignerOperator) None

Initialize the Green’s operator with the Wigner operator.

__iter__() Self

Allow iteration over the Green’s function q-points.

_abc_impl = <_abc._abc_data object>
_require_ready() None

Ensure the Green’s operator is computed before accessing it.

compute(recompute: bool = False, clear_wigner: bool = True) None

Invert the Wigner operator to obtain the Green operator on the GPU.

Parameters:
  • recompute (bool, optional) – If False and the operator is already available, do nothing. If True, rebuild all blocks.

  • clear_wigner (bool, optional) – If True, free the memory used by the Wigner operator after computing the Green’s function.

property dtype: dtype

Return the dtype of the Green’s function.

free() None

Free the memory used by the Green’s operator.

property shape: tuple[int, int, int]

Return the shape of the Green’s function.

squeeze() ndarray

Return the Green’s function with singleton dimensions removed.

class greenWTE.green.RTAWignerOperator(omg_ft: ndarray, k_ft: ndarray, material: Material)

Bases: object

Wigner operator in the relaxation-time approximation (RTA).

Builds the block-diagonal Wigner operator \(\mathcal{L}(q; \omega, k)\) for a single temporal frequency \(\omega\) and spatial wavevector magnitude \(k\).

Parameters:
  • omg_ft (float) – Temporal Fourier variable in rad/s.

  • k_ft (float) – Magnitude of the spatial Fourier variable in rad/m.

  • material (Material) – Material object containing the necessary material properties.

dtyper

The data type for the real-valued arrays.

Type:

cupy.dtype

dtypec

The data type for the complex-valued arrays.

Type:

cupy.dtype

nq

The number of q-points.

Type:

int

nat3

The number of phonon modes (3 times the number of atoms in the unit cell).

Type:

int

__getitem__(iq: int) ndarray

Return a single-q-point operator block.

Parameters:

iq (int) – The index of the q-point to retrieve.

Returns:

The Wigner operator block for the specified q-point, with shape (nat3^2, nat3^2).

Return type:

cupy.ndarray

__init__(omg_ft: ndarray, k_ft: ndarray, material: Material) None

Initialize the factory with the given physical parameters.

__iter__() Self

Allow iteration over the Wigner operators q-points.

compute(recompute: bool = False) None

Assemble the Wigner operator blocks on the GPU.

Parameters:

recompute (bool, optional) – If False and the operator is already available, do nothing. If True, rebuild all blocks.