API — Elasticity

MeanFieldHomogenization.Elasticity Module

MeanFieldHomogenization.Elasticity

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

MeanFieldHomogenization.Elasticity.EllipsoidShape Type

EllipsoidShape

Abstract supertype for the shape classification of an Ellipsoid.

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

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

MeanFieldHomogenization.Elasticity.Spherical Type

3-D sphere: a = b = c.

MeanFieldHomogenization.Elasticity.Prolate Type

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

MeanFieldHomogenization.Elasticity.Oblate Type

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

MeanFieldHomogenization.Elasticity.Triaxial Type

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

MeanFieldHomogenization.Elasticity.Circular Type

2-D circle: a = b.

MeanFieldHomogenization.Elasticity.Elliptic Type

2-D ellipse: a > b.

MeanFieldHomogenization.Elasticity.Ellipsoid Type

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

Ellipsoidal inclusion of the Eshelby problem ([6]). In the Echoes convention, an ellipsoid is described by an invertible second-order shape tensor through

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

semi_axes stores the eigenvalues (sorted in decreasing order for real-valued types) and basis stores the orthonormal frame 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, …).

MeanFieldHomogenization.Elasticity.Spheroid Function

Spheroid(ω; euler_angles = ())

Convenience constructor for an axisymmetric ellipsoid (spheroid). The aspect ratio ω is the ratio of the polar semi-axis (along the axis of revolution) to the equatorial semi-axis:

• ω < 1 ⇒ oblate (disc-like, axis of revolution is the short axis)

• ω > 1 ⇒ prolate (needle-like, axis of revolution is the long axis)

• ω = 1 ⇒ sphere

The two equatorial semi-axes are fixed to 1. Eshelby/Hill computations are scale-invariant, so the absolute size of the inclusion has no effect on the localization tensor and only ω matters.

Optional euler_angles (tuple of length 0–3, ZYZ convention, radians) rotate the symmetry axis from ez. Without angles, the axis of revolution is ez (oblate) or ex (prolate) — i.e. the result is strictly equivalent to Ellipsoid(1, 1, ω; euler_angles), with internal sorting and basis permutation handled by the regular Ellipsoid constructor.

Examples

Spheroid(0.2)                                      # oblate (axis ‖ ez)
Spheroid(5.0)                                      # prolate (axis ‖ ez after sort)
Spheroid(0.2; euler_angles = (π/4, π/3, 0))        # tilted axis

MeanFieldHomogenization.Elasticity.Cylinder Type

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.

MeanFieldHomogenization.Elasticity.CylindricalShape Type

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.

MeanFieldHomogenization.Elasticity.CircularCylindrical Type

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

MeanFieldHomogenization.Elasticity.EllipticCylindrical Type

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

MeanFieldHomogenization.Elasticity.tens_IA Function

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

Newton-potential geometric tensor of an ellipsoid, defined by

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

is symmetric with the same eigenvectors as and with diagonal components satisfying   (see [11], [6], [12]).

MeanFieldHomogenization.Elasticity.tens_UA Function

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

4th-order Newton-potential geometric tensor :

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 and coefficients given in the Echoes appendix (tables / ).

MeanFieldHomogenization.Elasticity.tens_VA Function

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

4th-order Newton-potential geometric tensor :

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

In the principal frame,   and     for  .

