newton.Rod#

class newton.Rod(points, *, edges=None, quaternions=None, rest_points=None, rest_quaternions=None, rest_straight=False, 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 initial centerline points, segment topology, and one material frame per segment, plus optional structural-rest points and frames. 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) – Initial 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.

  • rest_points (Sequence[Vec3] | np.ndarray | None) – Optional structural-rest node positions in world space [m], shape (N, 3), sharing the initial topology. Their edge lengths determine capsule geometry, mass properties, anchors, and rigidity discretization. If None, initial points also define rest lengths.

  • rest_quaternions (Sequence[Quat] | np.ndarray | None) – Optional structural-rest material frames in world space [unitless quaternion], shape (E, 4). If None, assembly transports initial material roll to the rest tangents.

  • rest_straight (bool) – Whether to use zero intrinsic bend and twist without changing the initial pose or segment lengths. Requires an ordered chain with at least two segments; mutually exclusive with explicit rest points or frames.

  • closed (bool) – Whether to connect the last segment body to the first with a rod joint. Valid only when edges is omitted and requires at least two segments. If rest_points is provided, its first and last points must coincide, but the initial endpoints may differ. Otherwise, the first and last points must coincide. The final consecutive point pair defines the loop’s closing 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.

Explicit rest arrays are copied and normalized on assignment. Copying or assembling a rod revalidates them against its current topology. compute_frames() updates only initial frames; omitted rest frames follow them during assembly, while explicit rest frames stay unchanged.

static create_straight(start, direction, length, *, segment_count, twist_total=0.0, rest_points=None, rest_quaternions=None, rest_straight=False, 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 rod with a uniformly discretized straight initial centerline.

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.

  • rest_points (Sequence[list[float] | tuple[float, float, float] | vec3f] | ndarray | None) – Optional structural-rest points [m], as in Rod.

  • rest_quaternions (Sequence[list[float] | tuple[float, float, float, float] | quatf] | ndarray | None) – Optional structural-rest frames [unitless quaternion], as in Rod.

  • rest_straight (bool) – Whether to remove intrinsic bend and twist, as in Rod.

  • 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 rod with a straight initial centerline and parallel-transported initial frames.

Raises:

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

Return type:

Rod

__init__(points, *, edges=None, quaternions=None, rest_points=None, rest_quaternions=None, rest_straight=False, 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 initial 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 rest_points: ndarray | None#

Writable structural-rest points [m], shape (N, 3), float32; None uses initial points.

property rest_quaternions: ndarray | None#

Writable rest frames [unitless quaternion], shape (E, 4), float32; None transports initial roll.

rest_straight#

Whether an ordered chain has zero intrinsic bend and twist at structural rest.

property segment_count: int#

Number of rod segments.

property segment_lengths: ndarray#

Initial 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.