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, omega=1e-06, device='cuda')

AC electrode tortuosity solver (migration + capacitive current).

Solves a complex-valued potential field under sinusoidal excitation with a closed (zero-flux) right boundary, using an SOR-like update and frequency-dependent prefactors. Reports the electrode tortuosity from boundary current.

Parameters:

• img (numpy.ndarray) – 2D or 3D binary image; internally batched.

• omega (float, optional) – Angular frequency of excitation. Defaults to 1e-6.

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

omega

Angular excitation frequency.

Type:

float

res

Series resistance coefficient.

Type:

float

c_DL

Double-layer capacitance coefficient.

Type:

float

A_CC

Current-collector interfacial area.

Type:

int

k_0

Scaling constant for normalization.

Type:

float

VF

Volume fraction of the conductive phase.

Type:

float

img

Working image on device.

Type:

torch.Tensor

phi

Complex potential field (padded).

Type:

torch.Tensor

phase_map

Padded binary phase mask.

Type:

torch.Tensor

prefactor

Complex update prefactors.

Type:

torch.Tensor

w

Over-relaxation factor.

Type:

float

cb

Checkerboard masks.

Type:

list[torch.Tensor]

converged

Global convergence flag.

Type:

bool

semiconverged

Stage convergence tracker.

Type:

float | bool

iter

Iteration counter.

Type:

int

tau_e

Electrode tortuosity estimate.

Type:

float | torch.Tensor

D_eff

Placeholder; not central to AC solve.

Type:

float | None

D_mean

Placeholder; not central to AC solve.

Type:

float | None

Notes

This class is standalone (does not inherit from BaseSolver) due to its complex-valued field and AC-specific update scheme.

__init__(img, omega=1e-06, device='cuda')

check_convergence()

crop(img, c=1)

init_cb(img)

init_phi(img)

Initialise phi field as zeros

Parameters:

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

Returns:

phi

Return type:

torch.array

init_prefactor(img)

Initialise prefactors -> (nn_cond+2j*omega*res*c(dims-nn_cond))**-1

Parameters:

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

Returns:

prefactor

Return type:

cp.array

pad(img, vals=[0, 0, 0, 0, 0, 0])

solve(iter_limit=100000, verbose=True, conv_crit=1e-05, conv_crit_2=0.001)

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 omega solves :return: tau

sum_neighbours()

tau_e_from_phi()

class taufactor.MultiPhaseSolver(img, cond={1: 1}, device='cuda')

Multi-phase SOR solver with per-phase conductivities.

Supports multiple conductive labels with different conductivities and uses harmonic-mean pair weights in the update stencil. Currently implemented for batch size of 1.

Parameters:

• img (numpy.ndarray) – Labeled image; 0 = non-conductive.

• cond (dict[int, float], optional) – Map label -> conductivity. Defaults to {1: 1}.

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

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

cond

Internal map of label to resistance half-weights.

Type:

dict[int, float]

pre_factors

Directional pre-factors for the stencil.

Type:

list[torch.Tensor]

VF

Volume fraction per label.

Type:

dict[int, float]

D_mean

Phase-weighted mean diffusivity.

Type:

float

D_eff

Effective diffusivity.

Type:

torch.Tensor | float | None

tau

Tortuosity.

Type:

torch.Tensor | float | None

Raises:

• ValueError – If conductivity for any label is 0, or if label 0 is included as conductive.

• TypeError – If batch size is greater than 1.

__init__(img, cond={1: 1}, device='cuda')

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

plot_stats(relative_error)

Default: No plotting output.

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.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) SOR 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')

compute_metrics()

Defines tau and relative error

init_conductive_neighbours(mask)

Saves the number of conductive neighbours for flux calculation

init_field(mask)

Sets an initial linear field across the volume

plot_stats(relative_error)

Default: No plotting output.

return_mask(img)

Return conductive mask.

vertical_flux() → torch.Tensor

Calculates the vertical flux through the volume

Modules

metrics
taufactor	Main module.
utils