newton.utils.create_cable_stiffness_from_elastic_moduli#

newton.utils.create_cable_stiffness_from_elastic_moduli(youngs_modulus: float, radius: float, segment_length: float) → tuple[float, float][source]#
newton.utils.create_cable_stiffness_from_elastic_moduli(youngs_modulus: float, radius: float, segment_length: float, *, poissons_ratio: float) → CableStiffness
newton.utils.create_cable_stiffness_from_elastic_moduli(youngs_modulus: float, radius: float, segment_length: float, *, shear_modulus: float) → CableStiffness

Create per-joint rod/cable stiffness from elastic moduli.

For a circular cross-section, this computes material stiffnesses and converts them to the per-joint stiffness values expected by ModelBuilder.add_rod() and ModelBuilder.add_rod_graph():

  • stretch = E * A / L [N/m]

  • bend    = E * I / L [N*m / rad]

  • twist   = G * J / L [N*m / rad] (returned only when poissons_ratio or shear_modulus is supplied)

where A = pi * r^2, I = pi * r^4 / 4 (area moment of inertia about a diameter), J = pi * r^4 / 2 (polar moment of area), and L = segment_length. For an isotropic material with Poisson’s ratio nu, the shear modulus is G = E / (2 * (1 + nu)).

No separate transverse shear stiffness is returned. The split cable API defaults shear_stiffness to stretch_stiffness when omitted; pass an explicit shear_stiffness if that default is not desired. The shear_modulus keyword supplies G for torsion/twist only.

The return shape mirrors what the caller asks for:

  • create_cable_stiffness_from_elastic_moduli(E, r, L) returns the plain 2-tuple (stretch, bend) – twist is not derivable from E alone, so it is omitted. Suitable for stretch-only or bend-only rods, or when the caller manages twist_stiffness separately.

  • Supplying poissons_ratio or shear_modulus switches the return to CableStiffness with the additional twist term. The result both unpacks as a 3-tuple and exposes named fields .stretch, .bend, .twist.

When the 2-tuple is passed through the builder without an explicit twist_stiffness, twist defaults to bend (the combined-stiffness model). For material-consistent torsion twist / bend = G * J / (E * I) = 1 / (1 + nu), pass poissons_ratio or shear_modulus to get the third term.

Parameters:

  • youngs_modulus – Young’s modulus E [Pa = N/m^2]. Must be finite and >= 0.

  • radius – Rod/cable radius r [m]. Must be finite and > 0.

  • segment_length – Per-joint rest length L [m]. Must be finite and > 0.

  • poissons_ratio – Poisson’s ratio nu used to compute the shear modulus G = E / (2 * (1 + nu)). Keyword-only. Must satisfy -1 < nu < 0.5 for a stable isotropic 3D material. Mutually exclusive with shear_modulus.

  • shear_modulus – Shear modulus G [Pa]. Keyword-only. Mutually exclusive with poissons_ratio.

Returns:

2-tuple (stretch, bend) when neither poissons_ratio nor shear_modulus is supplied; otherwise a CableStiffness NamedTuple (stretch, bend, twist).

Raises:

ValueError – if any of youngs_modulus, radius, segment_length, poissons_ratio, or shear_modulus is non-finite or out of range, or if both poissons_ratio and shear_modulus are supplied.