taufactor.taufactor

Main module.

Classes

AnisotropicSolver(img, spacing[, omega, ...])	Anisotropic SOR solver with voxel-spacing corrections.
MultiPhaseSolver(img[, diffusivities, ...])	Multi-phase SOR solver with per-phase conductivity/diffusivity.
PeriodicMultiPhaseSolver(img[, ...])	Multi-phase solver with periodic boundary conditions in y and z.
PeriodicSolver(img[, omega, D_0, device])	Two-phase SOR solver with periodic Y/Z boundaries.
SORSolver(img[, omega, precision, device])	A minimal, clean template for SOR solvers.
Solver(img[, omega, D_0, device])	Two-phase (binary) through-transport solver.
ThroughTransportSolver(img[, omega, ...])	Solver for through-transport with open boundaries in x direction.

class taufactor.taufactor.AnisotropicSolver(img, spacing, omega=None, D_0=1, device=torch.device)

Anisotropic SOR solver with voxel-spacing corrections.

Scales neighbour contributions to account for non-cubic voxels such as in FIB-SEM stacks (different spacing in cutting direction). Y-neighbors are scaled by (dx/dy)^2 and Z-neighbors by (dx/dz)^2.

Parameters:

• img (numpy.ndarray) – Binary input image.

• spacing (tuple[float, float, float]) – Voxel spacing (dx, dy, dz).

• bc (tuple[float, float], optional) – Boundary values. Defaults to (-0.5, 0.5).

• D_0 (float, optional) – Reference diffusivity. Defaults to 1.

• device (str | torch.device, optional) – Compute device. Defaults to 'cuda'.

Ky

Anisotropy weight for Y neighbors ((dx/dy)^2).

Type:

float

Kz

Anisotropy weight for Z neighbors ((dx/dz)^2).

Type:

float

Raises:

• ValueError – If spacing is not a length-3 numeric tuple.

• UserWarning – If spacing anisotropy is very large.

__init__(img, spacing, omega=None, D_0=1, device=torch.device)

init_conductive_neighbours(img)

Saves the number of conductive neighbours for flux calculation

sum_weighted_neighbours()

Default: isotropic 6-neighbor SOR increment on interior.

class taufactor.taufactor.MultiPhaseSolver(img, diffusivities=None, D_scaling=1, omega=None, device='cuda')

Multi-phase SOR solver with per-phase conductivity/diffusivity.

Supports multiple labels with user-defined diffusivities and uses harmonic-mean pair weights in the update stencil. Labels omitted from diffusivities are treated as isolating with a warning.

Parameters:

• img (numpy.ndarray) – Labeled image.

• diffusivities (dict[int, float], optional) – Map label -> diffusivity. Diffusivity can be zero for any label (including label 0). Labels not provided are assumed isolating. Defaults to {1: 1}.

• device (str | torch.device, optional) – Compute device. Defaults to 'cuda'.

diffusivities

Internal map of label to diffusivity.

Type:

dict[int, float]

pre_factors

Directional pre-factors for the stencil.

Type:

list[torch.Tensor]

VF

Volume fraction per label and batch.

Type:

dict[int, numpy.ndarray]

D_mean

Phase-weighted mean diffusivity per batch.

Type:

numpy.ndarray

D_eff

Effective diffusivity.

Type:

torch.Tensor | float | None

tau

Tortuosity.

Type:

torch.Tensor | float | None

Raises:

ValueError – If any diffusivity is negative or non-finite.

__init__(img, diffusivities=None, D_scaling=1, omega=None, device='cuda')

init_conductive_neighbours(img)

N_i: amount of conductive neighbours (cond_nn)

return_mask(img)

Return conductive mask.

sum_weighted_neighbours() → torch.Tensor

Default: isotropic 6-neighbor SOR increment on interior.

vertical_flux()

Calculates the vertical flux through the volume

class taufactor.taufactor.PeriodicMultiPhaseSolver(img, diffusivities=None, D_scaling=1, omega=None, device='cuda')

Multi-phase solver with periodic boundary conditions in y and z.

apply_boundary_conditions()

Default: Dirichlet in x and no-flux in y and z direction.

init_conductive_neighbours(img)