MeanFieldHomogenization.Elasticity.hill_tensor Function

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 ([8], [10]):

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 [16] (trait Residue) or the DECUHR adaptive cubature of [17] (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.

MeanFieldHomogenization.Core.eshelby_tensor Function

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 (or ) by the relations

The appropriate method is selected by dispatch on the order of C₀: an AbstractTens{4, 3} (elasticity) triggers the double contraction    , while an AbstractTens{2, 3} (conductivity) triggers the simple contraction  .

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.

MeanFieldHomogenization.Elasticity.iso_stiffness Function

iso_stiffness(k, mu) -> TensND.TensISO{4}

Build the isotropic stiffness tensor C = 3k·𝕁 + 2μ·𝕂 from (k, μ) — the reciprocal of k_mu.

Nanoinclusion interfaces

MeanFieldHomogenization.Elasticity.surface_stiffness Function

surface_stiffness(spheroid, κs, μs) -> TensTI{4}

Average surface stiffness of a spheroidal nanoinclusion carrying a Gurtin-Murdoch interface of surface bulk modulus κs and surface shear modulus μs ([35]).

spheroid is an Ellipsoid of revolution with in-plane semi-axis a and polar semi-axis c; the aspect ratio is  , oblate for   and prolate for  . The result is transversely isotropic about the symmetry axis, with

and four companion components given in the same reference. κs and μs have the dimension of a stiffness times a length, so scales as 1/a: the stiffening it produces is a size effect, controlled by the smallest dimension of the particle.

Adding it to the bulk stiffness gives the equivalent particle of the paper, equivalent_particle, which any scheme of the package accepts as an ordinary inclusion property.

Limiting cases are handled exactly: the spherical case   — where the closed form has a removable singularity — is evaluated from its Taylor series, and reproduces the isotropic tensor      of the same reference.

MeanFieldHomogenization.Elasticity.equivalent_particle Function

equivalent_particle(C_I, spheroid, κs, μs) -> AbstractTens

Stiffness of the equivalent particle — the nanoinclusion C_I together with its interface — of [35]:

The paper's central result is that the strain concentration rule and the homogenized stiffness keep their classical form once this substitution is made, so a nanocomposite estimate needs no new scheme:

C_eq = equivalent_particle(C_i, Spheroid(0.1), κs, μs)
add_phase!(rve, :nano, Spheroid(0.1), Dict(:C => C_eq); fraction = f)
homogenize(rve, MoriTanaka(), :C)

Note that the strain average rule is unaffected by the interface, but the stress average rule is not: the interface contributes   to the macroscopic stress, which is precisely what using in the scheme accounts for.

Parameter conversions

MeanFieldHomogenization.Elasticity.k_mu Function

k_mu(C::TensND.TensISO{4}) -> (k, mu)

Bulk and shear modulus of an isotropic stiffness tensor C = 3k·𝕁 + 2μ·𝕂. For a compliance tensor S, use k_mu(inv(S)).

For a tensor that is not already a TensISO, project first: k_mu(best_fit_iso(C)).

MeanFieldHomogenization.Elasticity.E_nu Function

E_nu(C::TensND.TensISO{4}) -> (E, nu)

Young's modulus and Poisson's ratio of an isotropic stiffness tensor. For a compliance tensor S, use E_nu(inv(S)).

MeanFieldHomogenization.Elasticity.iso_stiffness_E_nu Function

iso_stiffness_E_nu(E, nu) -> TensND.TensISO{4}

Build the isotropic stiffness tensor from Young's modulus and Poisson's ratio — the reciprocal of E_nu.

MeanFieldHomogenization.Elasticity.hoenig_params Function

hoenig_params(t::TensND.TensTI{4}) -> (E1, h, nu1, nu2, gamma)
hoenig_params(t::TensND.AbstractTens{4,3}, axis) -> (E1, h, nu1, nu2, gamma)

Hoenig (1978) parametrization of a transversely isotropic stiffness tensor: E1 the in-plane Young's modulus, h the axial/in-plane modulus ratio, nu1 the in-plane Poisson's ratio, nu2 the out-of-plane Poisson's ratio, and gamma the shear anisotropy ratio.

For a tensor that is not already TensTI, the 2-argument form projects onto the TI span about axis first (via TensND.proj_tens(Val(:TI), t, axis), the same machinery backing best_fit_ti). For a compliance tensor, use hoenig_params(inv(S)) / hoenig_params(inv(S), axis).

MeanFieldHomogenization.Elasticity.hoenig_stiffness Function

hoenig_stiffness(E1, h, nu1, nu2, gamma, axis) -> TensND.TensTI{4,T,5}

Build the TI stiffness tensor from its Hoenig (1978) parameters and symmetry axis — the reciprocal of hoenig_params.

The cubic symmetry class

The class itself lives in TensND: TensCubic stores the three constants and a cube frame, its products and inverses are componentwise, tens_cubic / arg_cubic convert to and from , cubic_anisotropy is the Zener-type departure from isotropy, and proj_tens(Val(:CUBIC), t, frame) — or best_fit_cubic — projects onto the class. None of that is reimplemented here.

What this package adds is a name for the projection residual, which is the quantity a solver reads, and the symmetry trait. The trait is honest only now that a storage type exists: material_symmetry answers from the container, and before TensND had TensCubic a CubicSym would have let dispatch claim a structure the object did not carry.

Read cubic_residual and cubic_anisotropy together. The first is the distance to a class the answer belongs to by group theory, so it is discretization error and nothing else; the second lives inside the class. An artifact breaks the symmetry, a real morphological anisotropy does not.

MeanFieldHomogenization.Elasticity.cubic_residual Function

cubic_residual(t, frame = CanonicalBasis{3,Float64}()) -> Real

Relative Frobenius distance from t to its projection onto the cubic class with cube axes frame — the third value returned by proj_tens(Val(:CUBIC), t, frame), named because it is the one that gets read.

This is a free error bar. Where the morphology and the medium leave the octahedral group invariant, the answer belongs to the class by group theory, so this distance is bounded by the discretization error and by nothing else: no reference solution appears in it. What lives inside the class, and is therefore not measured here, is TensND.cubic_anisotropy. Read together they separate a real morphological anisotropy from a numerical artifact — an artifact breaks the symmetry, a real anisotropy does not.

The default frame is the canonical one. Pass the inclusion's own basis when the cube is not aligned with it: a rotated cubic tensor is not cubic about the canonical axes, and the residual would say so, correctly but uselessly.

MeanFieldHomogenization.Elasticity.CubicSym Type

Cubic material (TensND TensCubic) — three independent constants.