taufactor

Top-level package for TauFactor.

class 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.ElectrodeSolver(img, conductive_label=1, reactive_label=0, omega=None, spacing=None, device='cuda')

Default solver for two phase images. Once solve method is called, tau, D_eff and D_rel are available as attributes.

__init__(img, conductive_label=1, reactive_label=0, omega=None, spacing=None, device='cuda')

Initialise parameters, solution field and other tools that can be re-used for multiple solves.

Parameters:

• img – input img with 1s conductive and 0s non-conductive

• bc – Upper and lower boundary conditions. Leave as default.

• D_0 – reference material diffusivity

• device – pytorch device, can be cuda or cpu

compute_metrics()

Defines tau and relative error

init_conductive_neighbours(img)

N_i: amount of conductive neighbours (cond_nn)

init_field(mask)

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

init_reactive_neighbours(img)

S_i: amount of reactive neighbours (reac_nn)

plot_stats(relative_error)

Default: No plotting output.

return_mask(img)

Return conductive mask.

class taufactor.ImpedanceSolver(img, conductive_label=1, reactive_label=0, omega=None, spacing=None, mode='tau_e', device='cuda')

Electrode Solver - solves the electrode tortuosity factor system (migration and capacitive current between current collector and solid/electrolyte interface) Once solve method is called, tau, D_eff and D_rel are available as attributes.

__init__(img, conductive_label=1, reactive_label=0, omega=None, spacing=None, mode='tau_e', device='cuda')

calc_input_impedance()

compute_metrics()

Defines tau and relative error

count_neighbours(img, mask)

Initialise factor based on conductive and capacitive neighbours factor = (N_i + 2*S_i* j*r*w*c / (1 + j*r*frequency*c) N_i: amount of conductive neighbours (cond_nn) S_i: amount of capacitive neighbours (reac_nn)

Parameters:

img (cp.array) – input image, with 1s conductive and 0s non-conductive

Returns:

prefactor

Return type:

cp.array

init_conductive_neighbours(img)

N_i: amount of conductive neighbours (cond_nn)

init_field(img)

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

init_field_internal(mask)

Initialise field with analytical solution :param img: input image, with 1s conductive and 0s non-conductive :type img: torch.array :return: initial field :rtype: torch.array

plot_stats(relative_error)

Default: No plotting output.

return_mask(img)

Return conductive mask.

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

run a solve simulation

Parameters:

iter_limit – max iterations before aborting, will attemtorch double for the same no. iterations

if initialised as singles :param verbose: Whether to print tau. Can be set to ‘per_iter’ for more feedback :param conv_crit: convergence criteria - running standard deviation of tau_e :param conv_crit_2: convergence criteria - maximum difference between tau_e in consecutive frequency solves :return: tau

class 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.PeriodicElectrodeSolver(img, conductive_label=1, reactive_label=0, omega=None, spacing=None, device='cuda')

Solver with periodic boundary conditions in y and z direction.

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)

init_reactive_neighbours(img)

S_i: amount of reactive neighbours (reac_nn)

class taufactor.PeriodicImpedanceSolver(img, conductive_label=1, reactive_label=0, omega=None, spacing=None, mode='tau_e', device='cuda')

Solver with periodic boundary conditions in y and z direction.

apply_boundary_conditions()

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

count_neighbours(img, mask)

Initialise factor based on conductive and capacitive neighbours factor = (N_i + 2*S_i* j*r*w*c / (1 + j*r*frequency*c) N_i: amount of conductive neighbours (cond_nn) S_i: amount of capacitive neighbours (reac_nn)

Parameters:

img (cp.array) – input image, with 1s conductive and 0s non-conductive

Returns:

prefactor

Return type:

cp.array

class 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.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.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

Modules

benchmark	Benchmark helpers for TauFactor convergence studies.
electrode	Main module.
metrics
taufactor	Main module.
utils