菜单
Joint topology, kinematic constraints, and elastic links for MBS. Covers revolute, prismatic, motors, springs, axis-aware joint frames, general revolute hinge alignment (local +Z to physical axis) plus special planar cases, and correct topology for mechanisms with ground pivots and fixed guides.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Entry point for FSI-coupled hybrid plans (plan_type=fsi_in_scene) — any scene combining SPH fluid (water tanks, dam-break, wave channels) with multi-body dynamics, optionally with a wheeled vehicle. Pick this over mbs_in_scene whenever the plan involves a fluid domain (scene_objects with domain_type starting "sph_") or an FSI body registration (scene_objects with fsi_registration set). Routes to fsi/sph (always), veh/wheeled_vehicle (when vehicle present), and enforces FSI-specific invariants distinct from generic mbs_in_scene rigid scenes.
Entry point for rigid-body hybrid plans (plan_type=mbs_in_scene) combining a robot or vehicle with scene assets — NO fluid coupling. Routes to the correct domain skills and defines only high-level invariants. Use core/fsi_in_scene instead when the plan involves SPH fluid or FSI body registration.
Entry point for pure multi-body simulation plans (plan_type=mbs). Routes the agent to the correct mechanics, system, and camera skills and defines only high-level invariants.
Entry point for static scene plans (plan_type=scene). Routes the agent to the correct scene, system, and camera skills and defines only high-level invariants.
Set up SPH-based Fluid-Structure Interaction (FSI): create ChFsiFluidSystemSPH and ChFsiSystemSPH, configure fluid and SPH parameters, seed fluid particles with hydrostatic initialization, add container BCE boundary markers, register floating rigid bodies, optionally couple with a wheeled vehicle, and advance with sysFSI.DoStepDynamics(dT).
Translate a `geometry_relations` entry from the plan into correct PyChrono coordinate code. Read this whenever the plan declares a relation_name you have not previously encoded, and especially BEFORE writing SetPos / camera placement for any body that participates in a multi-body geometric constraint. Each subsection below is one canonical pattern named exactly as it appears in `plan.geometry_relations[i].relation_name`.
| name | topology |
| description | Joint topology, kinematic constraints, and elastic links for MBS. Covers revolute, prismatic, motors, springs, axis-aware joint frames, general revolute hinge alignment (local +Z to physical axis) plus special planar cases, and correct topology for mechanisms with ground pivots and fixed guides. |
| compatibility | pychrono >= 8.0 |
| metadata | {"domain":"mbs"} |
Connect bodies with kinematic constraints, motors, and springs without mixing up topology or frame semantics. The core rule is: identify the physical degree-of-freedom axis first, then choose joint type and frame orientation so the joint axis matches that physical intent.
For quaternion and rotation construction details, see ../quaternions/SKILL.md. For planar XY body-orientation conventions, see ../body_creation/SKILL.md.
For every connection, answer these questions in order:
Then choose the joint:
Do not infer joint type from a copied code pattern. Infer it from the mechanism.
When a body rotates about a fixed ground pivot and is actuated:
joint_pivot = chrono.ChLinkLockRevolute()
frame_origin = chrono.ChFramed(chrono.ChVector3d(0, 0, 0), chrono.QUNIT)
joint_pivot.Initialize(rotating_body, ground, frame_origin)
sys.AddLink(joint_pivot)
motor = chrono.ChLinkMotorRotationTorque()
motor.Initialize(rotating_body, ground, frame_origin)
motor.SetTorqueFunction(chrono.ChFunctionSine(amplitude, frequency))
sys.AddLink(motor)
# WRONG: motor only
motor.Initialize(rotating_body, ground, chrono.ChFramed(chrono.ChVector3d(0, 0, 0)))
sys.AddLink(motor)
If a body slides along a fixed rail, the prismatic belongs between the slider and ground, not between the slider and another moving body.
guide_axis = chrono.ChVector3d(1, 0, 0) # example only
guide_pos = chrono.ChVector3d(guide_x, guide_y, guide_z)
frame_prismatic = chrono.ChFramed()
frame_prismatic.SetPos(guide_pos)
frame_prismatic.SetRot(guide_rotation_that_maps_frame_Z_to_guide_axis)
joint_slider_ground = chrono.ChLinkLockPrismatic()
joint_slider_ground.Initialize(slider, ground, frame_prismatic)
sys.AddLink(joint_slider_ground)
When a connecting rod attaches to a slider that already moves on a fixed guide:
Do not replace the rod-slider pin with a prismatic. That changes the mechanism.
Use chrono.ChLinkLockRevolute() as the default revolute implementation for these MBS skills and demos.
# CORRECT
joint = chrono.ChLinkLockRevolute()
# WRONG for this skill family
joint = chrono.ChLinkRevolute()
Before finalizing a crank-slider or similar fixed-guide mechanism, confirm all of these are present:
Do not reuse a frame rotation from one joint type just because the point is the same.
If you change a joint from prismatic to revolute, recompute the frame orientation from the hinge axis requirement. Do not keep the old guide-axis rotation by default.
Engine convention: ChLinkLockRevolute uses the joint ChFramed local +Z as the hinge axis (relative rotation is about that axis). The general rule is independent of gravity or world axes: choose a quaternion q for ChFramed(pivot_pos, q) such that, in world coordinates, local +Z after the frame rotation coincides with the physical hinge direction (a unit vector axis_hat).
General case (always start here):
axis_hat in the world frame (from the mechanism geometry, not from a copied code snippet).q_align that maps joint local +Z onto axis_hat (same geometric problem as aligning a prismatic’s sliding axis—only the physical meaning differs). Use chrono.QuatFromAngleAxis when the axis is a simple rotation from +Z, combine chrono.Q_ROTATE_* helpers when they apply, or build a rotation from two vectors / axis-angle as in ../quaternions/SKILL.md.joint.Initialize(body_a, body_b, chrono.ChFramed(pivot_pos, q_align)).# General pattern: q_align maps local +Z onto the physical hinge direction in world frame
q_align = rotation_z_to_axis_hat # construct from axis_hat; see ../quaternions/SKILL.md
joint = chrono.ChLinkLockRevolute()
joint.Initialize(body_a, body_b, chrono.ChFramed(pivot_pos, q_align))
sys.AddLink(joint)
Coordinate consistency checklist:
Q_ROTATE_* without verifying the hinge.Special cases (reminders):
| Situation | Physical hinge axis (typical) | Frame rotation (typical) |
|---|---|---|
| Identity / default frame | World +Z | chrono.QUNIT (local +Z = world +Z) |
| Planar XY in-world, gravity −Y, in-plane motion | World +Z (normal to XY) | chrono.QUNIT is common in demos |
| Planar XZ in-world, gravity −Z, in-plane swing | World ±Y (normal to XZ) | Not QUNIT; e.g. QuatFromAngleAxis(chrono.CH_PI_2, chrono.VECT_X) so local +Z aligns with Y |
| Hinge along world X or Y explicitly | ±X or ±Y | QuatFromAngleAxis or Q_ROTATE_* from ../quaternions/SKILL.md—never assume QUNIT |
| Tilted or non-cardinal hinge | Arbitrary axis_hat | Build q_align from axis_hat (general case); do not assume QUNIT |
Examples (special cases as code):
# Special: planar XY, hinge about world Z (local +Z already world +Z)
joint = chrono.ChLinkLockRevolute()
joint.Initialize(body_a, body_b, chrono.ChFramed(pivot_pos, chrono.QUNIT))
sys.AddLink(joint)
# Special: XZ plane swing, gravity along -Z — hinge must be world ±Y, not +Z
q_hinge_y = chrono.QuatFromAngleAxis(chrono.CH_PI_2, chrono.VECT_X)
joint = chrono.ChLinkLockRevolute()
joint.Initialize(body_a, body_b, chrono.ChFramed(pivot_pos, q_hinge_y))
sys.AddLink(joint)
Do not default to chrono.QUNIT for an XZ pendulum with gravity along −Z: the torque from gravity in the swing plane will not match a hinge about +Z.
# WRONG: copied from a prismatic guide example without checking hinge axis
joint = chrono.ChLinkLockRevolute()
joint.Initialize(body_a, body_b, chrono.ChFramed(pivot_pos, chrono.Q_ROTATE_Z_TO_X))
sys.AddLink(joint)
ChLinkLockPrismatic uses the frame's local +Z as the sliding axis. Therefore:
chrono.Q_ROTATE_Z_TO_X is only the common X-guide example, not a universal default.
# Example: guide along global X
joint = chrono.ChLinkLockPrismatic()
joint.Initialize(slider, ground, chrono.ChFramed(pos, chrono.Q_ROTATE_Z_TO_X))
sys.AddLink(joint)
# Example: guide along arbitrary axis_hat
joint = chrono.ChLinkLockPrismatic()
joint.Initialize(slider, ground, chrono.ChFramed(pos, rotation_z_to_axis_hat))
sys.AddLink(joint)
For linkages such as crank-rod or rod-slider, the body-local Initialize(body1, body2, True, frame1, frame2) form is preferred because each marker is defined in the body it belongs to.
joint = chrono.ChLinkLockRevolute()
joint.Initialize(body1, body2, True, frame1_local_to_body1, frame2_local_to_body2)
sys.AddLink(joint)
ChLinkLockLock) for Fixed ConnectionsUse ChLinkLockLock when two bodies must move together as a single unit — they share the same position and rotation. Common use: structural axle or connector that visually links two bodies but has no independent motion.
3-arg form:
joint = chrono.ChLinkLockLock()
joint.Initialize(body1, body2, chrono.ChFramed(connection_point, q_alignment))
sys.AddLink(joint)
The connection_point is interpreted as a body-local coordinate on body1.
Pattern — Axle connecting two bodies:
# body_a: one end of axle (e.g., at pivot)
# body_b: other end (e.g., disc at far end of axle)
# axle_pos: midpoint between body_a and body_b attachment points
axle.SetPos(axle_pos)
# Lock joint at body-local origin on axle, connecting to body_b
axle_to_bodyb = chrono.ChLinkLockLock()
axle_to_bodyb.Initialize(axle, body_b, chrono.ChFramed(chrono.ChVector3d(0, 0, 0), chrono.QUNIT))
sys.AddLink(axle_to_bodyb)
Rule: When using ChLinkLockLock, both bodies must be created and positioned first. The joint enforces that body1.frame_origin = body2.frame_origin in world coordinates. If the declared frame positions don't match the actual body positions, the constraint will be impossible and the simulation will diverge.
spring = chrono.ChLinkTSDA()
spring.Initialize(body1, body2, True,
chrono.ChVector3d(0, 0, 0),
chrono.ChVector3d(-1, 0, 0))
spring.SetRestLength(rest_length)
spring.SetSpringCoefficient(spring_k)
spring.SetDampingCoefficient(damping_c)
sys.AddLink(spring)
Spring (ChLinkTSDA):
spring = chrono.ChLinkTSDA()
spring.Initialize(body1, body2, True,
chrono.ChVector3d(0, 0, 0),
chrono.ChVector3d(-1, 0, 0))
spring.SetRestLength(rest_length)
spring.SetSpringCoefficient(spring_k)
spring.SetDampingCoefficient(damping_c)
sys.AddLink(spring)
# MUST add visual shape to the LINK (not a body)
spring.AddVisualShape(chrono.ChVisualShapeSpring(coil_radius, resolution, turns))
Rule: Visual shapes on links (springs, dampers) must be added to the link object itself, not to any body.
Rod / Axle between two bodies:
# Method A: ChBody with cylinder visual (if rod has mass/inertia)
rod = chrono.ChBody()
rod.SetMass(mass)
rod.SetInertiaXX(chrono.ChVector3d(1e-6, 1e-6, 1e-6))
rod.SetFixed(True)
sys.AddBody(rod)
cyl = chrono.ChVisualShapeCylinder(radius, length)
rod.AddVisualShape(cyl, chrono.ChFramed(chrono.VNULL, chrono.QuatFromAngleY(chrono.CH_PI_2)))
# Method B: ChVisualShapeLine for thin rod/cable (no mass)
rod_vis = chrono.ChVisualShapeLine()
rod_vis.SetLineGeometry(chrono.ChLineSegment(pos1, pos2))
rod_vis.SetColor(chrono.ChColor(0.3, 0.3, 0.3))
body1.AddVisualShape(rod_vis) # attach to either body
Visualization Checklist — All Structural Bodies:
Before finishing body creation, confirm ALL of these are visualized:
Common mistake: Creating bodies and joints but forgetting to add visual shapes for axle shafts, support posts, or other "minor" structural elements that are not the main moving bodies.
Spring-damper chains are stiff systems that require proper solver settings to remain stable:
# Configure solver for spring stability
sys.SetSolverType(chrono.ChSolver.Type_PSOR)
solver = sys.GetSolver().AsIterative()
solver.SetMaxIterations(100)
solver.SetTolerance(1e-10)
solver.EnableWarmStart(True) # Critical for spring convergence
Why warm start matters: Without it, the solver starts each timestep from scratch. With warm start (EnableWarmStart(True)), the solver uses the previous timestep's solution as an initial guess, which dramatically improves convergence for spring systems.
ChLinkLockSpherical has two main initialization forms:
3-arg form (used in demos):
joint = chrono.ChLinkLockSpherical()
joint.Initialize(body1, body2, chrono.ChFramed(connection_point))
# connection_point is in body1's body-local coordinates
# The frame on body2 is automatically aligned to the same world point
5-arg form (explicit relative frames):
joint.Initialize(body1, body2, True, # rel_frames=True
chrono.ChFramed(local_point_on_body1), # point in body1's local frame
chrono.ChFramed(local_point_on_body2)) # point in body2's local frame
# Explicitly specifies where on each body the joint connects
Use 5-arg when: The connection points matter for geometry (e.g., anchor points not at body center).
Common mistake: Using world-space coordinates instead of body-local coordinates in the frame, causing the joint to connect at wrong positions.
If the mechanism has no contact and is fully described by joints, springs, and motors, do not call sys.SetCollisionSystemType().
If sys.GetConstraintViolation() is not directly usable in your logging path, log a derived scalar or 0.0; do not block the whole simulation on debug logging.
ChLinkRevolute instead of the team's ChLinkLockRevolute conventionQ_ROTATE_Z_TO_X from a prismatic example into a revolute without checking the hinge axisQ_ROTATE_Z_TO_X as the only valid prismatic rotation instead of an X-axis examplechrono.QUNIT for a revolute when the mechanism swings in the XZ plane with gravity along −Z (hinge should be ±Y, not +Z; rotate the joint frame per Rule 8)chrono.QUNIT for a revolute without first defining the physical hinge axis_hat and aligning joint local +Z to it (Rule 8 general case—QUNIT is only correct when axis_hat is +Z)ChBodyEasySphere instead of density (results in wrong mass and physics explosion)(1, 1, 1) for sphere inertia instead of correct formula (2/5)*m*r²P_A and body B is at P_B, and a joint declares a frame at F_A in A's local coords and F_B in B's local coords, then P_A + Rotate(F_A) must equal P_B + Rotate(F_B) in world space. A mismatch causes the physics solver to impose impossible constraints, leading to explosion or divergence.allowed_classes:
allowed_methods:
allowed_constants:
allowed_utils: