Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -194,6 +194,13 @@ SP3_add_python_package(
Sofa/constants
)

SP3_add_python_package(
SOURCE_DIRECTORY
${CMAKE_CURRENT_SOURCE_DIR}/materials
TARGET_DIRECTORY
materials
)

## This is only to warn users that splib is now relocated in its own repository
# it just contains a __init__.py rising an exception indicating to where to find the plugin.
# If splib is available, then splib/__init__.py will be overriden by the one from the real splib.
Expand Down
63 changes: 63 additions & 0 deletions examples/materials_beam.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
from materials import Material

requiredPlugins = ([
"Sofa.Component.Constraint.Projective",
"Sofa.Component.Engine.Select",
"Sofa.Component.IntegrationScheme.Backward",
"Sofa.Component.LinearSolver.Direct",
"Sofa.Component.LinearSystem",
"Sofa.Component.Mass",
"Sofa.Component.SolidMechanics.FEM.Elastic",
"Sofa.Component.SolidMechanics.FEM.HyperElastic",
"Sofa.Component.StateContainer",
"Sofa.Component.Topology.Container.Dynamic",
"Sofa.Component.Topology.Container.Grid",
"Sofa.Component.Visual",
])


def createScene(root):
root.gravity = [0, 0, 0]
root.dt = 0.01

with root.addChild("plugins") as plugins:
plugins.addObject("RequiredPlugin", pluginName=requiredPlugins)

root.addObject("DefaultAnimationLoop")
root.addObject("VisualStyle", displayFlags="showVisualModels showBehaviorModels")

# One row per material along y, one column per model along z
for row, material in enumerate(("Dragon Skin 30", "Ecoflex 00-30")):
y = -0.06 * row
key = material.replace(" ", "").replace("-", "")
root.addObject("Visual3DText", name=f"label{key}", text=material, position=[0, y + 0.02, -0.04], scale=0.004)

for column, model in enumerate(("LinearElastic", "NeoHookean", "MooneyRivlin", "Ogden")):
z = 0.03 * column
if row == 0:
root.addObject("Visual3DText", name=f"label{model}", text=model, position=[0, 0.03, z + 0.005], scale=0.004)

with root.addChild(f"Beam{key}{model}") as beam:
beam.addObject("EulerImplicitIntegrationScheme", rayleighStiffness=0.1, rayleighMass=0.1)
beam.addObject("ConstantSparsityPatternSystem", template="CompressedRowSparseMatrixd")
beam.addObject("EigenSparseLU", template="CompressedRowSparseMatrixd")
beam.addObject("RegularGridTopology", name="grid", nx=9, ny=3, nz=3, min=[0, y, z], max=[0.1, y + 0.01, z + 0.01])
beam.addObject("MechanicalObject", template="Vec3")
beam.addObject("NodalMassDensity", property=1000)
beam.addObject("FEMMass", template="Vec3,Hexahedron")
beam.addObject("BoxROI", name="clampedEnd", box=[-0.0001, -1, -1, 0.0001, 1, 1])
beam.addObject("FixedProjectiveConstraint", indices="@clampedEnd.indices")
forceFieldData = {"symmetrizeTangent": False} if model == "LinearElastic" else None
prefab = Material(parent=beam, material=material, model=model, template="Vec3,Hexahedron", forceFieldData=forceFieldData)

stressEvaluator = prefab.forcefield if model == "LinearElastic" else prefab.constitutiveModel
beam.addObject("VonMisesStress", template="Vec3,Hexahedron", topology="@grid", stressEvaluator=stressEvaluator.getLinkPath(),
colorMap="green yellow orange red purple #221C35")

# Downward traction, in Pa, integrated over the quads of the free end face
beam.addObject("BoxROI", name="freeEnd", box=[0.0999, -1, -1, 0.1001, 1, 1], quads="@grid.quads")
with beam.addChild("Traction") as freeEnd:
freeEnd.addObject("QuadSetTopologyContainer", name="topology", quads="@../freeEnd.quadsInROI")
freeEnd.addObject("NodalSourceDensity", name="density", template="Vec3", property=[[0, -750, 0]])
freeEnd.addObject("VectorSourceTerm", name="source", template="Vec3,Quad", sourceDensity="@density")
freeEnd.addObject("FEMSourceTermIntegrator", template="Vec3,Quad", constantSources="@source")
1 change: 1 addition & 0 deletions materials/__init__.py
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
from .prefab import Material
159 changes: 159 additions & 0 deletions materials/library.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,159 @@
"""Constitutive model parameters for soft robotics materials.

Each material documents the strain energy expressions used in its reference and converts the reference's parameters
to those of SOFA's models.

Nomenclature:
E: Young's modulus (Pa)
μ: small-strain shear modulus (Pa)
ν: Poisson's ratio
K: bulk modulus (Pa)
"""

