Rodin::Solid module

Constitutive laws, kinematics, and solid-mechanics integration.

\[ \mathbf{P}=\frac{\partial W}{\partial\mathbf{F}}. \]

KinematicState computes deformation measures for constitutive laws such as NeoHookean and HolzapfelOgden. InternalVirtualWork assembles residuals and consistent tangents, and stress fields such as CauchyStress support postprocessing. The module covers finite-strain elasticity and fiber-reinforced material models.

It is organized into four sub-layers:

Kinematics

KinematicState encapsulates all finite-strain kinematic quantities at a quadrature point. Set the displacement gradient with setDisplacementGradient(H) and query derived tensors:

GetterReturnsDefinition
getDisplacementGradient() $ \nabla\mathbf{u} $ Input gradient
getDeformationGradient() $ \mathbf{F} $ $ \mathbf{I} + \nabla\mathbf{u} $
getDeformationGradientInverse() $ \mathbf{F}^{-1} $ Inverse
getDeformationGradientInverseTranspose() $ \mathbf{F}^{-T} $ Inverse transpose
getRightCauchyGreenTensor() $ \mathbf{C} $ $ \mathbf{F}^T\mathbf{F} $
getLeftCauchyGreenTensor() $ \mathbf{b} $ $ \mathbf{F}\mathbf{F}^T $
getJacobian() $ J $ $ \det\mathbf{F} $
getLogJacobian() $ \ln J $ Natural log of Jacobian

Invariant classes compute derived quantities from the kinematic state:

  • IsotropicInvariants — $ I_1 = \operatorname{tr}\mathbf{C} $ , $ I_2 = \tfrac{1}{2}[\operatorname{tr}(\mathbf{C})^2 - \operatorname{tr}(\mathbf{C}^2)] $ , $ I_3 = \det\mathbf{C} = J^2 $
  • FiberInvariants — $ I_4 = \mathbf{a}_0 \cdot \mathbf{C}\mathbf{a}_0 $ , $ I_5 = \mathbf{a}_0 \cdot \mathbf{C}^2\mathbf{a}_0 $ (for anisotropic materials; constructed with a fiber direction vector)

Constitutive Point and Input Injection

ConstitutivePoint bundles a KinematicState with an optional Geometry::Point (for spatial location) and a tag-based auxiliary data store. Auxiliary data (fiber directions, activation values, etc.) is injected via typed tags:

cp.set<Solid::Tags::FiberDirection>(fiberVec);
auto& f = cp.get<Solid::Tags::FiberDirection>();
bool has = cp.has<Solid::Tags::Activation>();

The Input<Derived> CRTP base and InputFunction callable allow the user to inject auxiliary data at each quadrature point during assembly. Integrators accept input via setInput().

Constitutive Laws

Each law derives from HyperElasticLaw<Derived> (CRTP base) and provides:

  • A Cache struct for precomputed invariant data
  • setCache(cache, cp) — populate the cache from a ConstitutivePoint
  • getFirstPiolaKirchhoffStress(P, cache, cp) — $ \mathbf{P} = \partial W / \partial \mathbf{F} $
  • getMaterialTangent(dP, cache, cp, dF) — directional derivative $ D\mathbf{P}[\delta\mathbf{F}] $
  • getStrainEnergyDensity(cache, cp) — returns $ W(\mathbf{F}) $
LawConstructorEnergy density $ W $
HookeHooke(lambda, mu) $ \boldsymbol{\sigma} = \lambda(\operatorname{tr}\boldsymbol{\varepsilon})\mathbf{I} + 2\mu\boldsymbol{\varepsilon} $ (linear stress-strain; not hyperelastic)
NeoHookeanNeoHookean(lambda, mu) $ \frac{\mu}{2}(I_1 - d) - \mu\ln J + \frac{\lambda}{2}(\ln J)^2 $
SaintVenantKirchhoffSaintVenantKirchhoff(lambda, mu) $ \frac{\lambda}{2}(\operatorname{tr}\mathbf{E})^2 + \mu\,\mathbf{E}:\mathbf{E} $
MooneyRivlinMooneyRivlin(c1, c2, kappa) $ c_1(\bar{I}_1 - d) + c_2(\bar{I}_2 - d) + \frac{\kappa}{2}(J-1)^2 $

where $ \mathbf{E} = \tfrac{1}{2}(\mathbf{C} - \mathbf{I}) $ is the Green-Lagrange strain, $ \bar{I}_k = J^{-2k/d} I_k $ are modified invariants, and $ \kappa $ is the bulk modulus.

