Reduced Elastic Links

Implementation report for adding floating-frame reduced elastic bodies to Newton's kinematic hierarchy and VBD solver path.

FFRF layout VBD modal solve Revolute attachments Deformed mesh rendering Optional displacement colors Euler-Bernoulli modes Matrix ROM modes Flexible dipper arm Analytic beam test
3new builder entry points
56focused CPU/CUDA unit cases
12headless ViewerGL MP4s
12public reduced-elastic examples

What Changed

Public API

  • JointType.ELASTIC owns a floating rigid frame plus reduced modal coordinates.
  • ModelBuilder.add_link_elastic() creates an elastic link for articulated mechanisms.
  • ModelBuilder.add_body_elastic() mirrors add_body() for stand-alone floating elastic bodies.
  • ModelBuilder.add_joint_elastic() is the state-owner joint used by those helpers.
  • ModalBasis stores sampled linear mode values; ModalGeneratorBeam, ModalGeneratorPOD, ModalGeneratorFEM, and ModalGeneratorSampled construct reusable bases.
  • The viewer now deforms elastic shape meshes from sampled modal basis values during log_state(), with an optional Matlab jet displacement-color diagnostic.

State Layout

  • joint_q: [px, py, pz, qx, qy, qz, qw, eta0, eta1, ...].
  • joint_qd: [vx, vy, vz, wx, wy, wz, eta_dot0, eta_dot1, ...].
  • The body still has a normal body_q and body_qd slot for rigid-body infrastructure.
  • Modal endpoint samples are cached from the existing joint parent/child transforms, with no separate attachment API.
  • Multiple elastic bodies can share one modal basis through elastic_basis; each joint/render sample keeps its basis-local sample index.

Solver Pipeline

Stage Implementation
Frame sync The elastic owner joint's first 7/6 coordinates are copied into the normal body pose/twist slots before rigid VBD runs.
Modal prediction Each modal coordinate uses an implicit Euler update with modal mass, stiffness, damping, and Control.joint_f.
Attachment evaluation Rigid VBD evaluates ordinary joint anchors through sampled mode shapes when the parent or child body is elastic.
Modal constraint solve After each rigid VBD pass, modal coordinates receive a diagonal implicit solve from joint-anchor residual gradients projected through the mode samples.
Frame write-back The solved body pose/twist is copied back into the owner joint, preserving the solved modal coordinates.
Viewer draw Builder finalization samples elastic shape vertices and a diagnostic centerline. ViewerGL hides the rigid instance for those shapes and uploads deformed mesh vertices each frame.
Elastic contact generation Reduced elastic shapes reuse their surface samples for contact. Each deformed surface vertex is reconstructed on the fly and queried against rigid/static shapes; elastic-elastic and face-interior contact are left for follow-up work.
Modal contact solve VBD keeps contact separate from the joint solve. The rigid side uses the deformed elastic contact point, while the elastic side projects the same fixed-stiffness contact force through the surface sample's phi values into the modal coordinates.

Mode Basis

The demo modes are now generated through ModalBasis rather than per-body Python callables. ModalBasis stores GPU-friendly samples phi[sample, mode]; builders add attachment and surface sample points locally to that basis, then flatten the values into the current VBD arrays.

ModalGeneratorFEM covers the Simscape-style matrix ROM path: users provide nodal coordinates plus M, K, and optional C matrices, Newton solves K phi = lambda M phi, mass-normalizes the selected eigenvectors, projects damping into modal space, and samples the resulting linear mode shapes at render vertices and joint interface nodes.

The beam generator produces standard small-deflection fields. The four-bar coupler uses one axial extension mode and the first two pinned-pinned Euler-Bernoulli bending modes. The bending displacement includes the plane-section axial term u_x = -y dw/dx, so the rendered beam cross-section rotates consistently with the neutral-axis deflection. The elastic box render cache now subdivides the visible surface in x, y, and z at roughly 1 cm spacing, and the beam examples seed each modal basis with those exact render-surface vertices, diagnostic line points, and attachment points.