from Sofa.Units.Definitions import DimensionLess, Pa

from .models import (
LinearElasticMaterial,
MooneyRivlinMaterial,
NeoHookeanMaterial,
OgdenMaterial,
YeohMaterial,
)


class DragonSkin20:
"""L. Marechal, P. Balland, L. Lindenroth, F. Petrou, C. Kontovounisios and F. Bello, "Toward a Common Framework and
Database of Materials for Soft Robotics," Soft Robotics, 2020, doi: 10.1089/soro.2019.0115.

Neo-Hookean: W = μ(I₁ − 3)
Mooney-Rivlin: W = C10(I₁ − 3) + C01(I₂ − 3) + C20(I₁ − 3)²
Yeoh: W = Σ C_i(I₁ − 3)^i
Ogden: W = Σ μ_p/α_p (λ₁^α_p + λ₂^α_p + λ₃^α_p − 3)
"""

name = "Dragon Skin 20"
nu = 0.49 * DimensionLess
LinearElastic = LinearElasticMaterial(E=4e5 * Pa)
MooneyRivlin = MooneyRivlinMaterial(C10=2.47e5 * Pa, C01=-3.74e5 * Pa, C20=38.8 * Pa)
NeoHookean = NeoHookeanMaterial(mu=2 * 2.07047e5 * Pa)
Ogden = OgdenMaterial(mu_p=(3.478 * -9.534e5 * Pa, 3.181 * -1.4515e6 * Pa, 3.339 * 2.4085e6 * Pa), alpha_p=(3.478 * DimensionLess, 3.181 * DimensionLess, 3.339 * DimensionLess))
Yeoh = YeohMaterial(C1=1e5 * Pa, C2=1.69e5 * Pa, C3=266 * Pa)


class DragonSkin30:
"""L. Marechal, P. Balland, L. Lindenroth, F. Petrou, C. Kontovounisios and F. Bello, "Toward a Common Framework and
Database of Materials for Soft Robotics," Soft Robotics, 2020, doi: 10.1089/soro.2019.0115.

Neo-Hookean: W = μ(I₁ − 3)
Mooney-Rivlin: W = C10(I₁ − 3) + C01(I₂ − 3) + C20(I₁ − 3)²
Yeoh: W = Σ C_i(I₁ − 3)^i
Ogden: W = Σ μ_p/α_p (λ₁^α_p + λ₂^α_p + λ₃^α_p − 3)
"""

name = "Dragon Skin 30"
nu = 0.49 * DimensionLess
LinearElastic = LinearElasticMaterial(E=4e5 * Pa)
MooneyRivlin = MooneyRivlinMaterial(C10=2.47e5 * Pa, C01=-3.30e5 * Pa, C20=209 * Pa)
NeoHookean = NeoHookeanMaterial(mu=2 * 2.4203e5 * Pa)
Ogden = OgdenMaterial(mu_p=(3.417 * 3.816e4 * Pa, 3.417 * 2.524e4 * Pa, 3.417 * 4.456e4 * Pa), alpha_p=(3.417 * DimensionLess, 3.417 * DimensionLess, 3.417 * DimensionLess))
Yeoh = YeohMaterial(C1=1e5 * Pa, C2=1.19e5 * Pa, C3=604 * Pa)


class Ecoflex0010:
"""L. Marechal, P. Balland, L. Lindenroth, F. Petrou, C. Kontovounisios and F. Bello, "Toward a Common Framework and
Database of Materials for Soft Robotics," Soft Robotics, 2020, doi: 10.1089/soro.2019.0115.

Neo-Hookean: W = μ(I₁ − 3)
Mooney-Rivlin: W = C10(I₁ − 3) + C01(I₂ − 3) + C20(I₁ − 3)²
Yeoh: W = Σ C_i(I₁ − 3)^i
Ogden: W = Σ μ_p/α_p (λ₁^α_p + λ₂^α_p + λ₃^α_p − 3)
"""

name = "Ecoflex 00-10"
nu = 0.49 * DimensionLess
LinearElastic = LinearElasticMaterial(E=4e4 * Pa)
MooneyRivlin = MooneyRivlinMaterial(C10=2.18e4 * Pa, C01=-7.22e4 * Pa, C20=12.6 * Pa)
NeoHookean = NeoHookeanMaterial(mu=2 * 2.264e4 * Pa)
Ogden = OgdenMaterial(mu_p=(2.858 * 7.363e5 * Pa, 2.604 * 8.074e5 * Pa, 2.740 * -1.526e6 * Pa), alpha_p=(2.858 * DimensionLess, 2.604 * DimensionLess, 2.740 * DimensionLess))
Yeoh = YeohMaterial(C1=1e3 * Pa, C2=1.31e4 * Pa, C3=20.56 * Pa)


