Tutorials
Mean-field homogenization replaces a heterogeneous microstructure — a matrix carrying inclusions, pores, or cracks — by an equivalent homogeneous medium with the same overall response. MeanFieldHomogenization computes that response from phase properties, geometries, volume fractions, and a scheme encoding an assumption about how the phases interact.
Simplest first within each group. Pages under generated/ are produced from the runnable demos in scripts/ by Literate.jl.
Fundamentals
The porous material gets two pages: the simplest non-trivial microstructure, and the one where the choice of scheme matters most.
| Page | What it shows |
|---|---|
| A first homogenization | build an RVE; dilute vs Mori–Tanaka |
| Bounds and classical schemes | Voigt/Reuss bounds, self-consistent, where each scheme sits |
| Porous materials and the self-consistent trap | why soft pores break the naive SC iteration |
| Porous benchmark: all schemes | every scheme on the canonical porosity sweep, spheres and oblate pores |
| Transport properties | the same algebra at tensor order 2: diffusivity of a porous medium, anisotropy from oriented pores |
| The differential scheme and path dependence | incremental homogenization; why mixing order matters |
| Comparing loading-path trajectories | the same target fractions, four trajectories, watched τ by τ |
Inclusions, geometries and orientation
| Page | What it shows |
|---|---|
| Hill polarization tensors in practice | hill_tensor on four geometries; residues vs cubature on an anisotropic matrix; the Eshelby tensor against its closed form; P → a dilute estimate |
| Cracks and crack density | volume fraction → crack density; the COD tensor |
| Crack distributions: isotropic or parallel | the same density, two orientation rules; the two self-consistent forms and their two percolation thresholds (9/16 exactly for the compliance form, ≈ 1.158 for the stiffness one); the local-versus-global frame of a TensRotated result |
| Validating a finite-element crack | the same crack solved by finite elements: what the corrected boundary condition buys, and convergence to the closed-form COD |
| Layered spheres | Hervé–Zaoui n-layer localization and layer averages |
| Layered spheroids: geometry and effective conductivity | the confocal n-layer spheroid, the equivalent particle, harmonic-series accuracy |
| Imperfect interfaces: what they do to the local fields | pointwise temperature and flux, streamlines, conductance sweep, 3-D view |
| Highly conducting interfaces | equivalent conductivity of an HC-coated particle vs aspect ratio |
| A layered spheroid, meshed | the same body by Fourier axisymmetric finite elements: calibrated against the two closed forms, taken to nests neither covers, then replaced by a surrogate trained on the cell so the morphology becomes differentiable |
| Nanocomposites: the equivalent particle | a Gurtin-Murdoch interface condensed into a particle stiffness, its three limiting shapes reproduced exactly, and the size effect it produces through an ordinary Mori-Tanaka estimate — no new scheme needed |
| Periodic multilayer: the exact laminate solution | a cell with no matrix and no Eshelby problem: the exact effective tensor, per-layer localization, the bounds it saturates |
| Imperfect interfaces in a laminate, and the size effect | the four interface models on a planar interface, and the interface density that makes the period matter |
| Symmetrization | exact rotation-group average vs best-fit projection |
| The custom-inclusion contract | plugging an arbitrary morphology into every scheme — the three entry gates, the density seam, free orientation averaging |
| An inclusion whose response is a neural network | both phases — how a surrogate is trained (schematics of the network and of the fitting loop, the recorded learning curve) and how a trained one is used: what stays exact whatever the fit, accuracy against the closed form, every scheme, and the derivative with respect to the morphology |
| Replacing a finite-element solve by a surrogate | the case the machinery exists for: the eccentric-core sphere, whose localization tensors have no closed form. Gate B with the 6-component transversely isotropic pair, the contrast ratios that replace gate A's homogeneity, the accuracy against the finite elements, the speed-up, and a derivative with respect to the eccentricity |
Composite inclusions carry no Hill tensor at all: they enter the schemes through their volume-averaged concentration tensors instead.
Interacting particle assemblies
The two N-body schemes. Every other scheme of the package sees a single inclusion in a reference medium and averages the interaction; these two resolve it inclusion by inclusion, so they need a ParticleAssembly — a cell that carries positions — rather than an RVE. Both are built on the same two-inclusion interaction tensor.
| Tutorial | What it shows |
|---|---|
| Chaining scales through an N-body scheme | the declarative multiscale seam with an assembly on either side, and why chaining two N-body estimates needs the anisotropic Green operator: a cluster estimate on a cubic array is cubic, not isotropic. Three scales end to end, plus a sensitivity across them |
The cluster model on cubic arrays and the equivalent inclusion method against a published table are under Applications: each exists to reproduce one paper's numbers rather than to teach the library.
Theory: interaction tensors, the cluster model, the equivalent inclusion method; the API is on the particle-assembly manual page.
Beyond elasticity
| Page | What it shows |
|---|---|
| Viscoelastic composites | complex moduli in the frequency domain; a first taste of ageing creep |
| The rheological model catalog | the classical chains, the fractional family and the bituminous models side by side; master curves, Cole-Cole and Black diagrams; the exact 2S2P1D pair in both domains; and one object driving both homogenization routes |
| Generalized Kelvin ⇄ generalized Maxwell | the exact conversion between the two representations: the interlacing that makes it unconditionally robust, the round trip at twenty branches, and two independent closed forms — the Zener relations and the Burgers relaxation function — as oracles |
| Choosing a numerical Laplace inversion | four algorithms measured against four exact pairs; why branch cuts are not the problem and oscillation is; the Gaver-Stehfest optimum and why more terms is worse; ForwardDiff straight through |
| Frequency or time? | the complex-modulus and time-domain ALV routes, cross-checked on the same non-ageing composite |
| Ageing viscoelastic schemes side by side | Dilute / Mori-Tanaka / Maxwell / PCW on one creep test; the aspect ratio; where the distribution shape decides the answer |
| Ageing creep: loading age against inclusion shape | ageing and morphology on the same output: three loading ages × three aspect ratios, and why the shape effect is an offset independent of the age |
| A creeping laminate | the exact multilayer in ageing viscoelasticity: the same algebra with Volterra products in place of tensor products |
| Derivatives through the ageing-viscoelastic pipeline | ForwardDiff through the Volterra assembly: the set_param lens for RVE parameters, closure capture for moduli and relaxation times |
Differentiation and solvers
| Page | What it shows |
|---|---|
| Derivatives and sensitivities | differentiate any result with ForwardDiff, no finite differences |
| From derivatives to a strength criterion | those derivatives as a macroscopic strength criterion |
| Nonlinear solvers for the self-consistent fixed point | NonlinearSolve.jl instead of Picard, and sensitivities that agree either way |
| Nonlinear homogenization by the secant method | elastic–perfectly plastic porous solid, closed by second moments |
Interoperability and tools
| Page | What it shows |
|---|---|
| Symbolic spheres | the same tensor algebra on SymPy / Symbolics expressions: Eshelby/Hill tensors and the closed-form estimates |
| Symbolic laminates: arithmetic and harmonic averages | the one microstructure whose effective behavior is a closed form, derived symbolically |
| Symbolic viscoelasticity | models with symbolic parameters, and symbolic Laplace-Carson inversion: the Burgers relaxation function derived rather than transcribed, and precisely where the symbolic route stops |
| Multiscale chaining: explicit and declarative, side by side | the two ways of chaining scales, the same answer, and the ForwardDiff pass that goes through both |