API — Core

MeanFieldHom.Core

Shared abstractions and numerical kernels used throughout MeanFieldHom.

Contents

• counters.jl : opt-in work counters for the benchmark harness
• abstractions.jl : inclusion hierarchy (AbstractInclusion …)
• traits.jl : algorithm and material-symmetry traits
• bases.jl : helpers around TensND bases
• tensor_helpers.jl : low-level utilities (_δ, _C_array, Voigt)
• rotational_average.jl : exact SO(3) / azimuthal averages (ISO, TI) of minor-symmetric tensors, incl. Mandel-block forms
• moduli.jl : modulus extractors for the common symmetry classes
• newton_potential.jl : Newton potentials (2D / 3D)
• green_kernel.jl : closed-form 3×3 inverse (_inv3)
• green_residue.jl : Masson / Cauchy residue summation
• green_helpers.jl : quadrature-agnostic Green-function helpers
• green_dipole.jl : real-space Kelvin Green gradient and the dipole far field of a polarized inclusion (isotropic)
• quadrature.jl : DECUHR cubature backend seam
• dispatch.jl : central _resolve_algo mechanism

AbstractInclusion{T<:Number}

Root abstract supertype for every inclusion geometry recognised by MeanFieldHom. The type parameter T is the element type of the geometric scalars (semi-axes, half-widths, …) and propagates through every tensor produced by the package, supporting Float64, ForwardDiff.Dual, SymPy.Sym, Symbolics.Num, …

AbstractEllipsoidalInclusion{dim,T} <: AbstractInclusion{T}

Supertype for ellipsoidal inclusions — solid ellipsoids (and their degenerate limits: spheres, cylinders, discs …). The first type parameter dim encodes the spatial dimension (2 or 3).

AbstractCrack{T} <: AbstractInclusion{T}

Supertype for flat-crack geometries (elliptic / ribbon / penny). Cracks always live in 3D physical space — the spatial dimension of the geometry (= 2 in the crack plane) is not exposed in the type, as downstream algorithms uniformly operate on the 3D stiffness tensor.

AbstractLayeredInclusion{dim,T} <: AbstractInclusion{T}

Supertype for multi-layer inclusions. The concrete LayeredSphere (concentric isotropic shells, Hervé-Zaoui recurrences for bulk, shear and conductivity, with five interface types) is shipped in the LayeredSpheres sub-module and extended to the ageing-viscoelastic setting in Viscoelasticity/layered_alv.jl. Open extensions (coated cylinders, anisotropic layers, excentered spheres) are tracked in docs/src/developer/roadmap.md.

AbstractAlgorithm

Abstract supertype for computation algorithms exposed through MeanFieldHom. The subtypes are plain singleton structs used as dispatch tags by the internal _kernel(...) machinery.

Closed-form / analytical algorithm — used for every isotropic matrix and for every 2D / conductivity case.

Residue-theorem algorithm — polynomial-root based, Float64 only (incompatible with ForwardDiff and SymPy).

DECUHR 2D hyper-cubature (Espelid & Genz 1994) via Integrals.jl DecuhrAlgorithm. Suitable for general anisotropy in 3D.

1D QuadGK quadrature dedicated to infinite cylinders (transverse-plane parametrization ζ(φ) = (0, cos φ / b, sin φ / c)). ForwardDiff-compatible, selected whenever an AbstractEllipsoidalInclusion with a cylindrical-shape trait meets a general-anisotropic 3D stiffness.

MaterialSymmetry

Abstract supertype classifying the symmetry class of a TensND tensor. Used by dispatch rules to select the most specific algorithm (e.g. closed-form formulas for isotropic and transversely isotropic matrices).

material_symmetry(C₀)

Return the MaterialSymmetry trait corresponding to the TensND tensor C₀. Dispatches on the concrete TensND type: TensISO → IsotropicSym, TensTI{4} → TransverselyIsotropicSym, TensOrtho → OrthotropicSym, anything else → GeneralAnisotropicSym.

extract_iso_moduli(C₀::TensISO{4,3}) -> (E, ν)

Extract Young's modulus E and Poisson's ratio ν from an isotropic 4th-order stiffness TensISO{4,3}. The internal TensND convention is $C_0 = 3k\,\mathbb J + 2μ\,\mathbb K$ i.e. C₀.data = (3k, 2μ).

extract_iso_moduli(C₀::TensISO{4,2}) -> (E, ν)

2D plane-strain counterpart of extract_iso_moduli for TensISO{4,2}. The same 3D formulas are used because the TensND storage is dimension-agnostic (TensISO{4,d} stores the same (α, β) = (3k, 2μ) pair).

extract_ti_moduli(C₀, n̂) -> (E, H, ν₁, ν₂, Γ)

Read the five TI compliance moduli out of a stiffness tensor C₀ whose axis of symmetry is n̂. Used by the closed-form COD formulas of the Cracks sub-module.

The moduli are defined through the compliance tensor $\mathbb S = C_0^{-1}$ as:

• $E = 1/S_{1111}$
• $H = 1/(S_{3333}·E)$
• $ν_1 = -E \cdot S_{1122}$
• $ν_2 = -E \cdot S_{1133}$
• $Γ = (1+ν_1)/(2·E·S_{2323})$

See the package documentation for the full derivation.

newton_potential_3d(a, b, c) -> (Iv, IIv)

Newton potential integrals for a 3-D ellipsoid with semi-axes a ≥ b ≥ c > 0.

Returns:

• Iv = (I_a, I_b, I_c) with I_a + I_b + I_c = 4π
• IIv = (I_aa, I_bb, I_cc, I_bc, I_ca, I_ab)

