PiecewiseElasticity

PiecewiseElasticity is an external SOFA plugin for tetrahedral continuum models with a strain-dependent Young's modulus. It provides TetrahedronFEMForceFieldPWE, a force field derived from SOFA's TetrahedronFEMForceField.

Instead of assigning one constant stiffness to the whole simulation, the component selects Young's modulus from user-defined strain intervals. This is a practical way to approximate nonlinear or asymmetric stress-strain behavior while retaining a tetrahedral FEM model.

The plugin is a general adaptive-material component. TPMS/IWP lattices are used in the included example because their homogenized response may differ in tension and compression; the plugin is not a lattice-geometry generator.

For a detailed technical treatment of the strain measurement, piecewise and smoothed modulus laws, homogenization motivation, example configurations, and tested SOFA workflow, see the included technical report.

Tension simulation	Compression simulation

Features

• Strain-dependent, piecewise Young's modulus for tetrahedral FEM models.
• Any number of strictly increasing strain thresholds.
• Optional linear smoothing near positive and negative thresholds.
• A sensor--actuator measurement direction that determines the strain used for selection.
• A reproducible tension/compression example, result CSV files, plots, and demonstration videos.

Requirements

• SOFA v24.06.00 (the version used to test this plugin).
• A Linux environment satisfying the dependencies of the selected SOFA release. For SOFA v24.06.00, the release notes list libopengl0; Python scenes or dependent plugins also require Python 3.10 and the packages required by SofaPython3.
• CMake 3.22 or later and a C++20-capable compiler.
• Ninja, when using the commands below.

The included Python example uses SofaPython3 and the SOFA plugins listed in examples/environment.py.

Installation and build

1. Prepare SOFA and its dependencies

Build or install SOFA v24.06.00 and satisfy its Linux dependencies before configuring this plugin. The release notes for this tested SOFA version list libopengl0; Python scenes or dependent plugins require Python 3.10 and the Python packages required by SofaPython3.

2. Register the external plugin

Place this repository in an external-plugin repository, then create the external repository's CMakeLists.txt file:

/path/to/sofa/ext_plugin_repo/CMakeLists.txt

Add:

cmake_minimum_required(VERSION 3.22)

find_package(SofaFramework REQUIRED)

sofa_add_subdirectory(plugin PiecewiseElasticity PiecewiseElasticity)

3. Configure with CMake-GUI

Open CMake-GUI from the SOFA build directory:

cd /path/to/sofa/build
cmake-gui

In CMake-GUI, set SOFA_EXTERNAL_DIRECTORIES to:

/path/to/sofa/ext_plugin_repo

Then:

1. Click Configure.
2. Enable PLUGIN_PIECEWISEELASTICITY.
3. Click Configure again.
4. Click Generate.
5. Close CMake-GUI.

4. Build

Compile SOFA and the external plugin:

cd /path/to/sofa/build
ninja

For later plugin-only builds:

cd /path/to/sofa/build
ninja PiecewiseElasticity

Quick start

Load the plugin before adding the component:

rootNode.addObject('RequiredPlugin', pluginName='PiecewiseElasticity')

node.addObject(
    'TetrahedronFEMForceFieldPWE',
    template='Vec3d',
    name='FEM',
    method='large',
    poissonRatio=0.45,
    youngModulus=6,
    useVariableYoungModuli=True,
    VariableYoungModuli=[6, 24],
    ThresholdStrain=[0],
    SensorPoint=[-25, 25, 0],
    ActuatorPoint=[-22, 25, 0],
    decayTime=0.0,
    smoothness=0.0,
)

The example scene is ready to run with the smoothed multi-threshold configuration:

cd /path/to/sofa/build
./bin/runSofa /path/to/PiecewiseElasticity/examples/environment.py

Test results and graphs

The repository includes a complete tension/compression test workflow: mesh files, the SOFA scene, controller, sample CSV results, graphs.py, static plots, and animated demonstrations. Use the supplied example to test a configuration, then run both loading cases before generating a plot:

tension = 0  # compression
tension = 1  # tension

Create the optional plotting environment once when the required packages are unavailable:

python3 -m venv /path/to/graph_venv
source /path/to/graph_venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "numpy<2" matplotlib scipy

After running the tension and compression simulations, generate the graph:

source /path/to/graph_venv/bin/activate
python /path/to/PiecewiseElasticity/examples/graphs.py
deactivate

The graphing script expects both output CSV families and accounts for the scene's gravity direction.

Component parameters

Parameter	Meaning
useVariableYoungModuli	Enables strain-dependent modulus selection.
VariableYoungModuli	Young's modulus values for the strain intervals.
ThresholdStrain	Strictly increasing thresholds between intervals. Its length must be one less than VariableYoungModuli.
SensorPoint	Reference point used to identify the measurement tetrahedron.
ActuatorPoint	Point that defines the measurement direction and actuator side.
decayTime	Simulation time after which variable elasticity is active.
smoothness	Fraction in [0, 1] of an eligible interval used for linear blending.

The selection, smoothing, and measurement details are described in the technical report.

Example configurations

The supplied scene contains four directly comparable configurations:

Configuration	Description	Result
Original SOFA component	Constant Young's modulus baseline.
One threshold	Separate modulus on either side of zero strain.
Multi-threshold	Multiple compression and tension intervals.
Smoothed multi-threshold	The same intervals with gradual modulus transitions.

The Images/ directory contains the animated tension and compression demonstrations above and the static result plots.

Documentation

• Technical report (PDF)

Video

Watch the complete plugin overview on YouTube.

Repository layout

CMakeLists.txt                    CMake build configuration
src/PiecewiseElasticity/          C++ component declaration and implementation
examples/environment.py           Tension/compression SOFA scene
examples/controller.py            Loading controller and CSV export
examples/graphs.py                Tension/compression plotting script
examples/data/mesh/               Homogenized tetrahedral and lattice visual meshes
examples/output/                  Sample tension and compression CSV results
Images/                           README GIFs and result plots
docs/                             Component reference, example guide, and technical report
LICENSE-LGPL.md                   GNU LGPL v2.1 or later
CITATION.cff                      Citation metadata

License

This project is distributed under the GNU Lesser General Public License v2.1 or later.

Citation

If this project supports your work, please cite the software metadata in CITATION.cff. The accompanying technical report is included under docs/.