All Lamé-parameter constructors accept $ \lambda $ and $ \mu $ computed from Young's modulus $ E $ and Poisson's ratio $ \nu $ :

\[ \lambda = \frac{E\nu}{(1+\nu)(1-2\nu)}, \quad \mu = \frac{E}{2(1+\nu)} \]

Integrators

Both integrators use setDisplacement() to set the linearization point and setInput() for auxiliary data injection. Quadrature order is auto-selected (2× FE order) unless overridden with setQuadratureOrder().

IntegratorForm typeAssemblesMathematical expression
InternalForce<Law, FES>Linear (residual)Internal force vector $ R_i = \int_\Omega \mathbf{P} : \nabla\phi_i \, dX $
MaterialTangent<Law, Solution, FES>Bilinear (tangent)Tangent stiffness matrix $ K_{ij} = \int_\Omega D\mathbf{P}[\nabla\phi_j] : \nabla\phi_i \, dX $

Constructor signatures (CTAD-deduced):

Solid::InternalForce residual(law, v);       // (law, TestFunction)
residual.setDisplacement(u);                  // set linearization point

Solid::MaterialTangent tangent(law, du, v);  // (law, TrialFunction, TestFunction)
tangent.setDisplacement(u);                   // set linearization point

Derived Fields

Typical Usage

A quasi-static hyperelastic block under gravity using NeoHookean (from examples/Solid/BlockGravity.cpp):

#include <Rodin/Solid.h>
#include <Rodin/Solver/NewtonSolver.h>
#include <Rodin/Solver/SparseLU.h>

// Material from Young's modulus and Poisson's ratio
const Real E = 200.0, nu = 0.3;
const Real lambda = E * nu / ((1.0 + nu) * (1.0 - 2.0 * nu));
const Real mu     = E / (2.0 * (1.0 + nu));
Solid::NeoHookean law(lambda, mu);

P1 Vh(mesh, mesh.getSpaceDimension());  // vector P1 space
TrialFunction du(Vh);
TestFunction  v(Vh);
GridFunction  u(Vh);  // accumulated displacement

// Build Newton system: K δu = -F_int(u) + F_body
Solid::MaterialTangent tangent(law, du, v);
tangent.setDisplacement(u);

Solid::InternalForce residual(law, v);
residual.setDisplacement(u);

auto bodyForce = VectorFunction{ Zero(), RealFunction(-10.0) };

Problem newton(du, v);
newton = tangent
       + residual
       - Integral(bodyForce, v)
       + DirichletBC(du, VectorFunction{ Zero(), Zero() }).on(bottomBC);

SparseLU linearSolver(newton);
NewtonSolver solver(linearSolver);
solver.setMaxIterations(50)
      .setAbsoluteTolerance(1e-10)
      .setRelativeTolerance(1e-8);
solver.solve(u);

Namespaces

namespace Tags
Standard tag types for auxiliary constitutive data.

Classes

template<class PassiveLaw, class ActiveLaw = ActiveFiberLaw>
class ActiveContraction
Adds active fiber stress to a passive law.
class ActiveFiberLaw
Local active fiber contraction law.
class HolzapfelOgden
Compressible Holzapfel-Ogden law with one preferred direction.
class Hooke
Isotropic Hooke's law for linear elasticity.
template<class Derived>
class HyperElasticLaw
CRTP base class for hyperelastic constitutive laws.
class MooneyRivlin
Compressible Mooney-Rivlin hyperelastic law.
class NeoHookean
Compressible Neo-Hookean hyperelastic law.
class SaintVenantKirchhoff
Saint-Venant-Kirchhoff hyperelastic law.
class Yeoh
Compressible Yeoh hyperelastic law.
template<class LawDerived>
class CauchyStress
Computes the Cauchy stress from a constitutive law.
template<class LawDerived>
class FirstPiolaKirchhoffStress
Computes the first Piola-Kirchhoff stress from a constitutive law.
class GreenLagrangeStrain
Computes the Green-Lagrange strain tensor from a kinematic state.
template<class Derived>
class Input
CRTP base class for inputs.
template<class... Args>
class InternalVirtualWorkResidual
Internal virtual work residual integrator family.
See specializations
SpecializationDescription
LawDerived, TestFunctionType, DisplacementType
Full specialization
template <
  class LawDerived,
  class TestFunctionType,
  class DisplacementType>
class InternalVirtualWorkResidual<
  LawDerived,
  TestFunctionType,
  DisplacementType> final;
