Harmonize PCS and GVS parameter models

docs/api/actuation/index.md

@@ -99,10 +99,10 @@ the physics modules to rendering types or styles.
 
 ## Parameter updates
 
-Body parameters keep the existing API:
+Body parameters use top-level or component-specific immutable updates:
 
 ```python
-robot = robot.update_params(young_modulus=new_modulus)
+robot = robot.update_link_params(stiffness=new_stiffness)
 robot = robot.with_params(new_body_params)
 ```
 

docs/api/systems/continuum-components.md

@@ -0,0 +1,204 @@
+# Continuum Robot Components
+
+PCS and GVS use the same public vocabulary for continuum links, cross-sections,
+isotropic materials, and joints. This page describes the physical meaning and
+ownership of those shared components. For construction, immutable replacement,
+and gradient-based identification workflows, see
+[Parameters and Optimization](../../user-guide/parameters-and-optimization.md).
+
+## Model composition
+
+Continuum-system parameters use shallow composition:
+
+```text
+PCSParams / PlanarPCSParams
+└── link: ContinuumLinkParams
+    └── cross_section: CrossSectionParams
+
+GVSParams
+├── link: ContinuumLinkParams
+│   └── cross_section: CrossSectionParams
+└── joint: JointParams
+```
+
+The hierarchy expresses physical ownership rather than a different material
+model for every system. A link owns its geometry, reference strain, mass
+properties, stiffness, and damping. A GVS joint separately owns joint
+stiffness and damping. System-level parameters own the base pose and gravity.
+
+## Cross-sections
+
+`CrossSectionParams.coefficients` is a two-dimensional array with one row per
+link. The static system structure determines how each row is interpreted:
+
+- a scalar dimension defines a constant profile;
+- `LinearProfile(base, tip)` defines a base-to-tip linear profile;
+- rows are zero-padded when different GVS links require different numbers of
+  coefficients.
+
+The supported solid cross-sections are circular, rectangular, and elliptical.
+`CrossSectionGeometry` identifies the family, while shared geometry utilities
+calculate area and second moments of area. Geometry dimensions are finite and
+strictly positive. Shared evaluators and `robot.cross_section_geometry(...)`
+use `[height, width]` for rectangular sections and
+`[semi_major, semi_minor]` for elliptical sections.
+
+`LinkSpec` provides the ergonomic construction interface:
+
+```python
+from soromox.systems import LinearProfile, LinkSpec
+
+circular = LinkSpec.circular(
+    length=0.2,
+    radius=0.012,
+    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],
+)
+
+tapered_rectangle = LinkSpec.rectangular(
+    length=0.25,
+    height=LinearProfile(base=0.03, tip=0.02),
+    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],
+)
+```
+
+PCS currently accepts constant circular links. GVS accepts constant or linear
+circular, rectangular, and elliptical cross-sections.
+
+## Continuum links
+
+`ContinuumLinkParams` stores the canonical numeric values used at runtime:
+
+| Field | Shape | Meaning |
+|-------|-------|---------|
+| `length` | `(N,)` | Link backbone lengths |
+| `density` | `(N,)` | Volumetric mass densities |
+| `reference_strain` | `(N, strain_dimension)` | Stress-free strain fields |
+| `cross_section.coefficients` | `(N, max_coefficients)` | Packed geometry profiles |
+| `stiffness` | `(N, generalized_dimension, generalized_dimension)` | Generalized link stiffness |
+| `damping` | same as `stiffness` | Generalized link damping |
+
+Stiffness and damping are finite symmetric matrices. They are not required to
+be diagonal or positive definite, which permits anisotropic, coupled, fitted,
+and learned constitutive models. Link lengths and densities must be finite and
+strictly positive; reference strains must be finite.
+
+The generalized dimension depends on the system:
+
+| System | Canonical link matrix shape |
+|--------|-----------------------------|
+| Spatial PCS | `(N, 6, 6)` |
+| PlanarPCS | `(N, 3, 3)` |
+| GVS | `(N, max_dof, max_dof)` |
+
+GVS matrices are zero-padded beyond each link's active basis coordinates.
+
+## Isotropic material model
+
+Young's modulus, shear modulus, and material damping are useful construction
+and identification variables, but they are not duplicated in the runtime robot
+parameters. Instead, callers keep an `IsotropicMaterialParams` PyTree:
+
+```python
+from soromox.systems import (
+    IsotropicMaterialParams,
+    shear_modulus_from_poisson_ratio,
+)
+
+young = 1.0e6
+material = IsotropicMaterialParams(
+    young_modulus=young,
+    shear_modulus=shear_modulus_from_poisson_ratio(young, 0.45),
+    material_damping_coefficient=1.0e4,
+)
+```
+
+Each field may be scalar or contain one value per link. Scalar values are
+broadcast when the material is applied. Young's and shear moduli must be finite
+and strictly positive; material damping must be finite and nonnegative.
+
+Geometry, link length, strain basis, rotational scaling, and quadrature are
+projected into unit-response operators. Material matrices are then evaluated
+as
+
+\[
+K_i = E_i K_{i,E} + G_i K_{i,G},
+\qquad
+D_i = \eta_i D_{i,\eta}.
+\]
+
+Equivalently, the unit operators represent the discretized integrals
+
+\[
+K_i = \int B_i(s)^\mathsf{T} C_i(s) B_i(s)\,\mathrm{d}s,
+\qquad
+D_i = \int B_i(s)^\mathsf{T} V_i(s) B_i(s)\,\mathrm{d}s.
+\]
+
+`link_matrices_from_material` evaluates the mapping without modifying the
+robot. `with_isotropic_material` returns a robot containing the resulting
+canonical matrices. It does not store the material PyTree.
+
+Geometry updates refresh the unit-response operators but leave explicitly
+stored matrices unchanged. Reapply `with_isotropic_material` when matrices
+should follow updated material or geometry values. This prevents geometry
+updates from silently overwriting an explicitly supplied constitutive model.
+
+## Joints
+
+GVS segments may start with a fixed, revolute, prismatic, helical,
+cylindrical, planar, spherical, or free joint. `JointSpec` accepts stiffness
+and damping in active joint coordinates. Omitted values create zero matrices.
+
+At runtime, `JointParams` stores both matrices with the same GVS padding as the
+link matrices:
+
+```python
+import jax.numpy as jnp
+
+from soromox.systems import JointSpec
+
+joint = JointSpec.revolute(
+    axis="z",
+    stiffness=jnp.array([[0.3]]),
+    damping=jnp.array([[0.02]]),
+)
+```
+
+The GVS global matrices interleave joint and link contributions before
+projection into active coordinates. PCS has no separate joint component.
+
+## Construction specs, params, and structure
+
+The three object categories have different lifetimes:
+
+| Category | Purpose | Typical examples |
+|----------|---------|------------------|
+| Specs | Convenient user input during construction | `LinkSpec`, `JointSpec`, `GVSSegment`, `StrainBasisSpec` |
+| Params | Dynamic numeric JAX PyTrees | `ContinuumLinkParams`, `JointParams`, `PCSParams`, `GVSParams` |
+| Structure | Static choices affecting layout or compilation | `PCSStructure`, `GVSStructure` |
+
+Specs may contain either isotropic material values or explicit generalized
+matrices. Construction resolves them to one canonical runtime representation.
+Changing numeric params with the same layout supports JAX transformations;
+changing segment count, basis order, active strains, or padding requires
+reconstruction with a new structure.
+
+## API reference
+
+::: soromox.systems.components
+    options:
+      show_root_heading: true
+      show_source: false
+      heading_level: 3
+      group_by_category: true
+      docstring_section_style: table
+      members_order: source

