API — LayeredSphere
MeanFieldHomogenization.LayeredSpheres Module
MeanFieldHomogenization.LayeredSpheresIsotropic n-layer spherical composite inclusion (core + concentric shells) embedded in an infinite matrix, with perfect or imperfect interfaces (spring / surface-elastic / Kapitza / surface-conductive). Public entry points: LayeredSphere, the bulk / shear concentration and layer-average utilities.
MeanFieldHomogenization.LayeredSpheres.LayeredSphere Type
LayeredSphere{T, N, Cs, Is} <: AbstractLayeredInclusion{3, T}Isotropic N-layer spherical composite inclusion (core + concentric shells) embedded in an infinite matrix. Type parameters:
T— element type of the radii (Float64,BigFloat,ForwardDiff.Dual,SymPyPythonCall.Sym,Symbolics.Num, …).N— number of layers ( ).Cs— concrete type of themoduliNTuple.Is— concrete type of theinterfacesNTuple.
Use the keyword-argument constructor LayeredSphere(radii, moduli; interfaces) for most cases.
Convention
Radii
are ascending, implicit.Moduli
per layer, layer between and . Interfaces
at each radius ; interface is the outer boundary with the matrix.
MeanFieldHomogenization.LayeredSpheres.AbstractInterface Type
AbstractInterface{T}Root supertype for interface conditions in a LayeredSphere. Concrete subtypes determine the jump matrix applied to the state vector
MeanFieldHomogenization.LayeredSpheres.PerfectInterface Type
PerfectInterface{T}()Perfect (continuous) interface: all state-vector components are continuous.
MeanFieldHomogenization.LayeredSpheres.SpringInterface Type
SpringInterface(kn, kt)
SpringInterface(kn)
SpringInterface(; kn, kt) # stiffnesses
SpringInterface(; sn, st) # compliancesImperfect interface of linear-spring type: the traction stays continuous while the displacement jumps in proportion to it,
kn, kt are the normal and tangential stiffnesses sn, st the matching compliances
itf = SpringInterface(50.0, 20.0) # stiffnesses
itf.kn, itf.kt # (50.0, 20.0)
itf.sn, itf.st # (0.02, 0.05)
SpringInterface(; sn = 0.02, st = 0.05) # == itfLimits: PerfectInterface; SpringInterface(kn) is a normal spring with the tangential direction bonded (
Compliances are what is stored
The perfect interface is ForwardDiff.Dual and in the symbolic types, where an Inf would poison the derivative. The stiffness spelling is a conversion on read and on write; the transfer matrices consume spring_compliances.
Echoes' PRIMALDISC takes the same stiffness convention, so the two accept the same numbers.
For a full compliance tensor with normal/tangential coupling, see AnisotropicSpringInterface.
MeanFieldHomogenization.LayeredSpheres.MembraneInterface Type
MembraneInterface{T}(κs::T, μs::T)Imperfect interface of surface-elastic (Gurtin–Murdoch "membrane") type — the dual analog of SpringInterface and the elastic counterpart of Echoes' DUALDISC. The interface behaves as a 2D elastic shell with surface moduli ks) and surface shear
and the shear (
The PerfectInterface. These jumps reproduce Echoes' DUALDISC concentration tensors and effective moduli to machine precision.
MeanFieldHomogenization.LayeredSpheres.KapitzaInterface Type
KapitzaInterface{T}(resistance::T)Thermal imperfect interface with scalar thermal resistance resistance): the flux is continuous and the temperature drops across the interface in the direction of the flux,
with SpringInterface: in the dictionary
MeanFieldHomogenization.LayeredSpheres.SurfaceConductiveInterface Type
SurfaceConductiveInterface{T}(conductance::T)Highly-conductive 2D surface layer (dual analog of MembraneInterface). Introduces a flux jump driven by the surface Laplacian of the temperature; for the spherical harmonic conductance),
PerfectInterface.
MeanFieldHomogenization.LayeredSpheres.layer_count Function
layer_count(lam) -> IntNumber of layers in one period.
layer_count(spheroid) -> IntNumber of layers (excluding the matrix).
layer_count(incl::FEAxiLayeredSpheroid) -> IntHow many layers the inclusion has, the matrix excluded.
layer_count(sphere) -> IntNumber of layers (excluding the matrix).
MeanFieldHomogenization.LayeredSpheres.layer_radius Function
layer_radius(sphere, k) -> TOuter radius of layer k. Layer 1 extends from 0 to layer_radius(1), layer k from layer_radius(k-1) to layer_radius(k).
MeanFieldHomogenization.LayeredSpheres.layer_modulus Function
layer_modulus(spheroid, k)Isotropic conductivity of layer k.
layer_modulus(sphere, k)Stiffness (or conductivity) tensor of layer k.
MeanFieldHomogenization.LayeredSpheres.layer_property_average Function
layer_property_average(spheroid, Val(2)) -> TensISO{2,3}Voigt (volume) average of the layer conductivities,
layer_property_average(sphere, P₀) -> TensISO
layer_property_average(sphere, Val(order)) -> TensISOVoigt (volume) average of the layer properties: the stiffnesses, P₀ is a fourth-order tensor (order = 4), the conductivities, order = 2); P₀ only sets the order. This is what the Voigt bound needs for a composite sphere: the declared phase property does not represent it. Explicit names: layer_stiffness_average and layer_conductivity_average.
MeanFieldHomogenization.LayeredSpheres.layer_inverse_property_average Function
layer_inverse_property_average(spheroid, Val(2)) -> TensISO{2,3}Reuss (volume) average of the layer resistivities,
layer_inverse_property_average(sphere, P₀) -> TensISO
layer_inverse_property_average(sphere, Val(order)) -> TensISOReuss (volume) average of the inverse layer properties: the compliances, layer_compliance_average and layer_resistivity_average.
MeanFieldHomogenization.LayeredSpheres.layer_interface Function
layer_interface(lam, k::Integer) -> AbstractInterfaceThe interface on top of layer k (the k-th in stacking order); k = N closes the cell onto layer 1 by periodicity.
layer_interface(spheroid, k) -> AbstractInterfaceInterface condition at layer_q(spheroid, k) (between layer k and layer k+1 if k < N, or with the matrix if k = N).
layer_interface(sphere, k) -> AbstractInterfaceInterface condition at layer_radius(k) (between layer k and layer k+1 if k < N, or with the matrix if k = N).
MeanFieldHomogenization.LayeredSpheres.layer_volume_fraction Function
layer_volume_fraction(lam, name::Symbol) -> NumberVolume fraction name.
layer_volume_fraction(spheroid, k) -> TVolume fraction of layer k inside the outer spheroid
layer_volume_fraction(sphere, k) -> TVolume fraction of layer k inside the outer sphere of radius layer_radius(N).
MeanFieldHomogenization.LayeredSpheres.outer_radius Function
outer_radius(sphere) -> TOutermost radius of the composite sphere.
MeanFieldHomogenization.LayeredSpheres.layer_gradient_average Function
layer_gradient_average(sphere, C₀, ε∞, layer) -> Tens{2,3}Volume-averaged strain tensor layer-th layer of a LayeredSphere embedded in an isotropic matrix C₀, under a remote strain ε∞. Returns a symmetric 2-tensor in the canonical frame. Combines the bulk concentration
This is the strain of the layer's material: the opening of a SpringInterface on either side of it is not included. gradient_gradient_concentration(sphere, C₀; layer, external, internal) adds it.
layer_gradient_average(sphere, K₀, ∇T∞, layer) -> Vec{3}Volume-averaged temperature gradient layer-th layer of a LayeredSphere in an isotropic matrix K₀.
The conduction method. The average is a scalar multiple of the remote gradient, and that scalar is constant inside a layer: with
the
MeanFieldHomogenization.LayeredSpheres.layer_flux_average Function
layer_flux_average(sphere, C₀, ε∞, layer) -> Tens{2,3}Volume-averaged stress layer-th layer, under a remote strain ε∞.
Note this is the average of the stress inside the layer's material. A MembraneInterface additionally carries a surface stress on the layer boundary, which belongs to the interface rather than to either adjacent bulk, and is therefore not included here — property_contribution and flux_gradient_concentration account for it separately. The gap is not small: on a two-layer sphere with MembraneInterface(1.3, 0.7), sphere_flux_average and flux_gradient_concentration ⊡ ε∞ differ by order one, while with perfect interfaces they agree to machine precision.
layer_flux_average(sphere, K₀, ∇T∞, layer) -> Vec{3}Volume-averaged flux layer-th layer, with the Fourier / Fick sign convention.
MeanFieldHomogenization.LayeredSpheres.sphere_gradient_average Function
sphere_gradient_average(sphere, C₀, ε∞) -> Tens{2,3}Volume-averaged strain over the whole composite sphere (all layers combined):
This is the strain of the material, which leaves out the opening of the spring interfaces. The strain of the sphere seen from the matrix, which the schemes use, includes it: gradient_gradient_concentration(sphere, C₀, C₀) ⊡ ε∞. The two agree when every interface is perfect or a membrane.
sphere_gradient_average(sphere, K₀, ∇T∞) -> Vec{3}Volume-averaged temperature gradient over the whole composite sphere,
As in elasticity, an average over the material: the temperature jump across a KapitzaInterface is left out, and gradient_gradient_concentration(sphere, K₀, K₀) includes it.
MeanFieldHomogenization.LayeredSpheres.sphere_flux_average Function
sphere_flux_average(sphere, C₀, ε∞) -> Tens{2,3}Volume-averaged stress over the whole composite sphere,
sphere_flux_average(sphere, K₀, ∇T∞) -> Vec{3}Volume-averaged flux over the composite sphere,
MeanFieldHomogenization.LayeredSpheres.cumulative_strain_average Function
cumulative_strain_average(sphere, C₀, ε∞, r) -> Tens{2,3}Volume-averaged strain over the ball of radius
Why a truncated layer is not a scaled one
Weighting the full-layer average by the truncated volume — the obvious shortcut — is correct only where the field is uniform inside a layer, and it is not: the mode-2 term of the deviatoric solution varies as _layer_avg_dev_shear_factor at the cut radius. The two agree at
MeanFieldHomogenization.LayeredSpheres.spring_compliances Function
spring_compliances(intf::SpringInterface) -> (sn, st)Normal and tangential compliances — the quantities the transfer matrices multiply the traction by. This is the stored pair; a perfect interface gives exact zeros.
MeanFieldHomogenization.LayeredSpheres.spring_stiffnesses Function
spring_stiffnesses(intf::SpringInterface) -> (kn, kt)Normal and tangential stiffnesses,
MeanFieldHomogenization.LayeredSpheres.LayeredSphereFields Type
LayeredSphereFields(sphere, C₀)Precomputed pointwise elastic solution of a LayeredSphere embedded in the isotropic matrix C₀: the per-region amplitudes of the spherical mode pair
Build it once and pass it wherever (sphere, C₀) is accepted. Every local_* entry point also takes (sphere, C₀) directly, but that form re-runs the whole recurrence on every call — fine for a handful of points, wasteful for the thousands a field map needs.
sol = LayeredSphereFields(sphere, C₀)
A = local_gradient_gradient_concentration(sol, x)See also LayeredSphereTransportFields.
MeanFieldHomogenization.LayeredSpheres.LayeredSphereTransportFields Type
LayeredSphereTransportFields(sphere, K₀)Precomputed pointwise transport (thermal / electric / Darcy) solution of a LayeredSphere in the isotropic matrix K₀: the per-region amplitudes
Transport twin of LayeredSphereFields.
MeanFieldHomogenization.LayeredSpheres.get_layer Function
get_layer(s::LayeredSpheroid, q; side = :outer) -> IntIndex of the region containing the confocal coordinate q:
Exactly on an interface side picks one — :outer (default) the limit from outside, region :inner the limit from inside, region get_layer(::LayeredSphere, r); it matters for a KapitzaInterface, across which the temperature itself jumps.
get_layer(sphere::LayeredSphere, r; side = :outer) -> IntIndex of the region containing the radius r:
Layer side picks one:
side = :outer(default) — the limit from above, : region , consistent with the half-open convention used bylayer_volume_fractionand byLayeredSpheroids.get_layer;side = :inner— the limit from below, : region .
The distinction is not cosmetic. Across a SpringInterface the displacement jumps and across a MembraneInterface the traction jumps, so local_flux(…, r_k; side = :inner) and side = :outer return genuinely different tensors — that difference is the interface law, and the test suite checks it against the prescribed jump.
Radii beyond side.
A symbolic radius is refused rather than located. SymPyPythonCall.Sym answers a comparison it cannot decide with a plain false — r ≥ 1.0 on a positive symbol returns Bool(false), not an error — so the loop below would silently return layer 1 for any symbol. Name the region explicitly instead: every pointwise entry point takes a layer keyword.
MeanFieldHomogenization.LayeredSpheres.region_stiffness Function
region_stiffness(f::LayeredSphereFields, k) -> TensISO{4,3}Stiffness tensor of region k, the matrix C₀ for k = N+1.
MeanFieldHomogenization.LayeredSpheres.shell_concentration Function
shell_concentration(f::LayeredSphereFields, k) -> (α_k, β_k)Volume-averaged bulk and shear concentration of layer k, recovered from the cached pointwise amplitudes: _layer_avg_dev_shear_factor(r_{k-1}, r_k, κ_k, μ_k).
Identical by construction to _bulk_concentration and _shear_concentration, which is the point: the pointwise reconstruction and the averaged path share their amplitudes and cannot drift apart.
MeanFieldHomogenization.LayeredSpheres.local_gradient_gradient_concentration Function
local_gradient_gradient_concentration(f_or_sphere, [C₀,] x; side = :outer) -> TensTI{4,3}
local_gradient_gradient_concentration(f_or_sphere, [K₀,] x; side = :outer) -> TensTI{2,3}In elasticity, with a fourth-order matrix stiffness C₀: Pointwise strain-strain concentration tensor
The point x is either a Cartesian vector (Vec{3}, NTuple{3}, AbstractVector, 1st-order AbstractTens) or spherical coordinates given as three arguments (r, θ, φ), θ the colatitude from
The result is transversely isotropic about TensTI{4,T,6}, six Walpole scalars plus the axis, in the canonical basis.
At (0,0,1) is used. Note that
side disambiguates a point lying exactly on an interface — see get_layer.
See also local_flux_gradient_concentration, local_gradient_flux_concentration, local_flux_flux_concentration, local_gradient, LayeredSphereFields.
In conduction, with a second-order matrix conductivity K₀: Pointwise gradient-gradient concentration
TensTI{2,T,2}. Same argument forms and same side convention as in elasticity.
MeanFieldHomogenization.LayeredSpheres.local_flux_gradient_concentration Function
local_flux_gradient_concentration(f_or_sphere, [C₀,] x; side = :outer) -> TensTI{4,3}
local_flux_gradient_concentration(f_or_sphere, [K₀,] x; side = :outer) -> TensTI{2,3}In elasticity, with a fourth-order matrix stiffness C₀: Pointwise stress-strain concentration σ(x) = local_flux_gradient_concentration(…) ⊡ ε∞. x (the matrix outside).
Twin of local_gradient_gradient_concentration; same arguments and conventions.
In conduction, with a second-order matrix conductivity K₀: Pointwise flux-gradient concentration q(x) = local_flux_gradient_concentration(…) · ∇T∞, with the Fourier / Fick sign convention
MeanFieldHomogenization.LayeredSpheres.local_gradient_flux_concentration Function
local_gradient_flux_concentration(f_or_sphere, [C₀,] x; side = :outer) -> TensTI{4,3}
local_gradient_flux_concentration(f_or_sphere, [K₀,] x; side = :outer) -> TensTI{2,3}In elasticity, with a fourth-order matrix stiffness C₀: Pointwise strain-stress concentration ε(x) = local_gradient_flux_concentration(…) ⊡ σ∞.
Exact because the remote medium is uniform: local_gradient_gradient_concentration; same arguments and conventions.
In conduction, with a second-order matrix conductivity K₀: Pointwise gradient-flux concentration ∇T(x) = local_gradient_flux_concentration(…) · q∞.
MeanFieldHomogenization.LayeredSpheres.local_flux_flux_concentration Function
local_flux_flux_concentration(f_or_sphere, [C₀,] x; side = :outer) -> TensTI{4,3}
local_flux_flux_concentration(f_or_sphere, [K₀,] x; side = :outer) -> TensTI{2,3}In elasticity, with a fourth-order matrix stiffness C₀: Pointwise stress-stress concentration σ(x) = local_flux_flux_concentration(…) ⊡ σ∞.
Twin of local_gradient_gradient_concentration; same arguments and conventions.
In conduction, with a second-order matrix conductivity K₀: Pointwise flux-flux concentration q(x) = local_flux_flux_concentration(…) · q∞.
MeanFieldHomogenization.LayeredSpheres.local_gradient Function
local_gradient(f_or_sphere, [C₀,] x, ε∞; side = :outer) -> Tens{2,3}
local_gradient(f_or_sphere, [K₀,] x, ∇T∞; side = :outer) -> Vec{3}In elasticity, with a fourth-order matrix stiffness C₀: Local strain tensor at x under the remote uniform strain ε∞, i.e. local_gradient_gradient_concentration(…) ⊡ ε∞. x is Cartesian, or replace it by three arguments (r, θ, φ).
In conduction, with a second-order matrix conductivity K₀: Local temperature gradient at x under the remote uniform gradient ∇T∞, i.e. local_gradient_gradient_concentration(…) · ∇T∞.
MeanFieldHomogenization.LayeredSpheres.local_flux Function
local_flux(f_or_sphere, [C₀,] x, ε∞; side = :outer) -> Tens{2,3}
local_flux(f_or_sphere, [K₀,] x, ∇T∞; side = :outer) -> Vec{3}In elasticity, with a fourth-order matrix stiffness C₀: Local stress tensor at x under the remote uniform strain ε∞, i.e. local_gradient(…) and C₀ outside the composite sphere).
In conduction, with a second-order matrix conductivity K₀: Local flux at x under the remote uniform gradient ∇T∞, with the Fourier / Fick convention
MeanFieldHomogenization.LayeredSpheres.local_displacement Function
local_displacement(f_or_sphere, [C₀,] x, ε∞; side = :outer) -> Vec{3}Local displacement at x under the remote uniform strain ε∞:
with
Across a SpringInterface the displacement is discontinuous; use side to select the limit (see get_layer).
MeanFieldHomogenization.LayeredSpheres.local_temperature Function
local_temperature(f_or_sphere, [K₀,] x, ∇T∞; side = :outer) -> NumberLocal temperature (or pressure / potential) at x under the remote uniform gradient ∇T∞:
Discontinuous across a KapitzaInterface; use side to pick the limit (see get_layer).
The names of elasticity and of conduction
The functions above serve both physics, the order of the matrix property selecting the method. Each also answers to the name it has in elasticity (or, for the layer averages of a property, in conduction); such a name forwards to the generic function, accepts one order only, and refuses the other with an error that names the generic function.
| Generic function | Elasticity | Conduction |
|---|---|---|
layer_property_average | layer_stiffness_average | layer_conductivity_average |
layer_inverse_property_average | layer_compliance_average | layer_resistivity_average |
layer_gradient_average | layer_strain_average | |
layer_flux_average | layer_stress_average | |
sphere_gradient_average | sphere_strain_average | |
sphere_flux_average | sphere_stress_average | |
local_gradient_gradient_concentration | local_strain_strain_concentration | |
local_flux_gradient_concentration | local_stress_strain_concentration | |
local_gradient_flux_concentration | local_strain_stress_concentration | |
local_flux_flux_concentration | local_stress_stress_concentration | |
local_gradient | local_strain | |
local_flux | local_stress |
MeanFieldHomogenization.LayeredSpheres.layer_stiffness_average Function
layer_stiffness_average(sphere) -> TensISO{4,3}Name in elasticity of layer_property_average: the Voigt average of the layer stiffnesses.
MeanFieldHomogenization.LayeredSpheres.layer_compliance_average Function
layer_compliance_average(sphere) -> TensISO{4,3}Name in elasticity of layer_inverse_property_average: the Reuss average of the layer compliances.
MeanFieldHomogenization.LayeredSpheres.layer_conductivity_average Function
layer_conductivity_average(sphere) -> TensISO{2,3}Name in conduction of layer_property_average: the Voigt average of the layer conductivities.
MeanFieldHomogenization.LayeredSpheres.layer_resistivity_average Function
layer_resistivity_average(sphere) -> TensISO{2,3}Name in conduction of layer_inverse_property_average: the Reuss average of the layer resistivities.
MeanFieldHomogenization.LayeredSpheres.layer_strain_average Function
layer_strain_average(args...; kw...)Name in elasticity of layer_gradient_average, which it takes the arguments of: the mean strain of a layer, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.layer_stress_average Function
layer_stress_average(args...; kw...)Name in elasticity of layer_flux_average, which it takes the arguments of: the mean stress of a layer, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.sphere_strain_average Function
sphere_strain_average(args...; kw...)Name in elasticity of sphere_gradient_average, which it takes the arguments of: the mean strain of the composite sphere, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.sphere_stress_average Function
sphere_stress_average(args...; kw...)Name in elasticity of sphere_flux_average, which it takes the arguments of: the mean stress of the composite sphere, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.local_strain_strain_concentration Function
local_strain_strain_concentration(args...; kw...)Name in elasticity of local_gradient_gradient_concentration, which it takes the arguments of: the pointwise strain concentration tensor, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.local_stress_strain_concentration Function
local_stress_strain_concentration(args...; kw...)Name in elasticity of local_flux_gradient_concentration, which it takes the arguments of: the pointwise stress per unit remote strain, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.local_strain_stress_concentration Function
local_strain_stress_concentration(args...; kw...)Name in elasticity of local_gradient_flux_concentration, which it takes the arguments of: the pointwise strain per unit remote stress, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.local_stress_stress_concentration Function
local_stress_stress_concentration(args...; kw...)Name in elasticity of local_flux_flux_concentration, which it takes the arguments of: the pointwise stress per unit remote stress, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.local_strain Function
local_strain(args...; kw...)Name in elasticity of local_gradient, which it takes the arguments of: the local strain, for a fourth-order matrix stiffness only.
MeanFieldHomogenization.LayeredSpheres.local_stress Function
local_stress(args...; kw...)Name in elasticity of local_flux, which it takes the arguments of: the local stress, for a fourth-order matrix stiffness only.