Momentum residual (pure displacement formulation).
LawDerived, TestFunctionType, DisplacementType, PressureType
Full specialization
template <
  class LawDerived,
  class TestFunctionType,
  class DisplacementType,
  class PressureType>
class InternalVirtualWorkResidual<
  LawDerived,
  TestFunctionType,
  DisplacementType,
  PressureType> final;
Momentum residual of the mixed u-p formulation. Bound to the displacement test function $ \mathbf{v} $.
template<class TestPressFunctionType, class DisplacementType>
class InternalVirtualWorkResidualP
Incompressibility constraint residual of the mixed u-p formulation. Bound to the pressure test function $ q $ .
template<class... Args>
class InternalVirtualWorkTangent
Internal virtual work tangent integrator family.
See specializations
SpecializationDescription
LawDerived, TrialFunctionType, TestFunctionType, DisplacementType
Full specialization
template <
  class LawDerived,
  class TrialFunctionType,
  class TestFunctionType,
  class DisplacementType>
class InternalVirtualWorkTangent<
  LawDerived,
  TrialFunctionType,
  TestFunctionType,
  DisplacementType> final;
Displacement tangent (pure displacement formulation).
LawDerived, TrialFunctionType, TestFunctionType, DisplacementType, PressureType
Full specialization
template <
  class LawDerived,
  class TrialFunctionType,
  class TestFunctionType,
  class DisplacementType,
  class PressureType>
class InternalVirtualWorkTangent<
  LawDerived,
  TrialFunctionType,
  TestFunctionType,
  DisplacementType,
  PressureType> final;
Displacement-displacement block $ K_{uu} $ of the mixed u-p formulation. Bound to the (u, v) pair.
class InternalVirtualWorkTangentUP
Displacement-pressure coupling block $ K_{up} $ . Bound to the (p, v) pair: columns are pressure DOFs, rows are displacement test DOFs.
See declaration
template<class TrialPressFunctionType, class TestFunctionType, class DisplacementType>
class InternalVirtualWorkTangentUP
class InternalVirtualWorkTangentPU
Pressure-displacement coupling block $ K_{pu} $ (linearized incompressibility constraint). Bound to the (u, q) pair: columns are displacement DOFs, rows are pressure test DOFs.
See declaration
template<class TrialFunctionType, class TestPressFunctionType, class DisplacementType>
class InternalVirtualWorkTangentPU
template<class Law, class State>
class InternalVirtualWork
Façade for the internal virtual work nonlinear form.
template<class TestFunctionType, class DisplacementType>
class FollowerPressureForce
Linear-form integrator: follower pressure residual $ +p \int (\mathbf{x}_{,\xi} \times \mathbf{x}_{,\eta}) \cdot \mathbf{w} $ . Add it with "+" to the Problem (it already carries the residual-convention sign of a pressure pushing along the outward normal).
template<class TrialFunctionType, class TestFunctionType, class DisplacementType>
class FollowerPressureTangent
Bilinear-form integrator: the EXACT load stiffness of the follower pressure, $ +p \int (\delta\mathbf{d}_{,\xi} \times \mathbf{x}_{,\eta} + \mathbf{x}_{,\xi} \times \delta\mathbf{d}_{,\eta}) \cdot \mathbf{w} $ . Add it with "+" alongside the material tangent. NONSYMMETRIC.
class IsotropicInvariants
Isotropic invariants of the right Cauchy-Green tensor.
class FiberInvariants
Fiber invariants for anisotropic hyperelasticity.
class KinematicState
Kinematic state for finite-strain continuum mechanics.
class ConstitutivePoint
Central data bundle for constitutive evaluation at a quadrature point.
class FiberKinematics
Preferred-direction kinematics at a constitutive point.
template<class Derived>
class Output
CRTP base class for outputs.

Typedefs

using InputFunction = std::function<void(ConstitutivePoint&)>
Type-erased callable for input injection into ConstitutivePoint.
template<class Law>
using OutputFunction = std::function<void(const ConstitutivePoint&, const Law&)>
Type-erased callable for extraction from a constitutive evaluation.

Functions

