newton.Rod#

class newton.Rod(points, *, edges=None, quaternions=None, closed=False, radius=None, youngs_modulus=None, poissons_ratio=None, shear_modulus=None, stretch_rigidity=None, shear_rigidity=None, bend_rigidity=None, twist_rigidity=None)[source]#

Bases: object

Represents discrete rod input for model construction.

A rod stores prepared centerline points, segment topology, and one material frame per segment. It may additionally store a capsule/cross-section radius and either uniform isotropic material properties or a complete set of uniform section rigidities. Geometry and constitutive data remain writable. Use newton.ModelBuilder.add_rod() to create the corresponding bodies and rod joints.

Parameters:

  • points (Sequence[Vec3] | np.ndarray) – Centerline node positions in world space [m], shape (N, 3).

  • edges (Sequence[tuple[int, int]] | np.ndarray | None) – Optional simple-graph segment endpoint indices, shape (E, 2). Self-edges and duplicate undirected edges are rejected. If omitted, consecutive points form an ordered chain.

  • quaternions (Sequence[Quat] | np.ndarray | None) – Optional per-segment material frames in world space, shape (E, 4). If omitted, an ordered chain uses parallel transport; other explicit topology aligns each frame’s local +Z axis independently to its edge.

  • closed (bool) – Whether an implicit ordered chain closes its last segment body back to its first with a rod joint. Valid only when edges is omitted and requires at least two segments with coincident first and last points, so the closing span is represented by a segment body.

  • radius (float | None) – Optional capsule radius [m]. If omitted, assembly uses 0.1 m. With elastic material inputs, this also defines the circular cross-section used to derive section rigidities and is required. Directly authored rigidities already include the cross-section and are not rescaled by this value.

  • youngs_modulus (float | None) – Optional Young’s modulus E [Pa]. Supplying material requires radius and exactly one of poissons_ratio and shear_modulus.

  • poissons_ratio (float | None) – Optional Poisson’s ratio nu.

  • shear_modulus (float | None) – Optional shear modulus G [Pa].

  • stretch_rigidity (float | None) – Optional axial rigidity EA [N]. If supplied, all four section rigidities are required. Mutually exclusive with elastic material inputs.

  • shear_rigidity (float | None) – Optional effective transverse shear rigidity kGA [N]. Mutually exclusive with elastic material inputs.

  • bend_rigidity (float | None) – Optional bending rigidity EI [N·m²]. Mutually exclusive with elastic material inputs.

  • twist_rigidity (float | None) – Optional torsional rigidity GJ [N·m²]. Mutually exclusive with elastic material inputs.

Raises:

ValueError – If the geometry, frames, or constitutive inputs are invalid or mutually inconsistent.

Note

Material-derived transverse shear follows the OpenUSD deformable-body treatment for a solid circular section, using kGA with k = 0.9. See newton.ModelBuilder.add_rod() for rigidity discretization, direct stiffness and damping controls, and topology limitations.

Assigning a complete points or edges array validates its shape and normalizes its dtype and memory layout; in-place array edits bypass these property setters. When edges were omitted, changing the number of points regenerates the consecutive chain edges. Assigning edges explicitly disables that automatic update. Neither operation recomputes quaternions. After changing points or edges, call compute_frames() when the material frames should follow the updated geometry.

static create_straight(start, direction, length, *, segment_count, twist_total=0.0, radius=None, youngs_modulus=None, poissons_ratio=None, shear_modulus=None, stretch_rigidity=None, shear_rigidity=None, bend_rigidity=None, twist_rigidity=None)#

Create a uniformly discretized straight rod.

Parameters:

  • start (list[float] | tuple[float, float, float] | vec3f) – First centerline point in world space [m].

  • direction (list[float] | tuple[float, float, float] | vec3f) – World-space direction. It is normalized before use, so its magnitude is ignored.

  • length (float) – Total centerline length [m], divided evenly among the segments.

  • segment_count (int) – Number of equal-length rod segments. The rod contains segment_count + 1 points.

  • twist_total (float) – Twist of the final segment frame relative to untwisted parallel transport [rad]. The value is distributed in segment_count equal increments, including the first frame, and is not retained after construction.

  • radius (float | None) – Optional circular-section and capsule radius [m].

  • youngs_modulus (float | None) – Optional Young’s modulus E [Pa].

  • poissons_ratio (float | None) – Optional Poisson’s ratio nu.

  • shear_modulus (float | None) – Optional shear modulus G [Pa].

  • stretch_rigidity (float | None) – Optional axial rigidity EA [N]. If supplied, all four section rigidities are required. Mutually exclusive with elastic material inputs.

  • shear_rigidity (float | None) – Optional effective transverse shear rigidity kGA [N]. Mutually exclusive with elastic material inputs.

  • bend_rigidity (float | None) – Optional bending rigidity EI [N·m²]. Mutually exclusive with elastic material inputs.

  • twist_rigidity (float | None) – Optional torsional rigidity GJ [N·m²]. Mutually exclusive with elastic material inputs.

Returns:

A straight rod with parallel-transported material frames.

Raises:

ValueError – If the geometry, twist, material, or rigidity inputs are invalid.

Return type:

Rod

__init__(points, *, edges=None, quaternions=None, closed=False, radius=None, youngs_modulus=None, poissons_ratio=None, shear_modulus=None, stretch_rigidity=None, shear_rigidity=None, bend_rigidity=None, twist_rigidity=None)#
compute_frames(*, twist_total=0.0)#

Recompute segment frames from the current centerline geometry.

Ordered chains use parallel transport and divide twist_total into equal per-segment increments. Other explicit topology uses independent edge-aligned frames and does not define graph-wide total twist.

Parameters:

twist_total (float) – Twist of the final ordered-chain frame relative to untwisted parallel transport [rad]. Must be zero unless the topology is an ordered chain. The value is not retained.

Returns:

None.

Raises:

ValueError – If the current geometry or twist_total is invalid, or if nonzero total twist is requested for non-chain topology.

Return type:

None

copy()#

Return an independent copy of this rod.

bend_rigidity#

Uniform bending rigidity EI [N·m²], or None.

closed#

Whether the implicit ordered chain closes its last segment body back to its first with a rod joint.

property edges: ndarray#

Writable segment endpoint indices, shape (E, 2), int32.

property point_count: int#

Number of centerline points.

property points: ndarray#

Writable centerline node positions in world space [m], shape (N, 3), float32.

poissons_ratio#

Uniform Poisson’s ratio nu, or None.

property quaternions: ndarray#

Writable normalized segment frames in world space, shape (E, 4), float32.

radius#

Capsule radius [m], or None to use the builder default.

property segment_count: int#

Number of rod segments.

property segment_lengths: ndarray#

Current length of every rod segment [m], shape (E,).

shear_modulus#

Uniform shear modulus G [Pa], or None.

shear_rigidity#

Uniform effective transverse shear rigidity kGA [N], or None.

stretch_rigidity#

Uniform axial rigidity EA [N], or None.

twist_rigidity#

Uniform torsional rigidity GJ [N·m²], or None.

youngs_modulus#

Uniform Young’s modulus E [Pa], or None.