docs/api/systems/gvs/gvs.md

@@ -14,24 +14,42 @@ system-identification workflows.
 
 ## Quick Start
 
+The shared link, cross-section, material, and joint model is described in
+[Continuum Robot Components](../continuum-components.md). For full immutable
+replacement and optimization workflows, see
+[Parameters, Updates, and Optimization](../../../user-guide/parameters-and-optimization.md).
+
 ```python
 import jax.numpy as jnp
 from soromox.systems import (
     GVS,
     GVSSegment,
     JointSpec,
+    LinearProfile,
     LinkSpec,
     StrainBasisSpec,
 )
 
 segment = GVSSegment(
-    link=LinkSpec.circular(E=1e6, nu=0.45, rho=1000.0, eta=1e4, L=0.3, r=0.03),
-    joint=JointSpec.fixed(),
+    link=LinkSpec.rectangular(
+        length=0.3,
+        height=LinearProfile(base=0.03, tip=0.02),
+        width=0.025,
+        density=1000.0,
+        young_modulus=1e6,
+        shear_modulus=3.45e5,
+        material_damping_coefficient=1e4,
+        reference_strain=[0, 0, 0, 1, 0, 0],
+    ),
+    joint=JointSpec.revolute(
+        axis="z",
+        stiffness=jnp.array([[0.3]]),
+        damping=jnp.array([[0.02]]),
+    ),
     basis=StrainBasisSpec(
-        type="monomial",
-        active=[1, 1, 1, 1, 0, 0],
-        orders=[1, 1, 1, 1, 0, 0],
-        xi_ref=[0, 0, 0, 1, 0, 0],
+        type="legendre",
+        strain_selector=("kappa_y", "sigma_x"),
+        basis_order=1,
     ),
     num_gauss_points=5,
 )
@@ -47,14 +65,14 @@ base_transform = robot.forward_kinematics(q, s=robot.segment_end_positions[-1])
 `GVS.from_segments(...)` creates typed `GVSParams` and `GVSStructure`
 internally, so `robot.params` can be optimized or partially replaced later.
 Static structure contains no copied material constants, lengths, joint
-stiffness, or reference strains. For workflows that need the split without
+matrices, or reference strains. For workflows that need the split without
 constructing a robot, use `GVS.params_from_segments(...)`.
 
 ## Segment Specs
 
-- `LinkSpec`: construction input for link geometry, material properties, and length. Its numeric values are copied into `GVSParams.link`; only the cross-section family remains static.
-- `JointSpec`: construction input for joint type and optional axis, plane, pitch, and stiffness. Stiffness is copied into `GVSParams.joint_stiffness`.
-- `StrainBasisSpec`: construction input for basis family, active strain components, basis orders, and reference strain. Reference strain is copied into `GVSParams.reference_strain`.
+- `LinkSpec`: shared construction input for link geometry, reference strain, material properties or explicit generalized matrices, and length.
+- `JointSpec`: shared construction input for joint type, kinematic choices, stiffness, and damping. Matrices are copied into `GVSParams.joint`.
+- `StrainBasisSpec`: GVS-specific basis family, active strain components, and basis orders.
 - `GVSSegment`: combines one link, one preceding joint, one strain basis, and `num_gauss_points`.
 
 ## Basis And Joint Names
@@ -75,7 +93,31 @@ After construction, GVS exposes canonical runtime arrays:
 - `dofs_per_segment`, `num_dofs`, `num_padded_dofs`, `active_dof_map`
 - `B_joint`, `B_Xs`, `B_Z1`, `B_Z2`
 - `xi_ref_joint`, `xi_ref_Xs`, `xi_ref_Z1`, `xi_ref_Z2`
-- `mass_matrices`, `stiffness_matrices`, `damping_matrices`, `joint_stiffness`
+- per-quadrature `mass_matrices`
+- canonical `params.link.stiffness`, `params.link.damping`
+- canonical `params.joint.stiffness`, `params.joint.damping`
+
+## Immutable updates
+
+```python
+robot = robot.update_link_params(
+    stiffness=1.1 * robot.params.link.stiffness,
+    damping=0.9 * robot.params.link.damping,
+)
+robot = robot.update_joint_params(
+    damping=1.2 * robot.params.joint.damping,
+)
+
+replacement = robot.params.replace(
+    link=robot.params.link.replace(
+        density=1.05 * robot.params.link.density,
+    ),
+    joint=robot.params.joint.replace(
+        stiffness=1.1 * robot.params.joint.stiffness,
+    ),
+)
+robot = robot.with_params(replacement)
+```
 
 ## When To Use GVS vs PCS
 
@@ -102,13 +144,13 @@ After construction, GVS exposes canonical runtime arrays:
       show_source: false
       heading_level: 3
 
-::: soromox.systems.gvs.specs.LinkSpec
+::: soromox.systems.components.links.LinkSpec
     options:
       show_root_heading: true
       show_source: false
       heading_level: 3
 
-::: soromox.systems.gvs.specs.JointSpec
+::: soromox.systems.components.joints.JointSpec
     options:
       show_root_heading: true
       show_source: false

docs/api/systems/gvs/index.md

@@ -2,6 +2,11 @@
 
 This section covers continuum soft robots modeled with the Geometric Variable Strain (GVS) approach.
 
+GVS uses the shared continuum link, cross-section, isotropic material, and joint
+model described in [Continuum Robot Components](../continuum-components.md).
+See [Parameters, Updates, and Optimization](../../../user-guide/parameters-and-optimization.md)
+for construction, replacement, and identification workflows.
+
 ## Overview
 
 GVS systems generalize PCS by allowing arbitrary strain basis functions instead of piecewise constant assumptions. A model is assembled from `GVSSegment` entries, where each segment contains a `LinkSpec`, `JointSpec`, `StrainBasisSpec`, and `num_gauss_points`.
@@ -13,7 +18,7 @@ GVS systems generalize PCS by allowing arbitrary strain basis functions instead
 | `GVSSegment` | Complete declaration of one GVS segment |
 | `LinkSpec` | Link geometry, material properties, and length |
 | `JointSpec` | Preceding joint type and optional joint parameters |
-| `StrainBasisSpec` | Strain basis family, active components, orders, and reference strain |
+| `StrainBasisSpec` | Strain basis family, active components, and orders |
 
 ## Basis Functions
 

docs/api/systems/index.md

@@ -43,6 +43,13 @@ The `SoftRobot` class extends `DynamicalSystem` with interfaces specific to soft
 
 ## Common Components
 
+PCS and GVS share continuum-link, cross-section, isotropic-material, and joint
+components. Their physical meaning, ownership, matrix shapes, and construction
+specifications are described in
+[Continuum Robot Components](continuum-components.md). Practical immutable
+replacement and gradient-based identification examples are in
+[Parameters, Updates, and Optimization](../../user-guide/parameters-and-optimization.md).
+
 ### SystemState
 
 The `SystemState` class is a container for the robot state used throughout SoRoMoX for simulation, control, and analysis.

docs/api/systems/pcs/index.md

@@ -2,6 +2,11 @@
 
 This section covers continuum soft robots modeled using the Piecewise Constant Strain (PCS) approach based on discrete Cosserat rod theory.
 
+PCS uses the shared link, cross-section, and material model described in
+[Continuum Robot Components](../continuum-components.md). See
+[Parameters, Updates, and Optimization](../../../user-guide/parameters-and-optimization.md)
+for construction, replacement, and identification workflows.
+
 ## Overview
 
 PCS systems model continuum soft robots by dividing them into segments, each with constant strain. This approach provides: