API — Sensitivities

Public lenses and autodiff entry points provided by MeanFieldHomogenization.Schemes. ForwardDiff is a strong dependency of MeanFieldHomogenization since v0.7.0 — the four derivative / gradient / jacobian / sensitivity functions are available out of the box, and the built-in SelfConsistent Newton-Raphson solver (NewtonDefault) uses the same machinery internally.

Lenses

MeanFieldHomogenization.Core.AbstractParameter Type

AbstractParameter

Supertype of parameter lenses. Concrete subtypes designate a single scalar input of a homogenization computation:

• AmountParameter — volume fraction or crack density of a phase.

• PropertyParameter — a scalar coefficient of a property tensor (:C, :K, …) of a phase or a layer, designated either by a named selector (:bulk, :shear, …) or by a positional index.

• GeometryParameter — a scalar geometry field of a phase (semi-axis of an ellipsoid, radius of a layer, …).

• DistributionShapeParameter — a scalar field of the PCW / Maxwell distribution shape.

• ThicknessParameter — the thickness of one layer of a laminate.

• InterfaceParameter — a compliance or surface modulus of one imperfect interface of a laminate.

• NestedParameter — a lens reaching into a declaratively nested cell, so that a multiscale chain differentiates end to end.

get_param / set_param read and replace the designated scalar in a cell. See also the convenience constructors amount, property, geometry, shape_param, thickness, interface_param and nested.

MeanFieldHomogenization.Schemes.AmountParameter Type

AmountParameter(phase::Symbol)

Lens on the amount (volume fraction or crack density) of phase phase. Prefer the helper amount.

MeanFieldHomogenization.Schemes.PropertyParameter Type

PropertyParameter(phase, property, selector)

Lens on a scalar coefficient of a property tensor :

• phase::Symbol — phase name (:M for the matrix by default, or any inclusion phase).

• property::Symbol — property key in the phase (:C, :K, …).

• selector::Union{Symbol,Int} — coefficient selector :

  • Symbol for canonical names (:bulk / :shear for TensISO{4,3} ; :scalar for TensISO{2} ; :ℓ₁..:ℓ₆ for TensTI{4} ; :transverse / :axial for TensTI{2}),

  • Int for the positional index into get_data(tensor) (universal fallback).

Prefer the helper property.

MeanFieldHomogenization.Schemes.GeometryParameter Type

GeometryParameter(phase, field, index = nothing)

Lens on a scalar geometry field of a phase. For an NTuple field (e.g. semi_axes), index selects one element of the tuple ; otherwise leave index = nothing.

Prefer the helper geometry.

MeanFieldHomogenization.Schemes.DistributionShapeParameter Type

DistributionShapeParameter(field, index = nothing)

Lens on a scalar field of the (Maxwell / PCW) distribution shape. Prefer the helper shape_param.

MeanFieldHomogenization.Schemes.amount Function

amount(phase::Symbol) -> AmountParameter

Helper. Equivalent to AmountParameter(phase).

MeanFieldHomogenization.Schemes.property Function

property(phase::Symbol, property::Symbol, selector) -> PropertyParameter

Helper. Equivalent to PropertyParameter(phase, property, selector).

MeanFieldHomogenization.Schemes.geometry Function

geometry(phase::Symbol, field::Symbol, index=nothing) -> GeometryParameter

Helper. Equivalent to GeometryParameter(phase, field, index).

MeanFieldHomogenization.Schemes.shape_param Function

shape_param(field::Symbol, index=nothing) -> DistributionShapeParameter

Helper. Equivalent to DistributionShapeParameter(field, index).

MeanFieldHomogenization.Core.get_param Function

get_param(cell, p::AbstractParameter) -> Number

Read the scalar designated by lens p in cell.

MeanFieldHomogenization.Core.set_param Function

set_param(cell, p::AbstractParameter, value)

Return a new cell in which the scalar designated by lens p has been replaced by value. The element type of the affected fields is promoted to absorb typeof(value); every other field is preserved, and the original is never mutated.

Autodiff entry points

MeanFieldHomogenization.Schemes.derivative Function

derivative(rve, scheme, param::AbstractParameter;
           output = :C, indexer = identity, kw...) -> Number | AbstractTens

Scalar derivative of homogenize(rve, scheme; property=output) with respect to the parameter selected by the lens param.

indexer is a function that extracts a scalar from the effective tensor (for example C -> get_data(C)[1] / 3 for the bulk modulus). Without an indexer, the derivative of the full tensor is returned — this is valid as long as ForwardDiff can propagate through the result (typically when the output is itself a structured object whose components ForwardDiff handles natively, via the _data Dual fields).

Extra kw... (e.g. Chunk, Tag) are forwarded to ForwardDiff.

The method is only available with using ForwardDiff; calling it without the extension loaded raises an explicit error pointing at the extension.

See also gradient, jacobian, sensitivity.

MeanFieldHomogenization.Schemes.gradient Function

gradient(rve, scheme, params::AbstractVector{<:AbstractParameter};
         output = :C, indexer, kw...) -> Vector

Gradient of a scalar functional (extracted via indexer) of the effective tensor returned by homogenize(rve, scheme; property=output), with respect to the vector of lenses params.

Implementation: ForwardDiff.gradient with automatic chunking (ForwardDiff.Chunk(length(params)) via the standard pickchunksize rule).

Without using ForwardDiff: error.

MeanFieldHomogenization.Schemes.jacobian Function

jacobian(rve, scheme, params::AbstractVector{<:AbstractParameter};
         output = :C, indexer = identity, kw...) -> Array

Jacobian (returned as a flat array length(output_flat) × length(params)) of homogenize(rve, scheme; property=output) with respect to the vector of lenses params.

indexer can be used to reduce the output to a sub-tensor before flattening. Without an indexer, the full effective tensor is flattened via get_array then vec.

Without using ForwardDiff: error.

MeanFieldHomogenization.Schemes.sensitivity Function

sensitivity(f, x₀; kind = :auto, kw...)

Generic ForwardDiff wrapper. f(x) is a user-supplied closure that builds or perturbs an RVE, runs homogenize, and returns a scalar (or a tensor).

kind:

• :derivative — scalar x₀, scalar output; returns f'(x₀).

• :gradient — vector x₀, scalar output; returns ∇f(x₀).

• :jacobian — vector x₀, tensor output; returns the flattened Jacobian.

• :auto (default) — pick one of the above from the types of x₀ and f(x₀).

This entry point covers cases the AbstractParameter lenses cannot express (compound parametrizations, user-defined inclusion types without an exposed scalar field, etc.).

Without using ForwardDiff: error.