The Watt coupler now keeps its axial mode explicit and replaces the analytic bending modes with a stiffer trajectory POD mode built from finite pinned-pinned bending exemplars. The runtime representation is still linear, but the main passive bending coordinate carries the cross-section rotation and surface correction from the exemplar shapes, reducing the visible endpoint volume gain.

The revolute endpoint fixture now uses eight independent linear POD modes extracted from finite-rotation torsion exemplar shapes. The initial 90 degree twist is a least-squares projection into that basis, so the held shape is nearly volume preserving without any example-side q_twist^2 coordinate coupling. After release, all modal coordinates evolve through the solver as ordinary linear modal DOFs. The example test tracks deformed mesh volume and fails if the visible shaft gains or loses too much volume.

The prismatic compression fixture uses an axial strain field with Poisson lateral strain. Its modal coordinate is driven from the same command as the prismatic actuator, so the doubled carriage stroke produces visible lateral bulging in compression and necking in extension while the fixed endpoints keep the elastic body in the joint hierarchy.

The mechanism set now includes three mixed rigid/elastic textbook-style articulations. A slider-crank uses the analytic closure equation for a connecting rod with elastic axial extension. A Watt straight-line linkage, historically used to approximate straight-line guided motion from rotary links, is now raised and oriented upright in the x-z plane; it attaches both endpoints and a vertical guided midpoint follower to one elastic coupler. The Watt drive is only the ground-to-left-rocker revolute target; the elastic modal DOFs are passive. A bell-crank transfer, a standard lever mechanism for redirecting motion through an angle, uses two separate elastic pushrods between rigid rockers; only the input rocker joint is actuated, and the elastic modes respond through the joint constraints. The Watt and bell-crank clips use larger driven rigid-link displacements and longer sequences to make the coupled rigid/elastic motion easier to read.

The gravity examples attach rigid weights to elastic bodies with ordinary fixed joints in a gravity-enabled model. A horizontal cantilever starts from an undeformed horizontal pose, drops under the attached weight, then runs with zero post-release modal damping while approaching the Euler-Bernoulli static tip displacement delta = P L^3 / (3 E I). A vertical bar is fixed at a raised top fixture, carries a heavier lower suspended weight, starts unextended, and checks the measured end-to-end stretch delta = |x_bottom - x_top| - L = P / k.

The flexible dipper example starts perfectly straight, is pinned at an interior fulcrum roughly two-thirds up a shortened vertical post, and is driven by a lower prismatic hydraulic link. The actuator now raises and lowers the arm through a slow stroke while a rigid tip weight loads the elastic body. The tuned render uses 32 VBD iterations with a lower fixed joint penalty and stronger modal damping, keeping the passive bend visible without the late-frame ringing seen with the softer block-solve tuning.

The plastic chair stick-slip example uses the CC0 Poly Haven Plastic Monobloc Chair 01 glTF as both the full visual mesh and the elastic contact surface. All 3271 raw mesh vertices are sampled into the same modal basis used by rendering, and contact generation queries those deformed vertices directly against the ramp. The previous hidden four-foot proxy remains useful as a controlled fallback, but the current report clip exercises full-mesh elastic contact.

The vibration example uses a stiffer, lightly damped finite-mass mode and releases the beam from an initial deflection, producing a quick underdamped ring-down. ModalGeneratorPOD starts the exemplar-deformation path by extracting linear modes from sampled displacement snapshots.

Mode Counts

Example Total modes Per elastic body
Elastic 4-Bar Linkage33
Revolute Torsion Fixture88
Prismatic Compression Fixture11
Elastic Slider-Crank33
Elastic Watt Linkage22
Elastic Bell-Crank Transfer42 + 2
Matrix ROM Handling Beam88
UR10 Elastic Car Panel66
Flexible Dipper Arm44
Wall Pad Contact22
Two-Gripper Contact Stable42 + 2
Scraper Contact22
Plastic Chair Stick-Slip1010
Cantilever Tip Load11
Cantilever Vibration11
Cantilever With Rigid Weight11
Vertical Suspended Weight11

Material And Stiffness Inputs

The values below are the material inputs and stiffness sources used by the report examples. Beam-generated bases list the Young's or shear modulus used by the generator. POD, direct, and matrix ROM bases list the physical source or matrix input instead of inventing an equivalent Young's modulus.

