FIKH (Fractional Isotropic-Kinematic Hardening) Comprehensive Validation Report

Date: 2026-03-29 Mode: Enterprise (–deep –security –performance) Scope: rheojax/models/fikh/, docs/source/models/fikh/, examples/fikh/, tests/models/fikh/

Summary

  • Assessment: ⚠️ Needs Minor Work (2 documentation issues)

  • Confidence: High

  • Mode: Enterprise with –deep –security –performance

1. Automated Checks

Dimension

Tool

Result

Unit Tests

pytest

90/90 PASSED

Linting

ruff

All checks passed

Type Checking

mypy

No FIKH-specific errors

Security (S rules)

ruff –select S

All checks passed

Assert statements

grep

None found (clean)

2. Physics Verification Against Literature

2.1 Caputo Fractional Structure Evolution — CORRECT

Implementation: D^α_C λ = (1-λ)/τ_thix - Γ·λ·|γ̇^p|

Literature: The RHS is the classical Moore/Coussot build-up/breakdown form, confirmed in Dimitriou & McKinley (2014) Soft Matter 10:6619. The promotion to Caputo derivative on the LHS is a synthesis extending Jaishankar & McKinley (2013, 2014) fractional viscoelasticity to thixotropic structure. No single paper proposes this exact combination — it is a well-motivated novel synthesis. ✓

2.2 L1 Scheme for Caputo Derivative — CORRECT

Implementation: b_k = (k+1)^(1-α) - k^(1-α), normalization 1/(Γ(2-α)·dt^α)

Literature: Standard L1 scheme from Lin & Xu (2007), textbook treatment in Li & Zeng (2015). Convergence order O(Δt^{2-α}), which for α ∈ (0,1) lies between O(Δt) and O(Δt²). Implementation matches exactly. ✓

2.3 Armstrong-Frederick Backstress — CORRECT

Implementation: dA/dt = C·γ̇^p·sign(ξ) - γ_dyn·|A|^(m-1)·A·|γ̇^p|

Literature: Standard AF rule (Armstrong & Frederick 1966, Chaboche 1991). Dimitriou & McKinley (2014) first adapted AF for thixotropic yield stress fluids within IKH. The exponent generalization m ≠ 1 is the Chaboche multi-surface extension. Implementation with |A|^(m-1) regularized as max(|A|, 1e-10)^(m-1) is numerically sound. ✓

2.4 Perzyna Plastic Flow Rule — CORRECT

Implementation: γ̇^p = ⟨|σ-C·A| - σ_y⟩/μ_p · sign(σ-C·A)

Literature: Standard Perzyna (1963) overstress model. Reduces to Bingham when σ_y=const, C=0. Macaulay bracket and sign function correctly implemented with sign-safety regularization (F-001 fix). ✓

2.5 Mittag-Leffler Relaxation — CORRECT

Implementation: Solution of D^α λ = -λ/τ gives λ(t) = E_α(-(t/τ)^α)

Literature: Textbook result (Mainardi 1996, Gorenflo & Mainardi 1997). Asymptotics correct:

  • Short time: E_α(z) ≈ 1 - z/Γ(1+α) (stretched onset)

  • Long time: E_α(z) ≈ (-z)^{-1}/Γ(1-α) (power-law tail)

  • α → 1 limit: E_1(-t/τ) = exp(-t/τ) (exponential recovery) ✓

2.6 Cole-Cole Depression Angle — CORRECT

Implementation: θ = (1-α)π/2 for fractional elements

Literature: Confirmed in Friedrich (1992) Rheol. Acta 31:309 for the fractional spring-pot/Scott Blair element. Applies to fractional Maxwell model; more complex models produce distorted arcs. ✓

2.7 Arrhenius Thermal Coupling — CORRECT

Implementation: η(T) = η_ref · exp(E_a/R · (1/T - 1/T_ref)) with R = 8.314462618 J/(mol·K)

Literature: Standard Arrhenius form. Exponent clipped to [-50, 50] for overflow protection. ✓

2.8 Taylor-Quinney Coefficient — CORRECT (with caveat)

Implementation: ρc_p·dT/dt = χ·σ·γ̇^p - h·(T-T_env) with χ default 0.9

Literature: Taylor & Quinney (1934) measured χ ≈ 0.9 for metals. For structured fluids (no dislocation storage), χ should be closer to 1.0. Default of 0.9 is conservative and acceptable. ✓

3. Documentation vs. Code Consistency

3.1 Issues Found

ISSUE 1 (Important): Fractional Weissenberg Number Not Dimensionally Consistent

  • Doc claim (fikh.rst:355-362): Wi_α = γ̇ · τ_thix^{1/α} described as a “dimensionless group”

  • Literature: Not found in any published reference. For α ≠ 1, this quantity has dimensions s^{1/α - 1}, which is NOT dimensionless. The standard Weissenberg number Wi = γ̇·τ is dimensionless. A dimensionally consistent fractional form would require: Wi_α = (γ̇·τ_ref)·(τ_thix/τ_ref)^{1/α} where τ_ref absorbs the dimensional mismatch.

  • Impact: Misleading for users trying to compute dimensionless groups. The quantity is a useful heuristic scaling but should not be called a “dimensionless group.”

ISSUE 2 (Minor): alpha_structure Bounds Inconsistency

  • Code (fractional_mixin.py:23): FRACTIONAL_ORDER_BOUNDS = (0.0, 1.0)

  • Docs (fikh.rst:817, fmlikh.rst:624,664): (0.05, 0.99)

  • The docs are more conservative (avoiding degenerate limits α=0, α=1), which is better practical guidance. The code allows the full range. Either align docs to code or tighten code bounds.

3.2 No Issues

  • All 6 protocols documented and implemented consistently

  • Parameter names, defaults, and units match between code and docs

  • Thermal coupling documented and implemented correctly

  • FMLIKH multi-mode architecture matches docs

  • All references are real and correctly cited

  • Mittag-Leffler asymptotics correctly described

4. Examples vs. Code Consistency

4.1 No Significant Issues

All 12 example notebooks (6 FIKH + 6 FMLIKH) demonstrate:

  • Correct protocol usage with appropriate parameters

  • Real data (waxy crude oil from Wei et al. 2018) and synthetic data

  • Physically reasonable parameter ranges

  • Correct claims about power-law relaxation, Bauschinger effect, Cole-Cole depression

4.2 Minor Notes

  • NB01 flow curve fitting pushes τ_thix to upper bounds (1.2 years) — acknowledged in notebook as a limitation of steady-state data for transient parameter identification

  • NB05 SAOS warns about Bayesian inference cost (>10 min) — appropriate caveat

  • FAST_MODE uses only 1 chain — correctly noted as not production-quality

5. Test Coverage Assessment

Area

Tests

Coverage

Initialization & params

9

All configs tested

Predictions (6 protocols)

15

All protocols + edge cases

Limiting behavior

2

α→1 exponential, α small slow recovery

Model function

3

Dict and array interfaces

Caputo derivative

12

L1 coefficients, history buffer, constant/linear functions

Thermal coupling

6

Arrhenius, yield stress, heating/cooling

Integration (fit→predict)

2

Startup and flow curve round-trips

Sign safety (F-001)

2

Bug fix validation

Edge cases covered: α→1 integer limit, α=0.1 slow recovery, zero strain, zero shear, E_a=0, constant function derivative=0, sign-safe regularization.

Missing tests (suggestions):

  • α→0 limit behavior (extremely strong memory)

  • FMLIKH shared vs per-mode α comparison

  • Short-memory truncation error quantification

6. Security Analysis

Check

Result

Secrets in code

None found

assert usage

None (clean)

Code injection

No eval/exec

Dependency vulnerabilities

N/A

7. Performance Notes

  • L1 scheme: O(n_history) per step via JAX scan — efficient fixed-window approximation

  • JIT compilation: All kernels within jax.lax.scan loops

  • Multi-mode (FMLIKH): jax.vmap parallelization over N modes

  • Precompilation: Explicit precompile() method for reducing first-call latency

  • History buffer: Fixed-size (n_history=100 default) prevents memory growth

Recommendations

Must Fix (Documentation)

  1. Fix Fractional Weissenberg Number in fikh.rst:355-362: Either (a) add a note that Wi_α is not dimensionless for α≠1, or (b) replace with a dimensionally consistent definition using a reference timescale, or © rename to “fractional scaling parameter” instead of “dimensionless group”

Should Fix

  1. Align alpha_structure bounds between code and docs: Either update FRACTIONAL_ORDER_BOUNDS to (0.05, 0.99) to match docs, or update docs to (0.0, 1.0) to match code. The docs’ conservative range is better practical guidance.

Nice to Fix

  1. Add tests for α→0 extreme memory regime

  2. Add FMLIKH shared-α vs per-mode-α comparison test

Evidence

  • 90/90 tests passing

  • Ruff lint: clean

  • Mypy: no FIKH-specific errors

  • Security: clean (no asserts, no S101)

  • 8/8 physics claims verified against published literature

  • 12 example notebooks reviewed