Harmonize PCS and GVS parameter models

[mstoelzle]

Summary

This PR harmonizes PCS, PlanarPCS, and GVS around a shared public parameter vocabulary and a common link-oriented construction/update workflow.

The central model is now:

PCSParams / PlanarPCSParams
├── link: ContinuumLinkParams
├── base_pose
└── gravity

GVSParams
├── link: ContinuumLinkParams
├── joint: JointParams
├── base_pose
└── gravity

Generalized link stiffness and damping matrices are the canonical runtime parameters. Isotropic Young's modulus, shear modulus, and material damping remain ergonomic construction and differentiable identification variables through a separate IsotropicMaterialParams PyTree.

Motivation

PCS and GVS previously exposed substantially different names and ownership rules for the same physical concepts. GVS construction used Greek/abbreviated fields and GVS-local link/cross-section structures, while PCS stored mostly flat system parameters and a global damping matrix. This made it difficult to:

• transfer code and intuition between PCS and GVS;
• reuse typed parameter definitions;
• update one link without rebuilding unrelated system state;
• distinguish construction inputs from canonical runtime mechanics;
• optimize interpretable material parameters without duplicating them in runtime params;
• support joint stiffness and damping consistently in GVS; and
• extend shared link and joint concepts to future system families.

This is intentionally a pre-1.0 clean break. It removes the divergent APIs instead of preserving aliases that would keep both vocabularies alive.

Strategy and architecture

Shared continuum components

New public components live in soromox.systems.components and are re-exported from soromox.systems:

• ContinuumLinkParams
• JointParams
• CrossSectionParams
• CrossSectionGeometry
• IsotropicMaterialParams
• LinearProfile
• LinkSpec
• JointSpec
• shear_modulus_from_poisson_ratio

The package is split by responsibility:

• cross_sections.py: coefficient packing, constant/linear profiles, and area/inertia geometry;
• links.py: canonical per-link runtime params, link specifications, validation, and matrix construction inputs;
• joints.py: joint definitions, DOF metadata, factories, validation, stiffness, and damping;
• materials.py: isotropic material PyTree and Poisson-ratio conversion.

GVS keeps only genuinely GVS-specific concepts: GVSSegment, StrainBasisSpec, basis evaluation, quadrature, padded operands, and GVS structure/runtime machinery.

Canonical link and joint mechanics

ContinuumLinkParams owns length, density, reference strain, cross section, generalized stiffness, and generalized damping. Both matrices are finite, symmetric, per-link arrays with matching shapes.

PCS assembles its global matrices from link-local blocks. GVS interleaves joint and link blocks so both joint stiffness and joint damping contribute to the global dynamics. Link blocks in GVS are zero-padded beyond each link's active basis coordinates.

The old PCS cross-link damping representation is deliberately removed: damping now has the same ownership and update semantics as stiffness.

Construction specifications

LinkSpec accepts exactly one stiffness source:

• young_modulus plus shear_modulus; or
• an explicit generalized stiffness matrix.

It similarly accepts exactly one damping source:

• material_damping_coefficient; or
• an explicit generalized damping matrix.

Circular, rectangular, and other shared cross-section factories populate a single coefficient-based CrossSectionParams; there is no profile-parameter class hierarchy. LinearProfile(base, tip) represents linear geometry changes.

reference_strain now belongs to the link. StrainBasisSpec describes only GVS basis selection and order.

Differentiable isotropic material mapping

PCS, PlanarPCS, and GVS expose the same APIs:

stiffness, damping = robot.link_matrices_from_material(material)
updated = robot.with_isotropic_material(material)

Unit-response operators implement:

K_i = E_i K_i,E + G_i K_i,G
D_i = eta_i D_i,eta

This keeps material identification cheap, batched, JIT-compatible, and differentiable without storing a second material representation inside system params. with_isotropic_material returns a new robot and does not mutate the original or retain the caller-owned material PyTree.

Geometry changes refresh unit-response operators but leave explicitly supplied canonical matrices unchanged. Reapplying with_isotropic_material is the explicit step that rebuilds them.

Updates and immutable replacement

All three continuum systems now support link-local updates:

