Core concepts

Mechanism

A Mechanism owns the ground body, mobile links, points, and joints. Kimech currently supports planar revolute and prismatic joints.

The model is declarative: geometry and connectivity are defined first, then the solver operates on the completed mechanism.

Kinematic Driver

A KinematicDriver prescribes the natural coordinate of one revolute or prismatic joint.

driver = KinematicDriver(
    joint,
    position=positions,
    velocity=omega,
    acceleration=alpha,
)

position is required. velocity and acceleration are optional physical time derivatives. Scalar differential values are broadcast over a position history.

The Driver is not a motor or actuator model. It does not contain torque, force, inertia, numerical integration, or solver settings.

Solve and continuation

solve() solves the requested Driver samples in order. Position sweeps use predictor-corrector continuation, warm-start fallback, and bounded adaptive subdivision when recovery is required.

The continuation parameter is the Driver coordinate itself.

KinematicSolution

A KinematicSolution stores the accepted state history and a snapshot of the Driver used to obtain it.

solution.driver
solution.coordinates
solution.coordinate_velocities
solution.coordinate_accelerations
solution.diagnostics
solution.time

Indexing returns a Configuration; slicing returns another KinematicSolution.

Diagnostics

Solve-generated solutions expose SolveDiagnostics. Condition numbers, ranks, singular values, residuals, accepted strategies, and subdivision counts describe the selected driven formulation. They are not a universal classification of mechanism singularity.

Driver-coordinate sensitivity

Use driver_sensitivity() after a successful solve:

from kimech import driver_sensitivity

sensitivity = driver_sensitivity(solution)
dq_du = sensitivity.coordinate_derivatives

This computes local derivatives with respect to the prescribed Driver coordinate, not derivatives with respect to time.