taufactor.taufactor

Main module.

Classes

AnisotropicSolver(img, spacing[, bc, D_0, ...])	Anisotropic SOR solver with voxel-spacing corrections.
BaseSolver(img[, bc, device])	Base solver class to handle common functionality for solvers.
ElectrodeSolver(img[, omega, device])	AC electrode tortuosity solver (migration + capacitive current).
MultiPhaseSolver(img[, cond, bc, device])	Multi-phase SOR solver with per-phase conductivities.
PeriodicSolver(img[, bc, D_0, device])	Two-phase SOR solver with periodic Y/Z boundaries.
Solver(img[, bc, D_0, device])	Two-phase (binary) SOR solver.

class taufactor.taufactor.AnisotropicSolver(img, spacing, bc=(-0.5, 0.5), D_0=1, device='cuda')

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, bc=(-0.5, 0.5), D_0=1, device='cuda')

init_nn(img)

Saves the number of conductive neighbours for flux calculation

solve(iter_limit=5000, verbose=True, conv_crit=0.02, 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, minimum percent difference between max and min flux through a given layer :return: tau

class taufactor.taufactor.BaseSolver(img, bc=(-0.5, 0.5), device='cuda')

Base solver class to handle common functionality for solvers.

__init__(img, bc=(-0.5, 0.5), device='cuda')

check_vertical_flux(conv_crit)

Assess vertical flux uniformity as a convergence proxy.

Computes per-slice vertical flux, flags convergence per batch, and returns diagnostics.

Parameters:

conv_crit (float) – Tolerance for relative flux variation across slices.

Returns:

flags (list[str]): One of {"converged","not_converged","zero_flux"} per batch. mean_fl (torch.Tensor): Mean flux per batch [B]. err (torch.Tensor): Relative spread per batch [B]. fl (torch.Tensor): Slice-resolved flux [B, X].

Return type:

tuple

crop(img, c=1)

Crop a uniform margin from all faces.

Parameters:

• img (torch.Tensor) – Batched 3D tensor.

• c (int, optional) – Number of voxels to remove from each face. Defaults to 1.

Returns:

Cropped tensor.

Return type:

torch.Tensor

init_cb(img)

Create a checkerboard over-relaxation mask for SOR.

Parameters:

img (torch.Tensor) – Batched 3D tensor of the working image.

Returns:

Two masks (even/odd slices), each shaped like the spatial volume.

Return type:

list[torch.Tensor]

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

Pad a 3D volume with constant boundary values.

Pads one voxel on each face and sets face values from vals.

Parameters:

• img (torch.Tensor) – Batched 3D tensor [B, X, Y, Z].

• vals (list[float], optional) – Six boundary values in order [x0, x1, y0, y1, z0, z1]. Defaults to six zeros.

Returns:

Padded tensor with shape [B, X+2, Y+2, Z+2].

Return type:

torch.Tensor

solve()

Run solver

class taufactor.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.taufactor.MultiPhaseSolver(img, cond={1: 1}, bc=(-0.5, 0.5), 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}, bc=(-0.5, 0.5), device='cuda')

calc_vertical_flux()

Calculates the vertical flux through the volume

check_convergence(verbose, conv_crit)

init_conc(img)

init_nn(img)

solve(iter_limit=5000, verbose=True, conv_crit=0.02)

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, minimum percent difference between max and min flux through a given layer :return: tau

class taufactor.taufactor.PeriodicSolver(img, bc=(-0.5, 0.5), 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()

init_nn(img)

Saves the number of conductive neighbours for flux calculation

class taufactor.taufactor.Solver(img, bc=(-0.5, 0.5), 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, bc=(-0.5, 0.5), D_0=1, device='cuda')

apply_boundary_conditions()

calc_vertical_flux()

Calculates the vertical flux through the volume

check_convergence(verbose, conv_crit, plot_interval)

init_conc(img)

Sets an initial linear field across the volume

init_nn(img)

Saves the number of conductive neighbours for flux calculation

solve(iter_limit=5000, verbose=True, conv_crit=0.02, 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, minimum percent difference between max and min flux through a given layer :return: tau