robot = robot.update_link_params(
    stiffness=1.1 * robot.params.link.stiffness,
    damping=0.9 * robot.params.link.damping,
)

GVS additionally supports:

gvs = gvs.update_joint_params(
    damping=1.2 * gvs.params.joint.damping,
)

Nested immutable replacement remains available:

params = robot.params.replace(
    link=robot.params.link.replace(density=new_density)
)
robot = robot.with_params(params)

Construction examples

PCS from isotropic material properties

from soromox.systems import PCS, LinkSpec, shear_modulus_from_poisson_ratio

young = 1.0e6
shear = shear_modulus_from_poisson_ratio(young, poisson_ratio=0.45)

pcs = PCS.from_links([
    LinkSpec.circular(
        length=0.20,
        radius=0.012,
        density=1000.0,
        young_modulus=young,
        shear_modulus=shear,
        material_damping_coefficient=1.0e4,
        reference_strain=[0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
    )
])

GVS with tapered geometry and joint mechanics

from soromox.systems import (
    GVS,
    GVSSegment,
    JointSpec,
    LinearProfile,
    LinkSpec,
    StrainBasisSpec,
)

gvs = GVS.from_segments([
    GVSSegment(
        link=LinkSpec.rectangular(
            length=0.20,
            height=LinearProfile(base=0.030, tip=0.020),
            width=0.025,
            density=1000.0,
            young_modulus=1.0e6,
            shear_modulus=3.4e5,
            material_damping_coefficient=1.0e4,
            reference_strain=[0.0, 0.0, 0.0, 1.0, 0.0, 0.0],
        ),
        joint=JointSpec.revolute(
            axis="z",
            stiffness=[[0.30]],
            damping=[[0.02]],
        ),
        basis=StrainBasisSpec(
            type="legendre",
            strain_selector=("kappa_y", "sigma_x"),
            basis_order=1,
        ),
        num_gauss_points=7,
    )
])

Optimizing interpretable material values

import jax
import jax.numpy as jnp
from soromox.systems import IsotropicMaterialParams

material = IsotropicMaterialParams(
    young_modulus=jnp.array([1.0e6]),
    shear_modulus=jnp.array([3.4e5]),
    material_damping_coefficient=jnp.array([1.0e4]),
)

def loss(candidate_material):
    candidate = robot.with_isotropic_material(candidate_material)
    return jnp.mean((candidate.stiffness_matrix() - target_stiffness) ** 2)

value, gradient = jax.value_and_grad(loss)(material)

The user guide also includes positive log-space parameterization, a complete Optax loop, geometry/material co-optimization, and direct generalized-matrix optimization.

Documentation

Rather than a narrowly scoped material-only tutorial, this PR adds a balanced
component/parameter documentation set:

• Continuum components documents shared cross sections, links, joints, material models, ownership, dimensions, and construction alternatives.
• Parameters and optimization documents construction, immutable updates, material identification, log-space/Optax optimization, geometry co-optimization, and PCS/GVS-specific notes.
• PCS/GVS parameter migration provides a concise conversion checklist for imports, constructors, nested field paths, GVS argument names, link-local damping, and material updates.

The enduring component and parameter pages are integrated into the existing API and user-guide navigation and cross-linked from the quick start, examples, parameter utilities, PCS pages, and GVS pages. The release-specific migration guide is intentionally linked only from the Unreleased changelog. Public APIs introduced or changed here include package-style docstrings with arguments, return values, validation behavior, and examples.

The Unreleased changelog entry separately highlights the public additions,
behavior changes, fixes, and breaking changes, with a direct link to the compact
migration guide.

Migration guide

Imports

Shared specifications are no longer GVS-owned.

# Before
from soromox.systems.gvs import LinkSpec, JointSpec

# After
from soromox.systems import LinkSpec, JointSpec
# or: from soromox.systems.components import LinkSpec, JointSpec

Keep importing GVSSegment, StrainBasisSpec, and GVS structures from the GVS namespace or the top-level systems exports.

PCS and PlanarPCS params

Replace flat constructors with from_links or params_from_links:

# Before
params = PCSParams(
    length=lengths,
    radius=radii,
    density=densities,
    young_modulus=young,
    shear_modulus=shear,
    damping=global_damping,
    reference_strain=reference,
)

# After
params = PCS.params_from_links([
    LinkSpec.circular(
        length=L,
        radius=r,
        density=rho,
        young_modulus=E,
        shear_modulus=G,
        material_damping_coefficient=eta,
        reference_strain=xi_ref,
    )
    for L, r, rho, E, G, eta, xi_ref in link_rows
])

Split an old block-diagonal PCS damping matrix into one generalized damping block per link. Cross-link damping terms are no longer supported.

Field access changes from flat fields to link-owned fields:

robot.params.length             -> robot.params.link.length
robot.params.density            -> robot.params.link.density
robot.params.reference_strain   -> robot.params.link.reference_strain
robot.params.stiffness          -> robot.params.link.stiffness
robot.params.damping            -> robot.params.link.damping

GVS link specifications

Replace abbreviated/Greek construction names with public descriptive names:

E       -> young_modulus
nu      -> derive shear_modulus with shear_modulus_from_poisson_ratio
rho     -> density
eta     -> material_damping_coefficient
L       -> length
r_i/r_f -> radius=LinearProfile(base=..., tip=...)

Move reference_strain from StrainBasisSpec to LinkSpec. Replace legacy basis active/orders arguments with strain_selector/basis_order.

Cross sections

Replace endpoint-specific geometry fields and GVS-local cross-section params with shared factories. Constant scalars and LinearProfile values are packed into CrossSectionParams.coefficients by LinkSpec; callers normally do not construct coefficient arrays by hand.

Runtime material updates

Do not expect Young's modulus, shear modulus, or damping coefficient inside robot.params. Keep them in a caller-owned IsotropicMaterialParams and explicitly apply them:

material = material.replace(young_modulus=1.1 * material.young_modulus)
robot = robot.with_isotropic_material(material)

For anisotropic or coupled identification, optimize and replace params.link.stiffness and params.link.damping directly.

Joint stiffness and damping

GVS joint values are now stored in params.joint.stiffness and params.joint.damping and contribute to global assembly. Existing joint specs that omit them continue to construct zero joint matrices.

Compatibility policy

No aliases for GVSLinkParams, old flat PCS fields, GVS-local shared specs, Greek construction fields, or the global PCS damping matrix are added. Downstream code should migrate in one step using the mappings above.

Validation

Completed locally on the feature branch:

• focused shared-component, PCS, PlanarPCS, and GVS tests;
• autodiff, scalar/per-link material, matrix-bypass, joint assembly, geometry-refresh, and immutable replacement coverage;
• Ruff checks, Python compilation checks, and staged whitespace validation;
• strict MkDocs and Zensical documentation builds;
• all project example model workloads at their complete simulation horizons, including full encoded videos where headless renderers support them;
• all four Section IV-A SoRoMoX simulations, the available planar/spatial
  PyElastica simulations, a complete 3,001-frame planar video, and all four
  comparison plots;
• the complete 100-step Section V-A parameter identification, all 22 residual evaluations, and all four residual plots;
• all Section V-C configuration-space generators (setpoint, slow/fast
  trajectory, and regulation-to-tracking), all controller rollouts, all derived
  plots, the complete 12-DOF operational-space trajectory, the matched
  full/partial feedback-linearization comparison, finite-array audits, metrics,
  canonical paper figure, and composite PDF/SVG;
• both Section V-D gain-optimization programs at their configured iteration
  counts: synergistic completed two finite iterations; collocated reproduced
  the known iteration-1 NaN guard and saved its partial result;
• both Section V-E CBF/no-CBF simulations, finite-array audits, and publication
  plots;
• Section V-F released-checkpoint evaluation (95.3% success), a fresh complete
  105-step policy rollout with finite arrays, and reward plotting from every
  committed training log;
• three complete PPO rollout/update cycles through 38,400 timesteps, plus a
  finite reward record at 40,192 timesteps; the user then requested that the
  multi-hour million-step CPU training be stopped;
• 868 repository tests passed without failure (68% of 1,255 collected) before
  the user requested that the remaining unusually long numerical tests be
  skipped.

Known baseline and environment-specific limitations:

• Section IV-B targets a GPU, but this host exposes only a CPU. An exact paper-grid
  CPU attempt completed every batch size for one- and two-link systems and part
  of the four-link sweep before being stopped as an impractical and invalid
  substitute for the publication GPU benchmark.
• SoRoSim reproduction requires MATLAB plus SoRoSim, neither of which is installed here.
• the PyElastica tendon case imports an external muscles module that is not present in this repository/environment.
• the Section V-D fresh-result plotter cannot consume the intentionally partial
  collocated MAT output after the known NaN guard because q_des_ts is absent;
  canonical complete result plotting remains separate from this known optimizer
  behavior.
• browser/display-backed Viser and Open3D recording paths require an interactive
  or headless graphics service. The Section V-E renderer loaded the fresh
  trajectory and built the migrated robot geometry, then blocked in the
  unavailable macOS graphics service without producing an MP4; the corresponding
  simulations and noninteractive plots were validated separately.
• repository-wide Ruff lint passes. The full-tree format audit identifies nine
  pre-existing out-of-scope files that would be reformatted; changed files in
  this PR are formatted.

Breaking changes

This PR changes public construction signatures and parameter field paths for PCS, PlanarPCS, and GVS. It also removes cross-link PCS damping and GVS-local ownership of shared link/joint specifications. These changes are deliberate and covered by the migration guide above.

[Copilot]

Pull request overview

This PR restructures SoRoMoX continuum-system parameters to use shared, componentized link/joint/cross-section/material models across PCS (incl. PlanarPCS) and GVS, aligning construction, immutable updates, and differentiable identification workflows.

Changes:

• Introduces soromox.systems.components (links, joints, cross-sections, isotropic materials) and re-exports those public APIs from soromox.systems.
• Migrates PCS/PlanarPCS/GVS parameter trees to nested link: ContinuumLinkParams (and joint: JointParams for GVS), removing legacy flat/Greek fields and global PCS damping.
• Updates tests, benchmarks, examples, paper scripts, and documentation/navigation to the new construction and update APIs (from_links, from_segments, update_link_params, update_joint_params, with_isotropic_material).

Reviewed changes

Copilot reviewed 81 out of 81 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tools/benchmarks/_benchmark_common.py	Updates PCS/PlanarPCS/GVS benchmark constructors to LinkSpec/JointSpec/GVSSegment.
tests/systems/test_typed_params_api.py	Adjusts typed-param immutability and update semantics to nested link params and link-local update APIs.
tests/systems/test_system_lengths.py	Updates GVS segment construction to shared LinkSpec/JointSpec and new strain-basis fields.
tests/systems/test_soft_robot_defaults.py	Moves CrossSectionGeometry import to shared components.
tests/systems/test_shared_continuum_components.py	Adds coverage for shared components, joint/link block assembly, and material mapping/JIT/grad behavior.
tests/systems/test_pressure_actuated_pcs_models.py	Migrates I-SUPPORT/PCS param usage to ContinuumLinkParams and canonical per-link matrices.
tests/systems/test_planar_pcs.py	Updates PlanarPCS tests to nested link fields and link-local updates (geometry, matrices, lengths).
tests/systems/test_pcs.py	Updates PCS tests to nested link fields and link-local updates (geometry, matrices, lengths).
tests/system_param_builders.py	Rebuilds PCS/PlanarPCS params from canonical per-link matrices and enforces removal of cross-link damping coupling.
tests/rendering/test_open3d_material_frames.py	Updates CrossSectionGeometry import to components package.
tests/rendering/test_isupport_viser_renderer.py	Rebuilds ISupport params via PCS.params_from_links and LinkSpec.
tests/rendering/test_base_renderer.py	Updates CrossSectionGeometry import to components package.
tests/actuation/test_threadlike.py	Updates GVS/PCS imports and migrates parameter update example to link-matrix updates.
src/soromox/systems/soft_robot.py	Removes CrossSectionGeometry from SoftRobot base module (moved to components).
src/soromox/systems/pendulum/pendulum.py	Updates CrossSectionGeometry import source.
src/soromox/systems/pcs/structures.py	Expands docstrings and clarifies PCS/PlanarPCS/ISupport structure attributes.
src/soromox/systems/pcs/params.py	Replaces flat PCS/PlanarPCS fields with link: ContinuumLinkParams; updates validation and docstrings.
src/soromox/systems/pcs/isupport.py	Migrates I-SUPPORT expansion logic to use canonical per-link stiffness/damping and shared components.
src/soromox/systems/params.py	Improves docstrings and clarifies continuum-param base class expectations (link component ownership).
src/soromox/systems/hsa/planar_hsa.py	Updates CrossSectionGeometry import source.
src/soromox/systems/gvs/structures.py	Moves cross-section/profile metadata into static structures; renames basis fields to strain_selector/basis_order.
src/soromox/systems/gvs/params.py	Replaces GVSLinkParams with shared ContinuumLinkParams + JointParams; updates validation and padded-layout checks.
src/soromox/systems/gvs/_runtime.py	Simplifies runtime pytree structures and removes link-only runtime container.
src/soromox/systems/gvs/_assembly.py	Updates runtime array assignment to new strain-basis names and shared cross-section coefficient packing.
src/soromox/systems/gvs/init.py	Stops exporting legacy LinkSpec/JointSpec/GVSLinkParams from the GVS namespace.
src/soromox/systems/components/materials.py	Adds IsotropicMaterialParams and shear_modulus_from_poisson_ratio.
src/soromox/systems/components/links.py	Adds ContinuumLinkParams and LinkSpec with validation and profile packing.
src/soromox/systems/components/joints.py	Adds JointParams and JointSpec (including DOF metadata and factories).
src/soromox/systems/components/cross_sections.py	Adds shared cross-section enums, coefficient storage, profile evaluation, and section properties helpers.
src/soromox/systems/components/init.py	Re-exports shared component APIs.
src/soromox/systems/articulated/articulated_soft_robot.py	Updates CrossSectionGeometry import source.
src/soromox/systems/init.py	Re-exports shared component APIs and removes legacy GVSLinkParams exports.
src/soromox/rendering/opencv_planar_renderer.py	Updates CrossSectionGeometry import source.
src/soromox/rendering/open3d_renderer.py	Updates CrossSectionGeometry import source.
paper_results/secVf_parallel_rl/code/render_rl_video.py	Migrates PCS construction to LinkSpec + params_from_links.
paper_results/secVf_parallel_rl/code/parallel_soromox_env.py	Migrates PCS construction to LinkSpec + params_from_links.
paper_results/secVe_safety_constrained_control/code/pcs_cf_cbf_clf_common.py	Migrates PCS construction to LinkSpec + params_from_links and updates downstream param access.
paper_results/secVd_control_gain_optimization/code/control_gain_optimization_with_synergistic.py	Migrates PCS construction to LinkSpec + params_from_links.
paper_results/secVd_control_gain_optimization/code/control_gain_optimization_with_collocated.py	Migrates PCS construction to LinkSpec + params_from_links.
paper_results/secVc_model_based_control/operational_space_impedance_control/code/operational_space_impedance_common.py	Migrates PCS construction to LinkSpec + from_links, deriving params from the constructed robot.
paper_results/secVc_model_based_control/operational_space_impedance_control/code/compare_impedance_feedback_linearization.py	Migrates PCS construction to LinkSpec + from_links.
paper_results/secVc_model_based_control/configuration_space_comparison/code/configuration_space_comparison_simulation.py	Migrates PCS construction to LinkSpec + from_links.
paper_results/secVa_system_identification/code/identify_soft_tentacle_residual.py	Migrates GVS specs to shared LinkSpec/JointSpec and new strain-basis fields; introduces LinearProfile.
paper_results/secVa_system_identification/code/identify_soft_tentacle_parameters.py	Migrates GVS specs to shared LinkSpec/JointSpec and new strain-basis fields; updates downstream field access.
paper_results/secIVa_benchmarking_sequential_cpu/code/soromox/simulate_tendon_driven_gvs.py	Migrates GVS example to shared specs and new strain-basis fields.
paper_results/secIVa_benchmarking_sequential_cpu/code/soromox/simulate_spatial_pcs.py	Migrates PCS example to LinkSpec + params_from_links.
paper_results/secIVa_benchmarking_sequential_cpu/code/soromox/simulate_planar_pcs.py	Migrates PlanarPCS example to LinkSpec + params_from_links.
paper_results/secIVa_benchmarking_sequential_cpu/code/soromox/simulate_complex_gvs.py	Migrates GVS example to shared specs and new strain-basis fields.
mkdocs.yml	Adds new docs pages to nav (continuum components, parameters/optimization).
examples/simulation/pcs/simulate_tendon_actuated_planar_pcs.py	Migrates PlanarPCS example construction to LinkSpec + params_from_links.
examples/simulation/pcs/simulate_tendon_actuated_pcs.py	Migrates PCS example construction to LinkSpec + params_from_links.
examples/simulation/pcs/simulate_planar_pcs.py	Migrates PlanarPCS example construction to LinkSpec + params_from_links.
examples/simulation/pcs/simulate_pcs.py	Migrates PCS example construction to LinkSpec + params_from_links.
examples/simulation/pcs/simulate_isupport.py	Migrates ISupport example to build link params via PCS.params_from_links and explicit damping matrices.
examples/simulation/pcs/simulate_batched_tendon_actuated_pcs.py	Migrates PCS batch example construction to LinkSpec + params_from_links.
examples/simulation/gvs/simulate_tendon_actuated_gvs.py	Migrates GVS example to shared specs, LinearProfile, and new strain-basis fields.
examples/simulation/gvs/simulate_gvs.py	Migrates GVS example to shared specs and new strain-basis fields.
examples/control/operational_space/control_tendon_actuated_pcs_with_synergistic.py	Migrates PCS construction to LinkSpec + params_from_links.
examples/control/actuation_space/setpoint_regulation_comparison.py	Migrates PCS construction to LinkSpec + params_from_links.
docs/user-guide/quick-start.md	Updates quick start to new construction/update API and links to new parameter/optimization guide.
docs/user-guide/parameters-and-optimization.md	Adds a new user guide page documenting construction, immutable updates, and optimization patterns.
docs/user-guide/examples.md	Updates examples doc to reference new parameter/optimization guide and new update/material workflows.
docs/installation.md	Updates installation verification scripts to use LinkSpec + from_links.
docs/index.md	Updates homepage example to use LinkSpec + from_links.
docs/development/extending.md	Updates development docs examples to use LinkSpec + from_links.
docs/development/contributing.md	Updates contributing docs example for nested link replacement.
docs/api/utilities/parameters.md	Updates parameter docs to reflect shared components, new construction workflow, and nested link params.
docs/api/systems/pcs/pcs.md	Adds updated PCS construction/update examples and links to shared component docs.
docs/api/systems/pcs/isupport.md	Updates I-SUPPORT construction example to use LinkSpec + PCS.params_from_links.
docs/api/systems/pcs/index.md	Adds references to shared components and new parameters/optimization guide.
docs/api/systems/index.md	Adds references to shared components and new parameters/optimization guide.
docs/api/systems/gvs/index.md	Updates GVS index to reference shared components and new strain-basis field naming.
docs/api/systems/gvs/gvs.md	Updates GVS quick-start and API refs to shared specs, joint damping, and immutable update patterns.
docs/api/systems/continuum-components.md	Adds a new API page documenting shared continuum components and ownership/mapping semantics.
docs/api/actuation/index.md	Updates actuation docs to reflect link-matrix updates instead of legacy material-field updates.

Suppressed comments (1)

tools/benchmarks/_benchmark_common.py:197

• _pcs_factory creates JAX arrays and converts indexed entries to Python float(...) when building LinkSpecs. This introduces device->host sync overhead inside the benchmark setup and will fail under JIT tracing. Since these values are constant per link here, use pure-Python scalars/lists and avoid float(...) conversions.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 83 out of 83 changed files in this pull request and generated no new comments.

[vdperfetta01]

The merge commit looks well organized, with the new shared components and clearer separation between construction inputs and runtime parameters make the codebase easier to understand and more flexible for future expansion.

After a careful read of the changes I was not able to find any typos or other mistakes. Instead, the code and docs appear consistent and well-written. I would probably just double-check the tests (especially the comparison between gvs and pcs) to certify the consistency with the new harmonization.