Example Elastic modulus or stiffness source
Elastic 4-Bar Linkage ModalGeneratorBeam default E = 1.0e6 Pa for the coupler shape basis; the solver stiffness is explicitly overridden.
Revolute Torsion Fixture Finite-twist POD basis with rectangular-shaft torsion properties: G = 4.0e4 Pa, density 500 kg/m^3, length 1.0 m.
Prismatic Compression Fixture Direct axial Poisson-stretch mode, no Young's modulus. The prismatic drive also uses ke = 4.0e4, kd = 140 as actuator gains.
Elastic Slider-Crank Beam basis with E = 2.5e6 Pa, density 300 kg/m^3, damping ratio 0.035.
Elastic Watt Linkage Axial beam basis with E = 2.0e6 Pa, density 320 kg/m^3; passive bending uses a finite-bending POD exemplar stiffness.
Elastic Bell-Crank Transfer Pushrod basis generated from E = 8.0e5 Pa, density 300 kg/m^3; both rods override to the same direct axial/bending stiffness pair.
Matrix ROM Handling Beam Matrix ROM from user-style M/K/C input: density 1400 kg/m^3, thickness 0.035 m, in-plane spring scale 980, out-of-plane spring scale 120, C = 0.004 M + 0.0008 K.
UR10 Elastic Car Panel Direct sampled modes on the 1.18 m x 0.81 m decimated hood mesh. Six low-order panel fields are projected to remove rigid motion and normalized to unit peak displacement, with modal stiffness coefficients [8.2, 9.8, 7.0, 11.5, 15.0, 14.0] kN/m and modal mass 0.18 kg each. For the example's free-edge pressure profile, this is about 1.7e5 N/m (166 N/mm) measured as total projected load over maximum panel deflection. The elastic panel body mass is 5 kg.
Flexible Dipper Arm Beam basis generated with E = 7.5e5 Pa, density 420 kg/m^3; solver uses tuned modal stiffness [1.8e5, 11, 6.4e4, 2.0e5], modal damping [4.0, 0.95, 0.60, 0.85], and a 5.0e5 fixed joint penalty for visible bending without residual-driven ringing.
Wall Pad Contact Two-mode direct rubber compression field. Contact uses fixed material coefficients ke = 8.0e4, kd = 0.04, and mu = 2.2; modal stiffness is [220, 900]. A 1 mm shape contact gap generates contacts just before penetration so the VBD iterations do not drop into a late-frame contact/no-contact limit cycle.
Two-Gripper Contact Stable Two opposing two-mode rubber pads squeeze a free dynamic 0.06 kg rigid sphere from the sides, then lift it under gravity with no guide, prescribed object path, or shake motion. The pads start near contact, close to about 14.5 mm modal compression, and use contact coefficients ke = 8.0e4, kd = 0.35, mu = 8.0, and a 2 mm detection gap. Each pad uses modal stiffness [110, 420] and damping [1.1, 1.35].
Scraper Contact Two-mode direct scraper field with vertical compression and lateral bending. Contact uses fixed material coefficients ke = 8.0e4, kd = 0.04, and mu = 2.2; modal stiffness is [640, 260] with lower modal damping for faster rebound.
Plastic Chair Stick-Slip Ten-mode POD basis from exemplar leg-bending, foot-splay, seat-sway, and lateral foot/leg shear displacement snapshots on the CC0 Poly Haven monobloc chair mesh. Modal stiffness is [8.5, 7.75, 7.0, 5.95, 4.91, 4.06, 3.31, 2.65, 2.13, 1.77] kN/m for a 3 kg chair with damping ratio 0.005. The chair faces down a fixed 24 deg smooth ramp under full gravity. Ramp contact uses the raw chair mesh vertices as elastic contact samples with fixed coefficients ke = 6.0e3, kd = 0.008, and mu = 0.72; the chair/ramp generation gaps are 2 mm and 4 mm so contacts persist through VBD iterations without expanding the physical ramp surface.
Cantilever Tip Load Analytic Euler-Bernoulli tip-load mode using flexural rigidity EI = 0.24 N*m^2, length 0.9 m.
Cantilever Vibration Beam basis with E = 3.2e7 Pa, density 250 kg/m^3, damping ratio 0.001.
Cantilever With Rigid Weight Direct analytic tip-load stiffness chosen from the target static deflection: load P = 476.766 N, target delta = 0.115 m.
Vertical Suspended Weight Direct axial stiffness chosen from target extension: load P = 441.45 N, target delta = 0.095 m.