class Ecoflex0030:
"""L. Marechal, P. Balland, L. Lindenroth, F. Petrou, C. Kontovounisios and F. Bello, "Toward a Common Framework and
Database of Materials for Soft Robotics," Soft Robotics, 2020, doi: 10.1089/soro.2019.0115.

Neo-Hookean: W = μ(I₁ − 3)
Mooney-Rivlin: W = C10(I₁ − 3) + C01(I₂ − 3) + C20(I₁ − 3)²
Yeoh: W = Σ C_i(I₁ − 3)^i
Ogden: W = Σ μ_p/α_p (λ₁^α_p + λ₂^α_p + λ₃^α_p − 3)
"""

name = "Ecoflex 00-30"
nu = 0.49 * DimensionLess
LinearElastic = LinearElasticMaterial(E=1e5 * Pa)
MooneyRivlin = MooneyRivlinMaterial(C10=1.8e4 * Pa, C01=-4.69e4 * Pa, C20=43.4 * Pa)
NeoHookean = NeoHookeanMaterial(mu=2 * 3.245e4 * Pa)
Ogden = OgdenMaterial(mu_p=(3.310 * -3.22e5 * Pa, 3.115 * 1.9e5 * Pa, 3.468 * 1.45e5 * Pa), alpha_p=(3.310 * DimensionLess, 3.115 * DimensionLess, 3.468 * DimensionLess))
Yeoh = YeohMaterial(C1=1e5 * Pa, C2=1.2e4 * Pa, C3=49.6 * Pa)


class Pebax2533:
name = "Pebax 2533"
nu = 0.4 * DimensionLess
LinearElastic = LinearElasticMaterial(E=1.2e7 * Pa)


class Pebax4033:
name = "Pebax 4033"
nu = 0.4 * DimensionLess
LinearElastic = LinearElasticMaterial(E=7.3e7 * Pa)


class Pebax6333:
name = "Pebax 6333"
nu = 0.4 * DimensionLess
LinearElastic = LinearElasticMaterial(E=3e8 * Pa)


class Pebax7233:
name = "Pebax 7233"
nu = 0.4 * DimensionLess
LinearElastic = LinearElasticMaterial(E=5.1e8 * Pa)


class PLA:
"""A. Ouyoucef, Q. Peyron, G. Zheng and F. Boyer, "Modeling, analysis and design of an extensible planar parallel
tendon actuated continuum robot," 2025 IEEE 8th International Conference on Soft Robotics (RoboSoft), 2025,
doi: 10.1109/RoboSoft63089.2025.11020851.
"""

name = "PLA"
nu = 0.3 * DimensionLess
LinearElastic = LinearElasticMaterial(E=3e9 * Pa)


class TPU:
name = "TPU"
nu = 0.45 * DimensionLess
LinearElastic = LinearElasticMaterial(E=1e8 * Pa)


MATERIALS = {material.name: material for material in (
DragonSkin20,
DragonSkin30,
Ecoflex0010,
Ecoflex0030,
Pebax2533,
Pebax4033,
Pebax6333,
Pebax7233,
PLA,
TPU,
)}


def get_material(name):
material = MATERIALS.get(name)
if material is None:
raise ValueError(f"Unknown material '{name}'. Available materials: {', '.join(MATERIALS)}")
return material
73 changes: 73 additions & 0 deletions materials/models.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
"""Constitutive models for soft robotics materials.

Each model documents the strain energy expression SOFA uses.

Nomenclature:
E: Young's modulus (Pa)
μ: small-strain shear modulus (Pa)
ν: Poisson's ratio
K: bulk modulus (Pa)
"""

from typing import NamedTuple

from Sofa.Units.Core import DimensionnedValue
from Sofa.Units.Definitions import DimensionLess, Pa
from Sofa.Units.UnitSystem import MechanicalUnitSystem


SI = MechanicalUnitSystem()


def K(mu, nu, spatial_dimension):
"""Bulk modulus of an isotropic material, K = 2μ(1 + (d − 2)ν) / (d(1 − 2ν)), where d is the spatial dimension."""
return 2 * mu * (1 + (spatial_dimension - 2) * nu) / (spatial_dimension * (1 - 2 * nu))


