"""Ready-made tests of a sample between rigid tools (see :mod:`morphogen.contact`): its
compression between two platens, on which it rubs and under which its own walls may close
on themselves (a foam, a lattice, a porous solid that densifies), and its indentation by a
sphere or a cone.
Both build a :class:`~morphogen.contact.problem.ContactProblem` of the mesh of the sample
with rigid obstacles, follow it in steps and give the curves that the tests measure: the
nominal stress against the nominal strain of a compression, the force against the depth
of an indentation with the modulus that it reads (Hertz, Sneddon; the slope of the
unloading: Oliver and Pharr 1992).
"""
from __future__ import annotations
import math
from dataclasses import dataclass, field
import numpy as np
from morphogen.contact.hertz import hertz_sphere, layer_correction, sneddon_cone
from morphogen.contact.problem import ContactProblem, ContactResult
from morphogen.contact.surfaces import Obstacle, Pair, Surface
from morphogen.mesh.tetra import TetMesh
#: The indenters of :func:`indentation`
INDENTERS = ("sphere", "cone")
def _plane_axes(axis: int) -> tuple[int, int]:
if axis not in (0, 1, 2):
raise ValueError("axis: 0, 1 or 2")
return tuple(a for a in range(3) if a != axis)
def _pins(mesh: TetMesh, axis: int) -> list[tuple]:
"""Prescribed displacements that hold a sample against the three rigid motions that
its platens leave it (two translations along them and the rotation about their
normal), on two nodes of its base: the one nearest the middle of the base (both
components along the platens) and the one furthest from it along the first of their
axes (the component along the second)."""
b, c = _plane_axes(axis)
x = mesh.nodes
height = float(mesh.size[axis])
base = np.flatnonzero(x[:, axis] <= x[:, axis].min() + 0.02 * height)
middle = x[base][:, [b, c]].mean(axis=0)
first = base[np.argmin(np.linalg.norm(x[base][:, [b, c]] - middle, axis=1))]
second = base[np.argmax(np.abs(x[base, b] - x[first, b]))]
if second == first or abs(x[second, b] - x[first, b]) < 1e-9 * height:
raise ValueError("the base of the sample is a point: nothing to hold it by")
return [(np.array([first]), [b, c], 0.0), (np.array([second]), c, 0.0)]
[docs]
@dataclass
class CompressionResult:
"""The compression of a sample between two platens. At each step: the nominal
``strain`` (the approach of the platens over the height of the sample: negative), the
``force`` that the sample exerts on the moving platen (positive), the nominal
``stress`` (minus this force over the section of the box of the sample: negative), the
``area`` in contact with the platens (steps x 2: the fixed one, the moving one;
reference area), the area of the walls of the sample in contact with themselves
(``self_area``, of one of the two sides) and the energy that friction dissipated
(``friction``). ``section`` and ``height``: those of the box of the sample.
``result``: the steps of the problem (:class:`~morphogen.contact.problem.
ContactResult`: reactions, works, the slave points at the end); ``problem``: the
problem (:meth:`~morphogen.contact.problem.ContactProblem.write` for its fields)."""
strain: np.ndarray
stress: np.ndarray
force: np.ndarray
area: np.ndarray
self_area: np.ndarray
friction: np.ndarray
section: float
height: float
result: ContactResult = field(repr=False)
problem: ContactProblem = field(repr=False)
@property
def modulus(self) -> float:
"""The apparent modulus of the first step: its stress over its strain."""
return float(self.stress[1] / self.strain[1])
[docs]
def tangent(self) -> np.ndarray:
"""The tangent modulus of each step: the change of the stress over that of the
strain (one value per step; stiffening as the walls close)."""
return np.diff(self.stress) / np.diff(self.strain)
[docs]
def rows(self) -> list[dict]:
"""One row per step: strain, stress, force, the areas in contact (with the fixed
platen, with the moving one, of the sample with itself) and the energy dissipated
by friction."""
return [
{
"strain": float(self.strain[k]),
"stress": float(self.stress[k]),
"force": float(self.force[k]),
"area_fixed": float(self.area[k, 0]),
"area_moving": float(self.area[k, 1]),
"self_area": float(self.self_area[k]),
"friction": float(self.friction[k]),
}
for k in range(len(self.strain))
]
[docs]
def compression(
mesh: TetMesh,
materials,
strain: float,
*,
axis: int = 2,
friction: float = 0.0,
self_contact: bool = True,
self_friction: float | None = None,
steps: int = 20,
kinematics: str = "finite",
fields: bool = False,
stiffness: float | None = None,
points: str = "gauss",
**options,
) -> CompressionResult:
"""Compress a sample between two rigid platens across ``axis``: the platens are the
planes of the two faces of the box of the ``mesh`` (that of the solid of a porous
sample: ``conforming_mesh(..., phases="solid")``), the lower one fixed, the upper one
brought down by ``-strain`` times the height of the box (``strain``: the nominal
strain, negative) in ``steps`` steps.
The free surface of the sample presses on the platens with Coulomb's ``friction``
(0: lubricated platens, the sample widens freely; with friction it barrels) and, with
``self_contact``, on itself with ``self_friction`` (by default that of the platens):
the walls of the pores that close, the struts of a lattice that meet. ``stiffness``:
the penalty of all these contacts (see :class:`~morphogen.contact.surfaces.Pair`);
``points``: their contact points, ``"gauss"`` or ``"nodes"`` (a sample that meets a
platen, or itself, by corners or edges); ``kinematics``: ``"finite"`` strains (the
default) or ``"small"`` ones; ``fields``: keep
the displacements of each step. The other ``options``: those of
:class:`~morphogen.contact.problem.ContactProblem` (``bulk``, ``augmentations``,
``tolerance``, ``neighbours``) and of its :meth:`run` (``tol``, ``max_newton``,
``max_cuts``).
Two nodes of the base hold the sample against the rigid motions along the platens
(the forces that they take are those that the platens would otherwise have to: none
for a sample that widens evenly)."""
if not (math.isfinite(strain) and -1.0 < strain < 0.0):
raise ValueError("compression: a nominal strain between -1 and 0 (the platens close)")
if steps < 1:
raise ValueError("compression: at least one step")
b, c = _plane_axes(axis)
skin = Surface.of(mesh)
if not skin.n_faces:
raise ValueError("compression: the mesh has no free surface")
normal = np.zeros(3)
normal[axis] = 1.0
height = float(mesh.size[axis])
section = float(mesh.size[b] * mesh.size[c])
contact = {"friction": friction, "stiffness": stiffness, "points": points}
fixed = Obstacle.plane(skin, tuple(mesh.lower), tuple(normal), name="fixed", **contact)
moving = Obstacle.plane(
skin, tuple(mesh.upper), tuple(-normal), name="moving",
motion=tuple(strain * height * normal), **contact,
) # fmt: skip
pairs = []
if self_contact:
rub = friction if self_friction is None else self_friction
pairs.append(Pair(skin, friction=rub, stiffness=stiffness, points=points))
build = {k: options.pop(k) for k in ("bulk", "augmentations", "tolerance", "neighbours")
if k in options} # fmt: skip
problem = ContactProblem(mesh, materials, pairs, [fixed, moving], kinematics=kinematics,
**build) # fmt: skip
res = problem.run(_pins(mesh, axis), steps=steps, fields=fields, **options)
first = len(pairs) # the contacts: the pair of the surface with itself, then the platens
force = res.forces[:, first + 1, axis]
return CompressionResult(
strain=strain * res.loads,
stress=-force / section,
force=force,
area=res.area[:, first : first + 2],
self_area=res.area[:, 0] if pairs else np.zeros(len(res.loads)),
friction=np.asarray(res.work["friction"]),
section=section,
height=height,
result=res,
problem=problem,
)
[docs]
@dataclass
class IndentationResult:
"""The indentation of a sample. At each step: the ``depth`` of the indenter under the
surface, the ``force`` on it, the ``area`` of the contact (the reference area of the
points that press), its ``radius`` (of the disc of the same area), the largest
``pressure`` and the ``hardness`` (the mean pressure, force over area); ``modulus``:
the reduced modulus ``E / (1 - ν²)`` of the homogeneous half-space that would take the
force at that depth (Hertz for a sphere, Sneddon for a cone: that of the sample while
the contact is small against it and against its heterogeneities). With an unloading:
``stiffness``, the slope of the force at its start, and ``unloading_modulus``, ``S
sqrt(π) / (2 sqrt(A))`` (Oliver and Pharr 1992: the area is that of the points, known
to a ring of them). ``radius_of_indenter`` (a sphere), ``thickness`` (of the sample
under its face) and ``base``: those of the test. ``result`` and ``problem``: as for a
compression."""
depth: np.ndarray
force: np.ndarray
area: np.ndarray
pressure: np.ndarray
modulus: np.ndarray
indenter: str
stiffness: float | None
unloading_modulus: float | None
radius_of_indenter: float | None
thickness: float
base: str
result: ContactResult = field(repr=False)
problem: ContactProblem = field(repr=False)
[docs]
def layer_modulus(self, poisson: float) -> np.ndarray:
"""The reduced modulus read from the force of a sphere with the base of the sample
taken into account: ``modulus`` over the factor by which a rigid base under a
layer of the thickness of the sample, of Poisson's ratio ``poisson``, multiplies
Hertz's force (:func:`~morphogen.contact.hertz.layer_correction`: bonded for a
fixed base, free to slide for a smooth one). A sample wide against its
thickness."""
if self.indenter != "sphere":
raise ValueError("layer_modulus: the correction is that of a sphere")
bonded = self.base == "fixed"
factor = np.array(
[
layer_correction(self.radius_of_indenter, h, self.thickness, poisson, bonded)
for h in self.depth
]
)
return self.modulus / factor
@property
def radius(self) -> np.ndarray:
return np.sqrt(self.area / math.pi)
@property
def hardness(self) -> np.ndarray:
with np.errstate(divide="ignore", invalid="ignore"):
return np.where(self.area > 0, self.force / self.area, 0.0)
[docs]
def rows(self) -> list[dict]:
"""One row per step: depth, force, area and radius of the contact, largest and
mean pressures, and the reduced modulus read from the force."""
radius, hardness = self.radius, self.hardness
return [
{
"depth": float(self.depth[k]),
"force": float(self.force[k]),
"area": float(self.area[k]),
"radius": float(radius[k]),
"pressure": float(self.pressure[k]),
"hardness": float(hardness[k]),
"modulus": float(self.modulus[k]),
}
for k in range(len(self.depth))
]
[docs]
def indentation(
mesh: TetMesh,
materials,
depth: float,
*,
indenter: str = "sphere",
radius: float | None = None,
half_angle: float = 70.3,
point=None,
axis: int = 2,
friction: float = 0.0,
steps: int = 10,
unload: bool = False,
base: str = "fixed",
kinematics: str = "finite",
fields: bool = False,
stiffness: float | None = None,
**options,
) -> IndentationResult:
"""Indent the upper face of a sample (across ``axis``) to a ``depth`` by a rigid
``indenter``: a ``"sphere"`` of ``radius``, or a ``"cone"`` of ``half_angle`` (degrees
from its axis; 70.3: the cone of the same area as the pyramids of Berkovich and
Vickers), at ``point`` of the face (two coordinates along it; by default its middle),
in ``steps`` steps, then out again in as many with ``unload``.
``base``: the lower face is ``"fixed"`` (glued) or ``"smooth"`` (it slides on its
support); the other faces are free. ``friction``: that of the indenter. ``stiffness``,
``kinematics``, ``fields`` and the other ``options``: as for :func:`compression`."""
if indenter not in INDENTERS:
raise ValueError(f"indentation: an indenter among {', '.join(INDENTERS)}")
if not (math.isfinite(depth) and depth > 0):
raise ValueError("indentation: a positive depth")
if indenter == "sphere" and not (radius is not None and radius > depth):
raise ValueError("indentation: the radius of the sphere, larger than the depth")
if base not in ("fixed", "smooth"):
raise ValueError("indentation: a base 'fixed' or 'smooth'")
if steps < 1:
raise ValueError("indentation: at least one step")
b, c = _plane_axes(axis)
x = mesh.nodes
height = float(mesh.size[axis])
top = float(mesh.upper[axis])
faces = Surface.of(mesh, lambda at: np.abs(at[:, axis] - top) < 1e-6 * height)
if not faces.n_faces:
raise ValueError("indentation: no face of the sample on the upper face of its box")
where = np.array(mesh.lower + 0.5 * mesh.size, dtype=float)
if point is not None:
where[[b, c]] = np.asarray(point, dtype=float).reshape(2)
where[axis] = top
normal = np.zeros(3)
normal[axis] = 1.0
def motion(t, down=-depth * normal):
return (t if t <= 1.0 else 2.0 - t) * down
contact = {"friction": friction, "stiffness": stiffness, "motion": motion}
if indenter == "sphere":
tool = Obstacle.sphere(faces, tuple(where + radius * normal), radius, **contact)
else:
tool = Obstacle.cone(faces, tuple(where), tuple(normal), half_angle, **contact)
under = np.flatnonzero(x[:, axis] < float(mesh.lower[axis]) + 1e-6 * height)
if not under.size:
raise ValueError("indentation: no node of the sample on the lower face of its box")
if base == "fixed":
prescribed = [(under, [0, 1, 2], 0.0)]
else:
prescribed = [(under, axis, 0.0), *_pins(mesh, axis)]
build = {k: options.pop(k) for k in ("bulk", "augmentations", "tolerance", "neighbours")
if k in options} # fmt: skip
problem = ContactProblem(mesh, materials, obstacles=[tool], kinematics=kinematics, **build)
load, count = (2.0, 2 * steps) if unload else (1.0, steps)
res = problem.run(prescribed, load=load, steps=count, fields=fields, **options)
t = res.loads
sunk = depth * np.where(t <= 1.0, t, 2.0 - t)
force = res.forces[:, 0, axis] # the sample pushes the indenter up
unit = np.array(
[
0.0 if h <= 0 else (
hertz_sphere(radius, 1.0, approach=h)["force"] if indenter == "sphere"
else sneddon_cone(half_angle, 1.0, h)["force"]
)
for h in sunk
]
) # fmt: skip
with np.errstate(divide="ignore", invalid="ignore"):
modulus = np.where(unit > 0, force / unit, 0.0)
slope = reduced = None
if unload:
peak = int(np.argmin(np.abs(t - 1.0)))
if peak + 1 < len(t) and sunk[peak] > sunk[peak + 1]:
slope = float((force[peak] - force[peak + 1]) / (sunk[peak] - sunk[peak + 1]))
if res.area[peak, 0] > 0:
reduced = slope * math.sqrt(math.pi) / (2.0 * math.sqrt(res.area[peak, 0]))
return IndentationResult(
depth=sunk,
force=force,
area=res.area[:, 0],
pressure=res.pressure[:, 0],
modulus=modulus,
indenter=indenter,
stiffness=slope,
unloading_modulus=reduced,
radius_of_indenter=float(radius) if indenter == "sphere" else None,
thickness=height,
base=base,
result=res,
problem=problem,
)