N_i: amount of conductive neighbours (cond_nn)

class taufactor.taufactor.PeriodicSolver(img, omega=None, D_0=1, device='cuda')

Two-phase SOR solver with periodic Y/Z boundaries.

Uses periodic wrapping for neighbor evaluation in Y and Z and reapplies periodic boundary conditions to the field each iteration. X remains the flux/open direction.

Notes

Overrides init_nn and apply_boundary_conditions from Solver.

apply_boundary_conditions()

Default: Dirichlet in x and no-flux in y and z direction.

init_conductive_neighbours(img)

Saves the number of conductive neighbours for flux calculation

class taufactor.taufactor.SORSolver(img: numpy.ndarray, omega: float | None = None, precision=None, device='cuda')

A minimal, clean template for SOR solvers. Subclasses override a few well-defined hooks. :param img: labelled input image defining (non-)conducting phases. :param oemga: Over-relaxation factor for SOR scheme. :param device: The device to perform computations (‘cpu’ or ‘cuda’).

__init__(img: numpy.ndarray, omega: float | None = None, precision=None, device='cuda')

apply_boundary_conditions()

Default: Dirichlet in x and no-flux in y and z direction.

check_convergence(verbose, conv_crit, plot_interval)

abstractmethod compute_metrics()

Defines tau and relative error

abstractmethod init_conductive_neighbours(img: torch.Tensor) → torch.Tensor

N_i: amount of conductive neighbours (cond_nn)

abstractmethod init_field(img: torch.Tensor) → torch.Tensor

Return initial padded field [bs,Nx+2,Ny+2,Nz+2].

init_reactive_neighbours(img: torch.Tensor) → torch.Tensor

S_i: amount of reactive neighbours (reac_nn)

plot_stats(relative_error)

Default: No plotting output.

abstractmethod return_mask(img: torch.Tensor) → torch.Tensor

Return conductive mask.

solve(iter_limit=10000, verbose=True, conv_crit=0.01, plot_interval=10)

Solve steady-state with SOR solver

Parameters:

• iter_limit – max iterations before aborting

• verbose – Set to ‘True’, ‘per_iter’ or ‘plot’ for more feedback

• conv_crit – convergence criteria, minimum percent difference between

max and min flux through a given layer :return: tau

sum_weighted_neighbours() → torch.Tensor

Default: isotropic 6-neighbor SOR increment on interior.

class taufactor.taufactor.Solver(img, omega=None, D_0=1, device='cuda')

Two-phase (binary) through-transport solver.

Solves steady-state potential/diffusion on a binary microstructure (1 = conductive, 0 = non-conductive) using a Jacobi-like SOR sweep with alternating checkerboards. Reports batchwise tortuosity and effective diffusivity.

Parameters:

• img (numpy.ndarray) – Binary image with labels in {0, 1}.

• bc (tuple[float, float], optional) – Boundary values (top_bc, bot_bc). Defaults to (-0.5, 0.5).

• D_0 (float, optional) – Reference (mean) diffusivity. Defaults to 1.

• device (str | torch.device, optional) – Compute device. Defaults to 'cuda'.

D_0

Reference diffusivity.

Type:

float

D_mean

Mean diffusivity used for scaling.

Type:

float | None

VF

Volume fraction per batch element.

Type:

numpy.ndarray

D_rel

Relative diffusivity per batch (set during solve).

Type:

numpy.ndarray

Raises:

ValueError – If labels are not strictly in {0, 1}.

__init__(img, omega=None, D_0=1, device='cuda')

init_conductive_neighbours(mask)

Saves the number of conductive neighbours for flux calculation

return_mask(img)

Return conductive mask.

vertical_flux() → torch.Tensor

Calculates the vertical flux through the volume

class taufactor.taufactor.ThroughTransportSolver(img, omega=None, precision=None, device='cuda')

Solver for through-transport with open boundaries in x direction.

Uses Dirichlet boundary conditions in x to calculate tortuosity from staedy-state fluxes.

__init__(img, omega=None, precision=None, device='cuda')

compute_metrics()

Defines tau and relative error

init_field(mask)

Sets an initial linear field across the volume

plot_stats(relative_error)

Plot relative fluxes across x direction to visualize convergence.