Displacement Coloring

ViewerBase.show_elastic_strain is available as an optional diagnostic that colors each elastic render vertex by modal displacement magnitude relative to the rest shape. This is not true mechanical strain. The matrix ROM handling beam, flexible dipper arm, and reduced elastic contact examples enable it to highlight where the modal response concentrates; the other report videos leave the diagnostic disabled and use the default orange elastic mesh color so the examples show the deformed geometry directly.

Videos

Elastic 4-Bar Linkage

Example source on GitHub

The coupler is an elastic link in a revolute-jointed four-bar. The orange coupler mesh is deformed directly from axial and Euler-Bernoulli bending modes; the cyan centerline is only a diagnostic overlay.

Revolute Torsion Fixture

Example source on GitHub

A revolute endpoint aligned with the shaft axis leaves the centerline unchanged. The rectangular shaft starts from held 90 degree finite-rotation torsion fields, then releases with low modal damping while tracking mesh volume drift.

Prismatic Compression Fixture

Example source on GitHub

A rotating base drives a prismatic carriage through a doubled stroke attached to an elastic bar. The axial mode includes Poisson lateral strain, so the mesh visibly bulges under compression and necks under extension while rotating with the parent frame.

Elastic Slider-Crank

Example source on GitHub

A rigid crank drives a rigid slider through an elastic connecting rod. The test compares slider position to the analytic slider-crank closure using the rod's current axial modal coordinate.

Elastic Watt Linkage

Example source on GitHub

A raised upright Watt-style straight-line linkage constrains the elastic coupler endpoints through rigid rockers in the x-z plane and attaches a vertical guided midpoint follower to the same elastic body. The coupler uses one axial mode plus one finite-bending POD mode, and the driven DOF is only the ground-to-left-rocker revolute target.

Elastic Bell-Crank Transfer

Example source on GitHub

Two elastic pushrods transmit motion from an actuated input rocker through a rigid bell crank to an output rocker, redirecting the input rotation through the central lever. The input rocker displacement is doubled, the elastic modes are not directly driven, and each pushrod is checked against its analytic modal length.

Matrix ROM Handling Beam

Example source on GitHub

A robot wrist proxy clamps the left edge of a straight rectangular handling beam with interior lightening holes. ModalGeneratorFEM extracts eight mass-normalized modes from nodal M/K/C matrices; two prismatic gripper carriages attach to actual bottom-edge material nodes, extend rigid arms toward the camera along y, and lift a visual picked panel while a distributed part-weight load is projected as Phi.T @ f. A gray/magenta/yellow overlay shows an 8x-amplified centerline deflection from a perfectly straight reference beam. The test compares the eight-mode static sag against the full matrix solve.

UR10 Elastic Car Panel

Example source on GitHub

A UR10 end effector prescribes the floating frame of a reduced elastic hood panel through four fixed gripper samples. The clip uses an offline-decimated CarHoods10k STL (skin_109_geometry_43_decimated_40000.stl) generated once from the original 142,304-triangle hood mesh and normalized to a larger 1.18 m x 0.81 m automotive-panel scale. The elastic body mass is 5 kg with inertia estimated from the loaded mesh extents. The robot is mounted on a pedestal and follows a raised side-sweep trajectory, keeping the panel and the amplified deformation guides above the floor over the full 240-frame clip. Four visible rigid struts run from the end-effector hub to the suction cups, which are snapped to the same surface samples used by the fixed joints. Six sampled panel modes respond to a distributed handling-pressure load; displacement coloring and a 4x-amplified yellow rib overlay make the flexible response easier to read.

Flexible Dipper Arm