FollowerPressureForce
CTAD guide for the follower-pressure residual.
See declaration
template<class TestFunctionType, class DisplacementType>
FollowerPressureForce(const Real& pressure, const TestFunctionType& v, const DisplacementType& displacement) -> FollowerPressureForce< std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
FollowerPressureTangent
CTAD guide for the follower-pressure tangent.
See declaration
template<class TrialFunctionType, class TestFunctionType, class DisplacementType>
FollowerPressureTangent(const Real& pressure, const TrialFunctionType& u, const TestFunctionType& v, const DisplacementType& displacement) -> FollowerPressureTangent< std::decay_t< TrialFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
InternalVirtualWork
See declaration
template<class Law, class State>
InternalVirtualWork(const Law& law, const State& displacement) -> InternalVirtualWork< std::decay_t< Law >, std::decay_t< State > >
InternalVirtualWorkResidual
See declaration
template<class LawDerived, class TestFunctionType, class DisplacementType>
InternalVirtualWorkResidual(const LawDerived& law, const TestFunctionType& v, const DisplacementType& displacement) -> InternalVirtualWorkResidual< LawDerived, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
InternalVirtualWorkResidual
See declaration
template<class LawDerived, class TestFunctionType, class DisplacementType, class PressureType>
InternalVirtualWorkResidual(const LawDerived& law, const TestFunctionType& v, const DisplacementType& displacement, const PressureType& pressure) -> InternalVirtualWorkResidual< LawDerived, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType >, std::decay_t< PressureType > >
InternalVirtualWorkResidualP
See declaration
template<class TestPressFunctionType, class DisplacementType>
InternalVirtualWorkResidualP(const TestPressFunctionType& q, const DisplacementType& displacement) -> InternalVirtualWorkResidualP< std::decay_t< TestPressFunctionType >, std::decay_t< DisplacementType > >
InternalVirtualWorkTangent
See declaration
template<class LawDerived, class TrialFunctionType, class TestFunctionType, class DisplacementType>
InternalVirtualWorkTangent(const LawDerived& law, const TrialFunctionType& u, const TestFunctionType& v, const DisplacementType& displacement) -> InternalVirtualWorkTangent< LawDerived, std::decay_t< TrialFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
InternalVirtualWorkTangent
See declaration
template<class LawDerived, class TrialFunctionType, class TestFunctionType, class DisplacementType, class PressureType>
InternalVirtualWorkTangent(const LawDerived& law, const TrialFunctionType& u, const TestFunctionType& v, const DisplacementType& displacement, const PressureType& pressure) -> InternalVirtualWorkTangent< LawDerived, std::decay_t< TrialFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType >, std::decay_t< PressureType > >
InternalVirtualWorkTangentUP
See declaration
template<class TrialPressFunctionType, class TestFunctionType, class DisplacementType>
InternalVirtualWorkTangentUP(const TrialPressFunctionType& p, const TestFunctionType& v, const DisplacementType& displacement) -> InternalVirtualWorkTangentUP< std::decay_t< TrialPressFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
InternalVirtualWorkTangentPU
See declaration
template<class TrialFunctionType, class TestPressFunctionType, class DisplacementType>
InternalVirtualWorkTangentPU(const TrialFunctionType& u, const TestPressFunctionType& q, const DisplacementType& displacement) -> InternalVirtualWorkTangentPU< std::decay_t< TrialFunctionType >, std::decay_t< TestPressFunctionType >, std::decay_t< DisplacementType > >

Typedef documentation

using InputFunction = std::function<void(ConstitutivePoint&)>

Defined in Rodin/Solid/Local/Input.h

Type-erased callable for input injection into ConstitutivePoint.

template<class Law>
using OutputFunction = std::function<void(const ConstitutivePoint&, const Law&)>

Defined in Rodin/Solid/Local/Output.h

Type-erased callable for extraction from a constitutive evaluation.

Template parameters
Law The prepared constitutive law type.

Function documentation

FollowerPressureForce

Defined in Rodin/Solid/Integrators/FollowerPressure.h

See declaration
template<class TestFunctionType, class DisplacementType>
FollowerPressureForce(const Real& pressure, const TestFunctionType& v, const DisplacementType& displacement) -> FollowerPressureForce< std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >

CTAD guide for the follower-pressure residual.

Parameters
pressure Pressure applied on the surface.
v Test shape-function expression.
displacement Displacement field.

FollowerPressureTangent

Defined in Rodin/Solid/Integrators/FollowerPressure.h

See declaration
template<class TrialFunctionType, class TestFunctionType, class DisplacementType>
FollowerPressureTangent(const Real& pressure, const TrialFunctionType& u, const TestFunctionType& v, const DisplacementType& displacement) -> FollowerPressureTangent< std::decay_t< TrialFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >

CTAD guide for the follower-pressure tangent.

Parameters
pressure The applied pressure, captured by reference
u The trial displacement function
v The test displacement function
displacement The current displacement state

InternalVirtualWork

Defined in Rodin/Solid/Integrators/InternalVirtualWork.h

