API reference¶
This page documents the public symbols exported by kimech.
Core model¶
- class kimech.Mechanism(name=None)¶
Declarative model of a planar rigid-body mechanism.
- Parameters:
name (str | None)
- mobility()¶
Return the planar lower-pair structural mobility estimate.
- Return type:
int
- topology()¶
Return a structural topology snapshot of the mechanism.
- Return type:
- validate()¶
Return a structural consistency report for the mechanism.
- Return type:
- class kimech.Link(mechanism, name)¶
A mobile planar rigid body with an arbitrary local reference frame.
- Parameters:
mechanism (Mechanism)
name (str)
- class kimech.Ground(mechanism)¶
The unique fixed body defining a mechanism’s global frame.
- Parameters:
mechanism (Mechanism)
- class kimech.Point(name, body, _coordinates)¶
A named point rigidly attached to a link or to ground.
- property local: ndarray¶
Return a copy of the point coordinates in the owning body frame.
- class kimech.RevoluteJoint(point_a, point_b, name=None)¶
Planar revolute joint joining two points on distinct bodies.
Driver and solve¶
- class kimech.KinematicDriver(joint, *, position, velocity=None, acceleration=None)¶
Prescribe one joint natural coordinate and optional time derivatives.
Kimech 0.6.0 initially supports the natural coordinate of one revolute or prismatic joint. The driver stores kinematic data only; physical sample times, numerical continuation, and solver configuration belong elsewhere.
- Parameters:
joint (_Joint)
- property acceleration: float | ndarray | None¶
Return prescribed acceleration data, if available.
- property is_scalar: bool¶
Return whether the prescribed position was supplied as a scalar.
- property joint: RevoluteJoint | PrismaticJoint¶
Return the joint whose natural coordinate is prescribed.
- property position: float | ndarray¶
Return the prescribed position scalar or a safe history copy.
- property sample_count: int¶
Return the number of requested position samples.
- property velocity: float | ndarray | None¶
Return prescribed velocity data, if available.
- kimech.solve(mechanism, *, driver, initial_guess, time=None)¶
Solve position and, when requested, differential kinematics.
- Parameters:
mechanism (Mechanism)
driver (KinematicDriver)
- Return type:
Results¶
- class kimech.KinematicSolution(mechanism, driver, coordinates, *, coordinate_velocities=None, coordinate_accelerations=None, time=None, diagnostics=None)¶
An ordered sequence of accepted mechanism configurations.
- Parameters:
mechanism (Mechanism)
driver (KinematicDriver)
coordinates (Sequence[Sequence[float]] | np.ndarray)
coordinate_velocities (Sequence[Sequence[float]] | np.ndarray | None)
coordinate_accelerations (Sequence[Sequence[float]] | np.ndarray | None)
time (Sequence[float] | np.ndarray | None)
diagnostics (SolveDiagnostics | None)
- body_accelerations(body)¶
Return body acceleration history with shape
(N, 3).
- body_poses(body)¶
Return body pose history with shape
(N, 3).
- body_velocities(body)¶
Return body velocity history with shape
(N, 3).
- property coordinate_accelerations: ndarray¶
Return a safe copy of the generalized acceleration matrix.
- property coordinate_velocities: ndarray¶
Return a safe copy of the generalized velocity matrix.
- property coordinates: ndarray¶
Return a safe copy of the generalized coordinate matrix.
- property diagnostics: SolveDiagnostics | None¶
Return numerical solve diagnostics, if available.
- property driver: KinematicDriver¶
Return the prescribed kinematic driver snapshot.
- property has_acceleration: bool¶
Return whether generalized acceleration state is available.
- property has_velocity: bool¶
Return whether generalized velocity state is available.
- joint_accelerations(joint)¶
Return natural joint acceleration for all configurations.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
ndarray
- joint_coordinates(joint)¶
Return the natural joint coordinate for all configurations.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
ndarray
- joint_velocities(joint)¶
Return natural joint velocity for all configurations.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
ndarray
- point_accelerations(point)¶
Return global point accelerations for all configurations.
- Parameters:
point (Point)
- Return type:
ndarray
- point_positions(point)¶
Return global point positions for all configurations.
- Parameters:
point (Point)
- Return type:
ndarray
- point_velocities(point)¶
Return global point velocities for all configurations.
- Parameters:
point (Point)
- Return type:
ndarray
- property time: ndarray | None¶
Return physical sample times, if available.
- class kimech.Configuration(mechanism, coordinates, *, coordinate_velocities=None, coordinate_accelerations=None, driver=None, time=None)¶
One valid kinematic configuration of a planar mechanism.
- Parameters:
mechanism (Mechanism)
coordinates (Sequence[float] | np.ndarray)
coordinate_velocities (Sequence[float] | np.ndarray | None)
coordinate_accelerations (Sequence[float] | np.ndarray | None)
driver (KinematicDriver | None)
time (float | None)
- body_acceleration(body)¶
Return
(ax, ay, alpha)for a mechanism body.
- body_pose(body)¶
Return
(x, y, theta)for a mobile link or the identity for ground.
- body_velocity(body)¶
Return
(vx, vy, omega)for a mechanism body.
- property coordinate_accelerations: ndarray¶
Return a safe copy of the generalized acceleration vector.
- property coordinate_velocities: ndarray¶
Return a safe copy of the generalized velocity vector.
- property coordinates: ndarray¶
Return a safe copy of the generalized coordinate vector.
- property driver: KinematicDriver | None¶
Return the prescribed kinematic driver for this configuration.
- property has_acceleration: bool¶
Return whether generalized acceleration state is available.
- property has_velocity: bool¶
Return whether generalized velocity state is available.
- joint_acceleration(joint)¶
Return the second time derivative of a joint’s natural coordinate.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
float
- joint_coordinate(joint)¶
Return the natural, unwrapped coordinate of a mechanism joint.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
float
- joint_velocity(joint)¶
Return the time derivative of a joint’s natural coordinate.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
float
- point_acceleration(point)¶
Return the global acceleration of a point attached to a mechanism body.
- Parameters:
point (Point)
- Return type:
ndarray
- point_position(point)¶
Return the global position of a point attached to a mechanism body.
- Parameters:
point (Point)
- Return type:
ndarray
- point_velocity(point)¶
Return the global velocity of a point attached to a mechanism body.
- Parameters:
point (Point)
- Return type:
ndarray
- property time: float | None¶
Return the physical sample time associated with this configuration.
Diagnostics and validation¶
- class kimech.SolveDiagnostics(condition_numbers, min_singular_values, ranks, *, subdivision_counts=None, strategies=None, corrector_attempts=None, residual_norms=None)¶
Numerical diagnostics recorded for an ordered kinematic solution.
Jacobian metrics refer to Kimech’s dimensionless scaled constraint Jacobian, so they are intended to be comparable across consistent choices of linear units.
- property condition_numbers: ndarray¶
Return scaled-Jacobian condition numbers.
- property corrector_attempts: ndarray | None¶
Return nonlinear position-corrector attempts per requested sample.
- property min_singular_values: ndarray¶
Return the smallest singular value of the scaled Jacobian.
- property ranks: ndarray¶
Return numerical ranks of the scaled Jacobian.
- property residual_norms: ndarray | None¶
Return final scaled position residual infinity norms.
- property strategies: ndarray | None¶
Return the accepted position-solve strategy for each requested sample.
- property subdivision_counts: ndarray | None¶
Return accepted internal subdivision counts for each requested sample.
- summary()¶
Return descriptive extrema and solve-effort counts for this history.
- Return type:
- class kimech.SolveDiagnosticSummary(sample_count, worst_condition_index, worst_condition_number, minimum_singular_value_index, minimum_singular_value, minimum_rank, max_subdivision_index, max_subdivision_count, max_corrector_attempt_index, max_corrector_attempts, strategy_counts)¶
Compact descriptive summary of a solve-diagnostics history.
- Parameters:
sample_count (int)
worst_condition_index (int | None)
worst_condition_number (float | None)
minimum_singular_value_index (int | None)
minimum_singular_value (float | None)
minimum_rank (int | None)
max_subdivision_index (int | None)
max_subdivision_count (int | None)
max_corrector_attempt_index (int | None)
max_corrector_attempts (int | None)
strategy_counts (tuple[tuple[str, int], ...])
- class kimech.SolveFailureContext(stage, driver_index=None, driver_position=None, residual_norm=None, condition_number=None, min_singular_value=None, rank=None, attempted_strategies=(), corrector_attempts=None)¶
Structured context attached to a kinematic solve failure.
Fields are descriptive and may be unavailable when a failure occurs before a reliable candidate state or Jacobian can be evaluated.
- Parameters:
stage (str)
driver_index (int | None)
driver_position (float | None)
residual_norm (float | None)
condition_number (float | None)
min_singular_value (float | None)
rank (int | None)
attempted_strategies (tuple[str, ...])
corrector_attempts (int | None)
Errors¶
- exception kimech.KimechError¶
Base class for Kimech-specific errors.
- exception kimech.InvalidModelError¶
Raised when a mechanism or solve problem is structurally invalid.
- exception kimech.KinematicSolveError(message, *, context=None)¶
Raised when a kinematic configuration cannot be solved reliably.
- Parameters:
message (str)
context (SolveFailureContext | None)
- Return type:
None
Sensitivity¶
- kimech.driver_sensitivity(solution)¶
Compute local dq/du sensitivity for every accepted driver sample.
- Parameters:
solution (KinematicSolution)
- Return type:
- class kimech.DriverSensitivity(solution, coordinate_derivatives)¶
Sensitivity of a driven solution with respect to its driver coordinate.
- Parameters:
solution (KinematicSolution)
coordinate_derivatives (np.ndarray)
- body_pose_derivatives(body)¶
Return body-pose derivatives with respect to the driver coordinate.
- property coordinate_derivatives: ndarray¶
Return generalized derivatives dq/du with shape (N, 3*n).
- property driver: KinematicDriver¶
Return the driver defining the sensitivity coordinate.
- joint_coordinate_derivatives(joint)¶
Return joint-coordinate derivatives with respect to the driver coordinate.
- Parameters:
joint (RevoluteJoint | PrismaticJoint)
- Return type:
ndarray
- property mechanism¶
Return the mechanism associated with this analysis snapshot.
Topology¶
- class kimech.MechanismTopology(mechanism)¶
Immutable-from-the-caller’s-perspective structural mechanism snapshot.
Topology is represented semantically as an undirected body-joint multigraph. Bodies are vertices and joints are edges, so multiple joints between the same pair of bodies retain their individual identities.
- Parameters:
mechanism (Mechanism)
- adjacent_bodies(body)¶
Return unique bodies adjacent to body in topology body order.
- property bodies: tuple[Ground | Link, ...]¶
Return ground followed by mobile links in snapshot order.
- property connected_components: tuple[tuple[Ground | Link, ...], ...]¶
Return deterministic body components for this snapshot.
- property cycle_rank: int¶
Return the undirected multigraph cycle rank E - V + C.
- degree(body)¶
Return multigraph degree, counting incident joint identities.
- incident_joints(body)¶
Return joints incident to body in joint creation order.
- Parameters:
- Return type:
tuple[RevoluteJoint | PrismaticJoint, …]
- property is_connected: bool¶
Return whether all snapshot bodies belong to one component.
- property joints: tuple[RevoluteJoint | PrismaticJoint, ...]¶
Return joints in snapshot creation order.
- joints_between(body_a, body_b)¶
Return all joints connecting two distinct bodies.
- Parameters:
- Return type:
tuple[RevoluteJoint | PrismaticJoint, …]