Two methods are provided:

• T<:Real (includes Float64, ForwardDiff.Dual): numerically stable case-split using tolerance comparisons (sphere, oblate, prolate, triaxial with elliptic integrals).
• T<:Number (e.g. SymPy.Sym, Symbolics.Num): structural equality via isequal selects the same four cases.

newton_potential_3d(ell::Ellipsoid{3})

Ellipsoid-level convenience wrapper that forwards to Core.newton_potential_3d.

newton_potential_2d(a, b) -> (Ia, Ib)

Newton potential integrals for a 2-D ellipse with semi-axes a ≥ b > 0. Returns (Ia, Ib) with Ia + Ib = 2π.

Works for any T<:Number including ForwardDiff.Dual, SymPy.Sym, Symbolics.Num.

Formulas:

• Circle: Ia = Ib = π
• General ellipse: Ia = 2πb/(a+b), Ib = 2πa/(a+b)

newton_potential_2d(ell::Ellipsoid{2})

Ellipsoid-level convenience wrapper that forwards to Core.newton_potential_2d.

newton_potential_3d_cylinder(b, c) -> (Iv, IIv)

Newton potential integrals for an infinite cylinder of elliptic cross-section with transverse semi-axes b ≥ c > 0 (cylinder axis = e₁, transverse plane = (e₂, e₃)).

Obtained as the limit a → ∞ of newton_potential_3d — the cylinder axis contributes no finite Newton mass (I_a = I_aa = I_ab = I_ac = 0) and the transverse potentials collapse to simple rational expressions in (b, c).

Returns:

• Iv = (I_a, I_b, I_c) with I_a + I_b + I_c = 4π, I_a = 0.
• IIv = (I_aa, I_bb, I_cc, I_bc, I_ca, I_ab) with I_aa = I_ab = I_ac = 0.

Two methods are provided:

• T<:Real (includes Float64, ForwardDiff.Dual): numerically stable case-split via tolerance comparison to pick the circular (b = c) or the elliptic (b > c) branch.
• T<:Number (SymPy.Sym, Symbolics.Num, …): structural equality via isequal selects the two branches.

Both branches are written as closed-form limits — no 1/(b² − c²) style denominators, so the routine is free of 0/0 indeterminacies at b = c and differentiable through ForwardDiff.

newton_potential_3d_cylinder(cyl::Cylinder)

Cylinder-level convenience wrapper that forwards to Core.newton_potential_3d_cylinder using the transverse semi-axes of cyl.

dimension(incl::AbstractInclusion) -> Int

Spatial dimension of the inclusion's ambient space (2 or 3 for the concrete inclusions shipped with the package).

element_type(incl::AbstractInclusion{T}) -> Type{T}

Element type of the geometric scalars stored in the inclusion (Float64, ForwardDiff.Dual, SymPy.Sym, …).

inclusion_basis(incl::AbstractInclusion) -> TensND.AbstractBasis

Local principal basis of the inclusion (principal frame for an ellipsoid, $(\hat l, \hat m, \hat n)$ for a crack, …). Used by downstream algorithms to rotate the matrix stiffness / conductivity into the inclusion frame.

shape_trait(incl::AbstractInclusion) -> Type

Concrete shape classification of the inclusion, used as a type parameter for Holy-style dispatch in the downstream kernels. Typical values: Spherical, Prolate, Oblate, Triaxial, Circular, Elliptic (ellipsoids), Penny, EllipticShape, Ribbon (cracks).

shape_tensor(incl::AbstractInclusion) -> AbstractTens{2}

Symmetric 2nd-order tensor encoding both the semi-axes and the orientation of an equivalent ellipsoidal envelope of the inclusion, in the global (canonical) frame.

\[\mathbf A = \mathbf R \; \mathrm{diag}(a_1, a_2, \dots) \; \mathbf R^{\!T}\]

where $\mathbf R$ is the rotation matrix mapping the canonical frame onto the inclusion's local basis and the diagonal entries are the semi-axes in the order dictated by the local basis.

Conventions for degenerate cases:

isotropify(t::TensND.AbstractTens{4,3}) → TensND.TensISO{4}

Exact average of t over SO(3): α = T_iijj/3, β = (T_ijij − α)/5 → α𝕁 + β𝕂. Valid for minor-symmetric tensors with or without major symmetry (the isotropic subspace is {𝕁, 𝕂} in both cases).

isotropify(t::TensND.AbstractTens{2,3}) → TensND.TensISO{2}

Exact SO(3) average of a 2nd-order tensor: (tr t / 3) 𝟏.

transverse_isotropify(t::TensND.AbstractTens{4,3}, n) → TensND.TensTI{4,T,8}

Exact average of t over all rotations about the axis n ((1/2π)∫ R_φ ⋆ t dφ), for a minor-symmetric t with or without major symmetry. The result lives in the full 8-dimensional axially-invariant space: the non-major-symmetric components (ℓ₃ ≠ ℓ₄) and the antisymmetric azimuthal couplings (ℓ₇, ℓ₈) are preserved — they are dropped by naive symmetric TI projections but present in e.g. averaged strain-concentration tensors.

transverse_isotropify(t::TensND.AbstractTens{2,3}, n) → TensND.TensTI{2,T,3}

Exact azimuthal average of a 2nd-order tensor about n: a·nT + b·nₙ + c·w with b = n̂ᵀ t n̂, a = (tr t − b)/2 and c = (w : t)/2 (w the in-plane rotation generator w·p = n̂ × p). The antisymmetric in-plane part c is preserved (a symmetric TI parametrization would silently drop it).