class LinearElasticMaterial(NamedTuple):
"""W = μ ε:ε + λ/2 (tr ε)², where ε is the small strain in the element's rotated frame and λ is Lamé's first parameter"""
E: DimensionnedValue

def to_sofa_data(self, nu, spatial_dimension):
return {"youngModulus": self.E, "poissonRatio": nu * DimensionLess}


class MooneyRivlinMaterial(NamedTuple):
"""W = C10(Ī₁ − 3) + C01(Ī₂ − 3) + K/2 (ln J)²"""
C10: DimensionnedValue
C01: DimensionnedValue
C20: DimensionnedValue # not in SOFA's energy

def to_sofa_data(self, nu, spatial_dimension):
# In 2D, Ī₂ is constant. C01 does not contribute.
mu = 2 * (SI(self.C10) + SI(self.C01)) * Pa if spatial_dimension == 3 else 2 * self.C10
return {"mu10": self.C10, "mu01": self.C01, "bulkModulus": K(mu, nu, spatial_dimension)}


class NeoHookeanMaterial(NamedTuple):
"""W = μ/2 (I₁ − 3) − μ ln J + λ/2 (ln J)², where λ is Lamé's first parameter"""
mu: DimensionnedValue

def to_sofa_data(self, nu, spatial_dimension):
return {"youngModulus": 2 * self.mu * (1 + nu), "poissonRatio": nu * DimensionLess}


class OgdenMaterial(NamedTuple):
"""W = Σ μ_p/α_p² (λ̄₁^α_p + λ̄₂^α_p + λ̄₃^α_p − 3) + K/2 (ln J)²"""
mu_p: tuple[DimensionnedValue, ...]
alpha_p: tuple[DimensionnedValue, ...]

def to_sofa_data(self, nu, spatial_dimension):
mu = sum(SI(mu_p) for mu_p in self.mu_p) / 2 * Pa
return {"mu": list(self.mu_p), "alpha": list(self.alpha_p), "kappa": K(mu, nu, spatial_dimension)}


# TODO: SOFA has no Yeoh component yet
class YeohMaterial(NamedTuple):
"""W = Σ C_i(Ī₁ − 3)^i + K/2 (ln J)²"""
C1: DimensionnedValue
C2: DimensionnedValue
C3: DimensionnedValue

def to_sofa_data(self, nu, spatial_dimension):
return {"C1": self.C1, "C2": self.C2, "C3": self.C3, "bulkModulus": K(2 * self.C1, nu, spatial_dimension)}
59 changes: 59 additions & 0 deletions materials/prefab.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
import Sofa
from Sofa.Units import Definitions
from Sofa.Units.UnitSystem import MechanicalUnitSystem

from . import library, models


class Material(Sofa.Prefab):
prefabParameters = (
{"name": "material", "type": "string", "help": "Name of the material", "default": ""},
{"name": "model", "type": "string", "help": "Constitutive model of the material", "default": "LinearElastic"},
{"name": "poissonRatio", "type": "double", "help": "Poisson's ratio, defaults to the material's"},
{"name": "template", "type": "string", "help": "Template of the force field", "default": "Vec3,Tetrahedron"},
{"name": "units", "type": "string", "help": "Time, length and mass units of the scene", "default": "s m kg"},
)

def __init__(self, *args, forceFieldData=None, **kwargs):
"""forceFieldData: Data of the force field to set"""
if "poissonRatio" not in kwargs:
kwargs["poissonRatio"] = models.SI(library.get_material(kwargs.get("material", "")).nu)
super().__init__(*args, **kwargs)

for name, value in (forceFieldData or {}).items():
self.forcefield.findData(name).value = value

def init(self):
material = library.get_material(self.material.value)
constitutive_model = getattr(material, self.model.value, None)
if constitutive_model is None:
raise ValueError(f"{self.model.value} has not been implemented for {material.name}")

state_template = self.template.value.split(",")[0]
spatial_dimension = int(state_template[3])

time, length, mass = (getattr(Definitions, symbol) for symbol in self.units.value.split())
units = MechanicalUnitSystem(time, length, mass)

sofa_data = {}
for name, value in constitutive_model.to_sofa_data(self.poissonRatio.value, spatial_dimension).items():
sofa_data[name] = units(value)

if isinstance(constitutive_model, models.LinearElasticMaterial):
self.addObject("CorotationalFEMForceField"
, name="forcefield"
, template=self.template.value
, **sofa_data
)
return

self.addObject(type(constitutive_model).__name__
, name="constitutiveModel"
, template=state_template
, **sofa_data
)
self.addObject("HyperelasticityFEMForceField"
, name="forcefield"
, template=self.template.value
, material="@constitutiveModel"
)
Loading