Example source on GitHub

A straight-start dipper arm is pinned at an interior fulcrum on a shortened support post, driven up and down by a lower prismatic hydraulic link, and loaded at the tool end. Displacement coloring highlights the passive modal bending as the driven rigid linkage moves under gravity.

Cantilever Tip Load

Example source on GitHub

A single elastic link uses the exact Euler-Bernoulli cantilever tip-load shape. The modal coordinate tracks the analytic static solution as the load varies.

Cantilever Vibration

Example source on GitHub

The same reduced beam formulation is given finite modal mass and released from an initial deflection, so the visible motion comes from modal dynamics rather than a prescribed load.

Cantilever With Rigid Weight

Example source on GitHub

A fixed elastic beam starts horizontal, carries a rigid tip mass in gravity, and uses zero post-release modal damping. The reduced coordinate uses the exact Euler-Bernoulli tip-load shape, and the final deflection is checked against P L^3 / (3 E I).

Vertical Suspended Weight

Example source on GitHub

A vertical elastic bar is fixed at a raised top fixture and supports a much heavier rigid block under gravity. It starts unextended, visibly stretches, and the top-fixed axial mode includes Poisson lateral contraction while the example checks measured total stretch rather than compression.

Reduced Elastic Contact Examples

Wall Pad Contact

Example source on GitHub

A kinematic reduced elastic rubber pad presses into a rigid wall. The contact generator reconstructs each pad surface vertex from the current modal coordinates before querying the wall, using a 1 mm generation gap so contacts are available before the solver iterations cross into penetration. This removes the previous late-frame contact/no-contact chatter; the test now checks zero settled contact dropouts and bounded modal step/second-difference.

Two-Gripper Contact

Example source on GitHub

Stable

Two opposing reduced elastic pads close around a free dynamic rigid sphere and lift it under real gravity through frictional contact only. The shake motion has been removed; the pads now close farther so the first two rubber compression modes are easier to read. The example checks zero settled contact dropouts plus a settled-window vibration metric. The rendered run measures no lateral vibration, less than 0.02 mm vertical relative motion, and about 14.5 mm balanced compression on both pads.

Scraper Contact

Example source on GitHub

A kinematic reduced elastic scraper leg is dragged along the ground. Surface-sample contact produces vertical compression and frictional lateral bending, giving a compact stick-slip style contact test for a rubber end effector sliding on a rigid plane.

Plastic Chair Stick-Slip

Example source on GitHub

A reduced elastic Poly Haven monobloc chair faces down a fixed 24 degree ramp and now uses the raw visual mesh as the elastic contact surface. Contact generation samples all 3271 deformed chair vertices against the ramp; the rendered run reaches 193 active contacts at peak, so the full-mesh path is tractable for this asset. The stiffer POD modes reduce the initial self-weight squash, a slightly lower friction coefficient avoids over-sticking, and the larger contact generation gap removes post-settle contact dropouts. In the rendered clip the chair slides about 0.27 m, reaches about 8.0 cm maximum local displacement, and the active contact samples show 293 measured stick-to-slip transitions. The test checks contact generation, bounded modal deformation, nonzero sliding, stick/slip regimes measured from active ramp contact tangential velocity, and low average normal bounce.

Plastic Chair Mode Exercise

Example source on GitHub Video driver

A diagnostic clip directly drives each POD modal coordinate in sequence with physics disabled. The chair is shown upright with displacement coloring enabled, so noisy or unexpected deformation content in the leg-bending and lateral foot-shear basis can be inspected independently from contact and friction.

Tests

