API — Elasticity

MeanFieldHom.Elasticity

Hill polarization tensors for ellipsoidal inclusions (2D / 3D, isotropic / anisotropic matrix). Public entry point: hill_tensor.

EllipsoidShape

Abstract supertype for the shape classification of an Ellipsoid.

Concrete subtypes (3-D): Spherical, Prolate, Oblate, Triaxial.

Concrete subtypes (2-D): Circular, Elliptic.

3-D sphere: a = b = c.

3-D prolate spheroid: a > b = c (axis of revolution = e₁).

3-D oblate spheroid: a = b > c (axis of revolution = e₃).

3-D triaxial ellipsoid: a > b > c.

2-D circle: a = b.

2-D ellipse: a > b.

Ellipsoid{dim, S<:EllipsoidShape, T<:Number, B<:AbstractBasis}

Ellipsoidal inclusion of the Eshelby problem (Eshelby 1957). In the Echoes convention, an ellipsoid $\mathcal E_{\mathbf A}$ is described by an invertible second-order shape tensor $\mathbf A$ through

x ∈ E_A  ⇔  x·(Aᵀ·A)⁻¹·x ≤ 1 ,
Aᵀ·A = Σᵢ ρᵢ² êᵢ^A ⊗ êᵢ^A ,   ρ₁=a ≥ ρ₂=b ≥ ρ₃=c .

semi_axes stores the eigenvalues $\rho_i$ (sorted in decreasing order for real-valued types) and basis stores the orthonormal frame $(\hat{\mathbf e}_i^{\mathbf A})$ relative to the canonical frame.

The shape S is determined at construction time:

• 3-D: Spherical, Prolate, Oblate, or Triaxial
• 2-D: Circular or Elliptic

T can be any Number subtype (Float64, ForwardDiff.Dual, SymPy.Sym, Symbolics.Num, …).

Cylinder{S<:CylindricalShape, T<:Number, B<:AbstractBasis} <:
    AbstractEllipsoidalInclusion{3, T}

Infinite cylindrical inclusion with transverse semi-axes (b, c) (with b ≥ c > 0 when T <: Real, or in the caller-provided order when T is symbolic). The cylinder axis is the first column of the local basis — consistent with the Prolate convention where the axis of revolution is also e₁.

S encodes the cross-section shape:

• CircularCylindrical when b = c (transversely isotropic result).
• EllipticCylindrical when b > c (orthotropic result).

T can be any Number subtype (Float64, ForwardDiff.Dual, SymPy.Sym, Symbolics.Num, …) — all analytical paths are type-generic.

CylindricalShape

Abstract supertype for the shape classification of a Cylinder. Sub-traits:

• CircularCylindrical — circular base (b = c).
• EllipticCylindrical — elliptic base (b > c).

All cylinders are infinite along e₁ in the inclusion's local basis.

3-D infinite cylinder with circular base: b = c, a → ∞, axis = e₁.

3-D infinite cylinder with elliptic base: b > c, a → ∞, axis = e₁.

tens_IA(ell::Ellipsoid{3}) -> AbstractTens{2,3}
tens_IA(ell::Ellipsoid{2}) -> AbstractTens{2,2}

Newton-potential geometric tensor $\mathbf I^{\mathbf A}$ of an ellipsoid, defined by

I^A = (det A)/(4π) ∫_{|ξ|=1} ξ⊗ξ / ‖A·ξ‖³ dS_ξ .

$\mathbf I^{\mathbf A}$ is symmetric with the same eigenvectors as $\mathbf A$ and with diagonal components $I_i^{\mathbf A}$ satisfying $\sum_i I_i^{\mathbf A} = 1$ (see Kellogg 1929, Eshelby 1957, Parnell 2016).

tens_UA(ell::Ellipsoid{3}) -> AbstractTens{4,3}
tens_UA(ell::Ellipsoid{2}) -> AbstractTens{4,2}

4th-order Newton-potential geometric tensor $\mathbb U^{\mathbf A}$:

