The DYNAMICS C API is a C-compatible interface to the library. The public declarations are in dynamics.h.

Conventions

Matrices use column-major storage, matching the Fortran API. For a matrix with m rows, n columns, and leading dimension ld, element (i, j) is stored at j * ld + i using zero-based C indices.
Mechanism link, joint, and frame indices are one-based, matching the Fortran API.
Memory returned by an allocation or creation routine is owned by the caller and must be released with its corresponding c_free_* routine.
An optional pointer may be passed as NULL only where the function declaration or reference explicitly permits it.
Solver callbacks use C calling conventions and receive array dimensions as explicit arguments.
Variational state histories use column-major 3 × nbody × ntime arrays; multiplier histories use nconstraint × ntime arrays.
The prescribed-motion linkage callback is synchronous and not reentrant.

Linking

Include the installed header and link against the DYNAMICS library and its dependencies. A CMake consumer can use the exported DYNAMICS target after installation:

find_package(dynamics CONFIG REQUIRED)

target_link_libraries(my_program PRIVATE dynamics::dynamics)

The C interface is enabled when building DYNAMICS with:

cmake -S . -B build -DBUILD_DYNAMICS_C_INTERFACE=ON

Example

The repository contains a complete closed-loop example at examples/c_four_bar_example_1.c. It shows how to allocate mechanism links, connect them with c_joint values, create a planar linkage, solve its forward kinematics, and release all allocated data.

Beam coordinates

The beam element APIs use the local element coordinate system shown below. The local x-axis runs from node 1 to node 2. For a 3D beam, the orientation point defines the local z-axis and the local y-axis completes the right-handed frame.

Beam element coordinate systems

Denavit-Hartenberg parameters

The c_dh_parameter_set structure follows the standard Denavit-Hartenberg convention used by the kinematics API. The transform maps coordinates from frame i into frame i-1 as

Rz(joint_angle) Tz(link_offset) Tx(link_length) Rx(link_twist).

Standard Denavit-Hartenberg parameters

Geometry operations

The geometry API provides point, line, plane, and Plucker-line representations, along with projection, distance, parallelism, intersection, and common-normal operations. The relationships are summarized below.

Geometry representations and operations

Variational and linkage dynamics

The variational API supports two workflows:

c_variational_integrator_solve integrates caller-defined rigid bodies in maximal coordinates. C callbacks supply applied loads, equality constraints, and optionally an analytic reduced constraint Jacobian.
c_create_serial_linkage_dynamic_model and c_create_linkage_dynamic_model convert linkage descriptions into opaque dynamic-model handles. c_linkage_dynamic_solve then applies gravity, constant body loads, and optional prescribed planar motion.

Initialize c_variational_integrator_settings with c_default_variational_integrator_settings before changing individual fields. The force_evaluation field selects the applied-load sampling rule for both direct and linkage solves:

DYN_VI_FORCE_LEFT_ENDPOINT (default) evaluates loads at the current state; this is explicit and least expensive.
DYN_VI_FORCE_IMPLICIT_ENDPOINT evaluates loads at the trial next state in every Newton residual evaluation. This is more robust for stiff damping but increases nonlinear work and also endpoint-samples springs and user loads.
DYN_VI_FORCE_MIDPOINT evaluates loads at the time/state midpoint in every Newton residual evaluation. Translation, time, and linear velocity are averaged; orientation uses the unit-quaternion geodesic midpoint, and angular velocity is averaged in world coordinates then expressed in the midpoint body frame. This is midpoint force sampling, not a complete implicit-midpoint state integrator.

For a scalar mass-damper equation m * dv/dt = -c * v, with $r=h c/m$, the velocity amplification factors are $1-r$ (left endpoint), $1/(1+r)$ (implicit endpoint), and $(1-r/2)/(1+r/2)$ (midpoint). Thus the explicit mode can grow energy for $r>2$, the implicit mode strongly damps stiff modes, and midpoint is stable but approaches a sign-alternating factor of $-1$ for very stiff modes. All applied loads use the selected sampling rule, not only damper elements. Force callbacks in the implicit and midpoint modes are called repeatedly during Newton and should be deterministic functions of their input state, time, and user data.

The direct and linkage solve routines write caller-owned histories using these column-major shapes:

position, velocity, and angular velocity: 3 × nbody × ntime;
orientation: nbody × ntime;
multipliers: nconstraint × ntime.

Multiplier column i belongs to simulation point i. The final column is computed with a noncommitting look-ahead step. For prescribed linkage motion, the prescribed-angle multiplier is appended after the linkage constraints and represents the required actuator torque.

Use c_linkage_dynamic_joint_reactions to convert one state and multiplier column into world-frame joint forces and moments. Reactions are returned in mechanism joint order and act on each joint's child link. The reaction on the parent link is equal and opposite.

Linkage dynamic models may also contain linear force elements:

c_linear_spring acts in tension and compression between arbitrary body-fixed points. Its free_length defines zero force and therefore any preload at the initial configuration.
c_linear_damper acts only on relative velocity along the current element axis.
c_torsional_spring acts about the axis of its referenced revolute joint; free_angle defines its zero-torque angle.
c_torsional_damper opposes only relative twist rate about that joint axis.

Body index zero denotes a ground attachment whose point is expressed in world coordinates. Other attachment points are expressed in their body frame. Use the element count and result routines to query current length/rate/force or angle/rate/torque values.

Opaque dynamic-model handles own copied linkage and mass-property data; release them with c_free_linkage_dynamic_model. Callback state views are temporary and must not be retained after a callback returns. The prescribed-motion callback bridge is synchronous and not reentrant.

Reference

The generated reference is organized by API area:

The complete declaration reference is also available from the generated Data Structures and Files pages.

Routine-level documentation, including the purpose of every public routine, its arguments, output arguments, and return value, is maintained in the C APIroutine reference". The declarations in dynamics.h remain the authoritative source for types, array dimensions, and calling conventions.