Test Coverage
test_elastic_link_layoutOwner joint layout, mode arrays, and model metadata.
test_modal_basis_add_sampleBasis-local sampled linear mode storage and duplicate sample handling.
test_modal_generator_beam_samplesAnalytic axial, pinned-pinned bending, and torsion samples from ModalGeneratorBeam.
test_modal_generator_pod_rank_onePOD basis extraction from exemplar displacement samples with heuristic mass/stiffness.
test_modal_generator_fem_matrix_romGeneralized matrix eigen solve, mass normalization, and modal damping projection for a nodal M/K/C model.
test_elastic_fk_syncFFRF pose/twist transfer through eval_fk.
test_elastic_endpoint_shape_samplingSampling mode shapes at ordinary joint child transforms.
test_elastic_endpoint_modal_basis_samplingSampling a ModalBasis at a revolute attachment and storing the basis-local sample index.
test_modal_basis_shared_by_elastic_bodiesTwo elastic bodies sharing one modal basis template.
test_elastic_render_shape_samplingRender polyline sampling and quadratic basis sampling for visible elastic body drawing.
test_elastic_shape_mesh_samplingActual elastic render mesh vertex sampling for Euler-Bernoulli bending modes.
test_elastic_shape_box_windingGenerated elastic box render meshes use outward triangle winding for correct backface culling.
test_elastic_shape_box_exact_modal_samplesElastic box render vertices are exact modal samples, avoiding interpolation artifacts on subdivided surfaces.
test_torsion_render_shape_samplingSaint-Venant torsion leaves the centerline fixed while rotating surface vertices.
test_finite_torsion_exemplar_preserves_volumeFinite-rotation torsion exemplar preserves closed-mesh volume while the small-angle torsion field shows large volume gain.
test_finite_torsion_pod_modes_project_exemplarEight independent POD modes reconstruct the held 90 degree finite-twist shape without nonlinear coordinate coupling.
test_cantilever_tip_load_solutionAnalytic Euler-Bernoulli cantilever tip-load displacement P L^3 / (3 E I).
test_cantilever_modal_vibration_solutionMulti-step implicit Euler solution for a free vibrating reduced cantilever mode.
test_elastic_modal_implicit_solution_vbdAnalytic implicit Euler solution for a forced damped modal oscillator.
test_vbd_revolute_uses_elastic_endpointVBD revolute residuals use deformed endpoint positions.
test_vbd_revolute_constraint_solves_elastic_modeAnalytic modal solve for a displaced revolute anchor.
test_fourbar_elastic_coupler_geometryAnalytic four-bar geometry with an elastic coupler and revolute attachments.
test_vbd_prismatic_rotates_elastic_childA prismatic joint from a rotating rigid parent carries the parent orientation onto an elastic child.
test_crank_slider_elastic_analytic_geometryTextbook slider-crank closure with elastic axial extension in the connecting rod.
test_elastic_multiple_attachment_samplesIndependent endpoint and midpoint attachment samples on one elastic body.
test_matrix_rom_exampleMatrix-derived handling beam with wrist support, prismatic grippers, projected picked-part load, and full-matrix static sag reference.
example_robot_ur10_elastic_panel.test_finalKinematic UR10 frame driving a six-mode elastic car-panel mesh with bounded modal response, visible deformation, and sub-millimeter gripper residual.
test_dipper_arm_exampleFlexible dipper arm with revolute root, prismatic actuator loop, suspended payload, visible passive bending, and bounded volume drift.
test_elastic_surface_contact_generationPoint-sampled elastic surface vertices generate rigid contacts with elastic sample metadata.
test_elastic_surface_contact_uses_deformed_vertexContact generation reconstructs deformed elastic surface points instead of using rest vertices.
test_vbd_elastic_contact_solves_modal_penetrationVBD modal contact solve projects contact force into an elastic compression coordinate.
test_elastic_wall_contact_exampleWall-pad contact generates contacts and visible modal compression.
test_elastic_gripper_contact_exampleFree dynamic two-gripper lift under gravity checks two-sided contact, visible modal compression, bounded lift lag, zero settled contact dropouts, and low settled vibration.
test_elastic_scraper_contact_exampleScraper contact generates ground contacts, vertical compression, and lateral modal bending.
test_elastic_chair_stick_slip_exampleCC0 monobloc chair facing down a fixed smooth ramp uses raw full-mesh vertex contacts, bounded POD deformation, nonzero sliding, contact stick/slip regimes measured from active ramp tangential velocity, and low average normal bounce.

Current Scope

Generated in headless Newton ViewerGL. CUDA/OpenGL interop was unavailable on this host, so ViewerGL used its built-in CPU-copy fallback for frame capture.