U^A = (det A)/(4π) ∫_{|ξ|=1} ξ⊗ξ⊗ξ⊗ξ / ‖A·ξ‖³ dS_ξ .

In the principal frame, the non-zero Kelvin–Mandel components are

U^A_{iiii} = 3(Iᵢ − ρᵢ² Iᵢᵢ)/2
U^A_{iijj} = U^A_{ijij} = U^A_{ijji} = (Iⱼ − ρᵢ² Iᵢⱼ)/2 ,   i≠j

with the $I_i^{\mathbf A}$ and $I_{ij}^{\mathbf A}$ coefficients given in the Echoes appendix (tables $I_i$ / $I_{ij}$).

tens_VA(ell::Ellipsoid{3}) -> AbstractTens{4,3}
tens_VA(ell::Ellipsoid{2}) -> AbstractTens{4,2}

4th-order Newton-potential geometric tensor $\mathbb V^{\mathbf A}$:

V^A = (det A)/(4π) ∫_{|ξ|=1} ξ ⊗ˢ 1 ⊗ˢ ξ / ‖A·ξ‖³ dS_ξ
    = (1 ⊠ˢ I^A + I^A ⊠ˢ 1)/2 .

In the principal frame, $V^{\mathbf A}_{iiii} = I_i^{\mathbf A}$ and $V^{\mathbf A}_{ijij} = V^{\mathbf A}_{ijji} = (I_i^{\mathbf A}+I_j^{\mathbf A})/4$ for $i\ne j$.

hill_tensor(ell, C₀; method=:auto, abstol=1e-8, reltol=1e-6, maxiters=1_000_000)
    → AbstractTens

Hill polarization tensor P for an ellipsoidal inclusion ell embedded in a reference medium C₀. C₀ can be a 4th-order stiffness (elasticity) or a 2nd-order conductivity tensor — dispatch selects the appropriate formulation automatically.

The general expression of the elastic polarization tensor is (Willis 1977, Mura 1987):

P(A, C) = (det A)/(4π) ∫_{|ξ|=1} ξ ⊗ˢ (ξ·C·ξ)⁻¹ ⊗ˢ ξ / ‖A·ξ‖³ dS_ξ

The isotropic case (C₀::TensISO) is evaluated analytically; the anisotropic case uses the Cauchy-residue reduction of Masson 2008 (trait Residue) or the DECUHR adaptive cubature of Espelid & Genz 1994 (trait DECUHR). See the Hill polarization tensors theory page for the full dispatch table and return types.

hill_tensor(incl::NeuralHillInclusion, P₀; kw...) -> AbstractTens

Hill tensor evaluated by the surrogate: features off the geometry and P₀, one forward pass, then an exact decode into the structured tensor of the surrogate's class, in the global frame.

Keyword arguments of the analytic entry points (method, tolerances) are accepted and ignored — there is no quadrature to steer — so a scheme that forwards them works unchanged.

eshelby_tensor(incl, C₀; method=:auto, abstol, reltol, maxiters) -> AbstractTens

Eshelby tensor of the inclusion incl embedded in a matrix of stiffness / conductivity C₀, derived from the Hill polarization tensor $\mathbb P$ (or $\mathbf P$) by the relations

\[\mathbb S = \mathbb P : \mathbb C_0 \qquad\text{(order 4, elasticity)}\]

\[\mathbf s = \mathbf P \cdot \mathbf K_0 \qquad\text{(order 2, conductivity / diffusion)}\]

The appropriate method is selected by dispatch on the order of C₀: an AbstractTens{4, 3} (elasticity) triggers the double contraction $\mathbb P \;\underset{s}{:}\; \mathbb C_0$, while an AbstractTens{2, 3} (conductivity) triggers the simple contraction $\mathbf P \cdot \mathbf K_0$.

All keyword arguments (method, abstol, reltol, maxiters) are forwarded verbatim to hill_tensor; see its docstring for the set of admissible algorithm traits.

See also hill_tensor.