Conductivity Backends

Overview

The design of FastIterativeMethod.jl deliberately separates the FIM algorithm from conductivity evaluation. This allows the package to work with different mesh representations and conductivity models without code duplication.

Default: Constant Conductivity

The simplest case is constant conductivity:

using FastIterativeMethod, StaticArrays, Tensors

# Create a conductivity evaluator with constant value
cc = ConductivityEvaluatorCache(
    nothing,                              # No cell cache
    MVector(FastIterativeMethod.create_custom_quadrature_points(SVector(1, 2, 3, 4))),     # Quadrature points (allocated on use)
    1.0                                   # Conductivity value
)

When cell_cache = Nothing, the evaluate function simply returns the stored conductivity value.

Extending with Custom Backends

To create a backend-specific implementation (e.g., for Ferrite or a custom mesh format):

Step 1: Create a Custom Cell Cache

struct MyBackendCellCache
    cell_data::SomeData
    # Additional fields as needed
end

Step 2: Extend the Conductivity Cache

# Create a specialized subtype
my_cache = ConductivityEvaluatorCache(
    MyBackendCellCache(...),
    SVector{7,Vec{3,Float64}}(undef),
    MyBackendConductivityModel(...)
)

Step 3: Dispatch Functions

Implement three key functions for your backend:

# Evaluate conductivity at a quadrature point
function FastIterativeMethod.evaluate(
    cache::ConductivityEvaluatorCache{MyBackendCellCache},
    qp_index::Int
)
    # Return conductivity value for quadrature point qp_index
    # Use cache.conductivity and cache.quadrature_points as needed
    return your_conductivity_value
end

# Reinitialize cache for a new cell
function FastIterativeMethod.reinit!(
    cache::ConductivityEvaluatorCache{MyBackendCellCache},
    cell_id::Int
)
    # Update cache.cell_cache with cell-specific data
    # For example, if the conductivity varies spatially.
    return cache
end

# Update conductivity value
function FastIterativeMethod.change_conductivity!(
    cache::ConductivityEvaluatorCache{MyBackendCellCache},
    val
)
    cache.conductivity = val
end

Example: Ferrite Integration

The package includes a Ferrite extension (ext/FastIterativeMethodFerriteExt.jl) that works with Ferrite's grids and cell caches.

Performance Considerations

Quadrature points — The package pre-allocates 7 quadrature points per cell.
Cell reinitialization — Keep reinit! fast; it's called once per cell per solve iteration.
Conductivity evaluation — The evaluate function is called many times per cell iteration.

Testing Your Backend

To verify your backend works correctly:

Create a simple test mesh (e.g., a single tetrahedron).
Initialize boundary conditions (set Φ for known vertices).
Call reset!(fim_cache) to initialize the active list.
Call solve!(fim_cache) and verify field values are updated correctly.
Compare results with a reference solution.
Please add tests.