GitHub

API — Sensitivities

Public lenses and autodiff entry points provided by MeanFieldHom.Schemes. ForwardDiff is a strong dependency of MeanFieldHom 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

MeanFieldHom.Schemes.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, 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.

The get_param / set_param functions read and replace the designated scalar in a RVE. See also the convenience constructors amount, property, geometry, shape_param.

MeanFieldHom.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.

MeanFieldHom.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.

MeanFieldHom.Schemes.property — Function
property(phase::Symbol, property::Symbol, selector) -> PropertyParameter

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

MeanFieldHom.Schemes.geometry — Function
geometry(phase::Symbol, field::Symbol, index=nothing) -> GeometryParameter

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

MeanFieldHom.Schemes.shape_param — Function
shape_param(field::Symbol, index=nothing) -> DistributionShapeParameter

Helper. Equivalent to DistributionShapeParameter(field, index).

MeanFieldHom.Schemes.set_param — Function
set_param(rve, p::AbstractParameter, value) -> RVE

Return a new rve instance in which the scalar designated by lens p has been replaced by value. The element type of the affected fields (amounts, tensors, geometries) is promoted to absorb typeof(value) ; all other fields are preserved unchanged (no mutation of the original).

Autodiff entry points

MeanFieldHom.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.

MeanFieldHom.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.

MeanFieldHom.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.

MeanFieldHom.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.