See declaration
template<class Law, class State>
InternalVirtualWork(const Law& law, const State& displacement) -> InternalVirtualWork< std::decay_t< Law >, std::decay_t< State > >
Parameters
law The constitutive law (stored by value)
displacement The current displacement (stored by reference)

CTAD deduction guide for InternalVirtualWork

InternalVirtualWorkResidual

Defined in Rodin/Solid/Integrators/InternalVirtualWorkResidual.h

See declaration
template<class LawDerived, class TestFunctionType, class DisplacementType>
InternalVirtualWorkResidual(const LawDerived& law, const TestFunctionType& v, const DisplacementType& displacement) -> InternalVirtualWorkResidual< LawDerived, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
Parameters
law The constitutive law
v The displacement test function
displacement The current displacement state

CTAD deduction guide for the displacement-only residual

InternalVirtualWorkResidual

Defined in Rodin/Solid/Integrators/InternalVirtualWorkResidual.h

See declaration
template<class LawDerived, class TestFunctionType, class DisplacementType, class PressureType>
InternalVirtualWorkResidual(const LawDerived& law, const TestFunctionType& v, const DisplacementType& displacement, const PressureType& pressure) -> InternalVirtualWorkResidual< LawDerived, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType >, std::decay_t< PressureType > >
Parameters
law The isochoric constitutive law
v The displacement test function
displacement The current displacement state
pressure The current pressure state

CTAD deduction guide for the mixed u-p momentum residual

InternalVirtualWorkResidualP

Defined in Rodin/Solid/Integrators/InternalVirtualWorkResidual.h

See declaration
template<class TestPressFunctionType, class DisplacementType>
InternalVirtualWorkResidualP(const TestPressFunctionType& q, const DisplacementType& displacement) -> InternalVirtualWorkResidualP< std::decay_t< TestPressFunctionType >, std::decay_t< DisplacementType > >
Parameters
q The pressure test function
displacement The current displacement state

CTAD deduction guide for the incompressibility constraint residual

InternalVirtualWorkTangent

Defined in Rodin/Solid/Integrators/InternalVirtualWorkTangent.h

See declaration
template<class LawDerived, class TrialFunctionType, class TestFunctionType, class DisplacementType>
InternalVirtualWorkTangent(const LawDerived& law, const TrialFunctionType& u, const TestFunctionType& v, const DisplacementType& displacement) -> InternalVirtualWorkTangent< LawDerived, std::decay_t< TrialFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
Parameters
law The constitutive law
u The trial displacement function
v The test displacement function
displacement The current displacement state

CTAD deduction guide for the displacement-only tangent

InternalVirtualWorkTangent

Defined in Rodin/Solid/Integrators/InternalVirtualWorkTangent.h

See declaration
template<class LawDerived, class TrialFunctionType, class TestFunctionType, class DisplacementType, class PressureType>
InternalVirtualWorkTangent(const LawDerived& law, const TrialFunctionType& u, const TestFunctionType& v, const DisplacementType& displacement, const PressureType& pressure) -> InternalVirtualWorkTangent< LawDerived, std::decay_t< TrialFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType >, std::decay_t< PressureType > >
Parameters
law The isochoric constitutive law
u The trial displacement function
v The test displacement function
displacement The current displacement state
pressure The current pressure state

CTAD deduction guide for the mixed u-p displacement block

InternalVirtualWorkTangentUP

Defined in Rodin/Solid/Integrators/InternalVirtualWorkTangent.h

See declaration
template<class TrialPressFunctionType, class TestFunctionType, class DisplacementType>
InternalVirtualWorkTangentUP(const TrialPressFunctionType& p, const TestFunctionType& v, const DisplacementType& displacement) -> InternalVirtualWorkTangentUP< std::decay_t< TrialPressFunctionType >, std::decay_t< TestFunctionType >, std::decay_t< DisplacementType > >
Parameters
p The trial pressure function
v The test displacement function
displacement The current displacement state

CTAD deduction guide for the K_up block

InternalVirtualWorkTangentPU

Defined in Rodin/Solid/Integrators/InternalVirtualWorkTangent.h

See declaration
template<class TrialFunctionType, class TestPressFunctionType, class DisplacementType>
InternalVirtualWorkTangentPU(const TrialFunctionType& u, const TestPressFunctionType& q, const DisplacementType& displacement) -> InternalVirtualWorkTangentPU< std::decay_t< TrialFunctionType >, std::decay_t< TestPressFunctionType >, std::decay_t< DisplacementType > >
Parameters
u The trial displacement function
q The test pressure function
displacement The current displacement state

CTAD deduction guide for the K_pu block