Functions
void	c_default_variational_integrator_settings (c_variational_integrator_settings *settings)
	Fill variational-integrator settings with library defaults.

void	c_variational_integrator_solve (int nbody, const c_rigid_body bodies, int ntime, double dt, const double initial_position, const c_quaternion initial_orientation, const double initial_velocity, const double initial_angular_velocity, int nconstraint, c_variational_force force_callback, c_variational_constraint constraint_callback, c_variational_constraint_jacobian jacobian_callback, void user_data, const c_variational_integrator_settings settings, double position, c_quaternion orientation, double velocity, double angular_velocity, double multipliers, int converged, int iterations, int jacobian_singular, int completed_steps)
	Integrate rigid bodies directly in maximal coordinates.

c_linkage_dynamic_model	c_create_serial_linkage_dynamic_model (const c_serial_linkage linkage, int n, const double q)
	Create a dynamic model from a serial linkage value.

c_linkage_dynamic_model	c_create_linkage_dynamic_model (bool planar, int nlinks, const c_mechanism_link links, int njoints, const c_joint joints, int base, int nq, const double *q)
	Create a dynamic model directly from parallel/planar linkage descriptors.

void	c_free_linkage_dynamic_model (c_linkage_dynamic_model obj)
	Release a linkage dynamic-model handle.

int	c_linkage_dynamic_body_count (c_linkage_dynamic_model obj)
	Return the number of moving rigid bodies in a dynamic model.

int	c_linkage_dynamic_joint_count (c_linkage_dynamic_model obj)
	Return the number of joints represented by a dynamic model.

int	c_linkage_dynamic_constraint_count (c_linkage_dynamic_model obj)
	Return the linkage constraint count before any prescribed-motion constraint is added.

void	c_linkage_dynamic_add_linear_spring (c_linkage_dynamic_model obj, const c_linear_spring *element)
	Add a tension/compression linear spring.

void	c_linkage_dynamic_add_linear_damper (c_linkage_dynamic_model obj, const c_linear_damper *element)
	Add an axis-only linear viscous damper.

void	c_linkage_dynamic_add_torsional_spring (c_linkage_dynamic_model obj, const c_torsional_spring *element)
	Add a linear torsional spring to a revolute joint.

void	c_linkage_dynamic_add_torsional_damper (c_linkage_dynamic_model obj, const c_torsional_damper *element)
	Add a twist-rate damper to a revolute joint.

int	c_linkage_dynamic_axial_element_count (c_linkage_dynamic_model obj)

int	c_linkage_dynamic_torsional_element_count (c_linkage_dynamic_model obj)

void	c_linkage_dynamic_axial_element_results (c_linkage_dynamic_model obj, int nbody, double time, const double position, const c_quaternion orientation, const double velocity, const double angular_velocity, c_axial_element_result *results)
	Query all axial elements at one state.

void	c_linkage_dynamic_torsional_element_results (c_linkage_dynamic_model obj, int nbody, double time, const double position, const c_quaternion orientation, const double velocity, const double angular_velocity, c_torsional_element_result *results)
	Query all torsional elements at one state.

void	c_linkage_dynamic_solve (c_linkage_dynamic_model obj, int nbody, int nconstraint, const c_variational_integrator_settings settings, int ntime, double dt, const double gravity[3], const double body_force, const double body_torque, int prescribed_body, c_linkage_prescribed_motion prescribed_motion, void user_data, double position, c_quaternion orientation, double velocity, double angular_velocity, double multipliers, int converged, int iterations, int jacobian_singular, int *completed_steps)
	Solve linkage dynamics.

void	c_linkage_dynamic_joint_reactions (c_linkage_dynamic_model obj, int nbody, int nconstraint, double time, const double position, const c_quaternion orientation, const double velocity, const double angular_velocity, const double multipliers, c_joint_reaction reactions)
	Convert one state's linkage multipliers into joint reaction wrenches.

Detailed Description

Function Documentation

◆ c_default_variational_integrator_settings()

void c_default_variational_integrator_settings ( c_variational_integrator_settings * settings )

Fill variational-integrator settings with library defaults.

Parameters

settings Output settings structure.

◆ c_variational_integrator_solve()

void c_variational_integrator_solve	(	int	nbody,
		const c_rigid_body *	bodies,
		int	ntime,
		double	dt,
		const double *	initial_position,
		const c_quaternion *	initial_orientation,
		const double *	initial_velocity,
		const double *	initial_angular_velocity,
		int	nconstraint,
		c_variational_force	force_callback,
		c_variational_constraint	constraint_callback,
		c_variational_constraint_jacobian	jacobian_callback,
		void *	user_data,
		const c_variational_integrator_settings *	settings,
		double *	position,
		c_quaternion *	orientation,
		double *	velocity,
		double *	angular_velocity,
		double *	multipliers,
		int *	converged,
		int *	iterations,
		int *	jacobian_singular,
		int *	completed_steps
	)

Integrate rigid bodies directly in maximal coordinates.

All matrices and histories are column-major. State histories have shape 3-by-nbody-by-ntime; orientations have shape nbody-by-ntime; multipliers have shape nconstraint-by-ntime. Callback state pointers are valid only during the callback.

Parameters

nbody	Number of rigid bodies; must be positive.
bodies	Array of nbody rigid-body mass-property structures.
ntime	Number of returned simulation points, including the initial state; must be positive.
dt	Positive fixed time step between simulation points.
initial_position	Initial world-frame center-of-mass positions with shape 3-by-nbody.
initial_orientation	Initial body-to-world unit quaternions, length nbody.
initial_velocity	Initial world-frame center-of-mass velocities with shape 3-by-nbody.
initial_angular_velocity	Initial body-frame angular velocities with shape 3-by-nbody.
nconstraint	Number of scalar equality constraints. Use zero for an unconstrained problem.
force_callback	Optional applied-force callback, or NULL for zero applied force and torque.
constraint_callback	Constraint callback. Required when nconstraint is greater than zero; may be NULL when nconstraint is zero.
jacobian_callback	Optional analytic reduced constraint Jacobian, or NULL to use scaled finite differences.
user_data	Opaque pointer forwarded unchanged to all callbacks; may be NULL.
settings	Integration settings, commonly initialized by c_default_variational_integrator_settings. force_evaluation selects explicit left-endpoint, implicit trial-endpoint, or midpoint applied-load evaluation; see the Variational and linkage dynamics guide for equations and tradeoffs.
position	Output world-frame position history with shape 3-by-nbody-by-ntime.
orientation	Output quaternion history with shape nbody-by-ntime.
velocity	Output world-frame velocity history with shape 3-by-nbody-by-ntime.
angular_velocity	Output body-frame angular-velocity history with shape 3-by-nbody-by-ntime.
multipliers	Output constraint multipliers with shape nconstraint-by-ntime. The final column is obtained from a noncommitting look-ahead step. On failure, only columns for completed steps are valid and the look-ahead column is omitted. Storage may be omitted only when nconstraint is zero.
converged	Set to 1 on success and 0 if a numerical solve fails.
iterations	Total Newton iterations across attempted steps.
jacobian_singular	Set to 1 if a Newton Jacobian was detected as singular.
completed_steps	Number of completed time advances. The output histories contain the initial state and these completed steps; unused trailing entries are zero (identity quaternions for orientation).

◆ c_create_serial_linkage_dynamic_model()

c_linkage_dynamic_model c_create_serial_linkage_dynamic_model	(	const c_serial_linkage *	linkage,
		int	n,
		const double *	q
	)

Create a dynamic model from a serial linkage value.

Parameters

linkage	Serial linkage definition. The dynamic model copies all link mass properties and does not retain the linkage pointer.
n	Number of links and joint variables.
q	Constraint-compatible initial joint variables, length n.

Returns: Opaque dynamic-model handle, owned by the caller, or NULL on failure.

◆ c_create_linkage_dynamic_model()

c_linkage_dynamic_model c_create_linkage_dynamic_model	(	bool	planar,
		int	nlinks,
		const c_mechanism_link *	links,
		int	njoints,
		const c_joint *	joints,
		int	base,
		int	nq,
		const double *	q
	)

Create a dynamic model directly from parallel/planar linkage descriptors.

Set planar true for a planar linkage. The q array contains all joint variables and must describe a constraint-compatible configuration.

Parameters

planar	True for planar dynamics; false for spatial dynamics.
nlinks	Number of link descriptors.
links	Array of nlinks multi-frame links. Link and frame data are copied into the dynamic model.
njoints	Number of joint descriptors.
joints	Array of njoints joints using one-based link/frame indices.
base	One-based index of the fixed base link.
nq	Number of complete joint variables.
q	Constraint-compatible complete joint-variable array, length nq.

Returns: Opaque dynamic-model handle, owned by the caller, or NULL on failure.

◆ c_free_linkage_dynamic_model()

void c_free_linkage_dynamic_model ( c_linkage_dynamic_model obj )

Release a linkage dynamic-model handle.

Parameters

obj	Dynamic-model handle. NULL is accepted and ignored.

◆ c_linkage_dynamic_body_count()

int c_linkage_dynamic_body_count ( c_linkage_dynamic_model obj )

Return the number of moving rigid bodies in a dynamic model.

The fixed base link of a parallel mechanism is not included.

Parameters

obj	Dynamic-model handle.

Returns: Moving-body count, or zero for a NULL handle.

◆ c_linkage_dynamic_joint_count()

int c_linkage_dynamic_joint_count ( c_linkage_dynamic_model obj )

Return the number of joints represented by a dynamic model.

Parameters

obj	Dynamic-model handle.

Returns: Joint count, or zero for a NULL handle.

◆ c_linkage_dynamic_constraint_count()

int c_linkage_dynamic_constraint_count ( c_linkage_dynamic_model obj )

Return the linkage constraint count before any prescribed-motion constraint is added.

Parameters

obj	Dynamic-model handle.

Returns: Base linkage constraint count, or zero for a NULL handle.

◆ c_linkage_dynamic_add_linear_spring()

void c_linkage_dynamic_add_linear_spring	(	c_linkage_dynamic_model	obj,
		const c_linear_spring *	element
	)

Add a tension/compression linear spring.

Parameters

obj	Dynamic-model handle.
element	Spring attachment, stiffness, and free-length definition.

◆ c_linkage_dynamic_add_linear_damper()

void c_linkage_dynamic_add_linear_damper	(	c_linkage_dynamic_model	obj,
		const c_linear_damper *	element
	)

Add an axis-only linear viscous damper.

Parameters

obj	Dynamic-model handle.
element	Damper attachment and damping-coefficient definition.

◆ c_linkage_dynamic_add_torsional_spring()

void c_linkage_dynamic_add_torsional_spring	(	c_linkage_dynamic_model	obj,
		const c_torsional_spring *	element
	)

Add a linear torsional spring to a revolute joint.

Parameters

obj	Dynamic-model handle.
element	Revolute-joint index, stiffness, and free-angle definition.

◆ c_linkage_dynamic_add_torsional_damper()

void c_linkage_dynamic_add_torsional_damper	(	c_linkage_dynamic_model	obj,
		const c_torsional_damper *	element
	)

Add a twist-rate damper to a revolute joint.

Parameters

obj	Dynamic-model handle.
element	Revolute-joint index and damping-coefficient definition.

◆ c_linkage_dynamic_axial_element_count()

int c_linkage_dynamic_axial_element_count ( c_linkage_dynamic_model obj )

Parameters

obj	Dynamic-model handle.

Returns: Number of axial elements.

◆ c_linkage_dynamic_torsional_element_count()

int c_linkage_dynamic_torsional_element_count ( c_linkage_dynamic_model obj )

Parameters

obj	Dynamic-model handle.

Returns: Number of torsional elements.

◆ c_linkage_dynamic_axial_element_results()

void c_linkage_dynamic_axial_element_results	(	c_linkage_dynamic_model	obj,
		int	nbody,
		double	time,
		const double *	position,
		const c_quaternion *	orientation,
		const double *	velocity,
		const double *	angular_velocity,
		c_axial_element_result *	results
	)

Query all axial elements at one state.

Parameters

obj	Dynamic-model handle.
nbody	Moving-body count.
time	State time.
position	Position array, shape 3-by-nbody.
orientation	Quaternion array, length nbody.
velocity	Velocity array, shape 3-by-nbody.
angular_velocity	Body-frame angular velocity, shape 3-by-nbody.
results	Output array sized by c_linkage_dynamic_axial_element_count.

◆ c_linkage_dynamic_torsional_element_results()

void c_linkage_dynamic_torsional_element_results	(	c_linkage_dynamic_model	obj,
		int	nbody,
		double	time,
		const double *	position,
		const c_quaternion *	orientation,
		const double *	velocity,
		const double *	angular_velocity,
		c_torsional_element_result *	results
	)

Query all torsional elements at one state.

Parameters

obj	Dynamic-model handle.
nbody	Moving-body count.
time	State time.
position	Position array, shape 3-by-nbody.
orientation	Quaternion array, length nbody.
velocity	Velocity array, shape 3-by-nbody.
angular_velocity	Body-frame angular velocity, shape 3-by-nbody.
results	Output array sized by c_linkage_dynamic_torsional_element_count.

◆ c_linkage_dynamic_solve()

void c_linkage_dynamic_solve	(	c_linkage_dynamic_model	obj,
		int	nbody,
		int	nconstraint,
		const c_variational_integrator_settings *	settings,
		int	ntime,
		double	dt,
		const double	gravity[3],
		const double *	body_force,
		const double *	body_torque,
		int	prescribed_body,
		c_linkage_prescribed_motion	prescribed_motion,
		void *	user_data,
		double *	position,
		c_quaternion *	orientation,
		double *	velocity,
		double *	angular_velocity,
		double *	multipliers,
		int *	converged,
		int *	iterations,
		int *	jacobian_singular,
		int *	completed_steps
	)

Solve linkage dynamics.

Query body and constraint counts first to allocate output arrays. When prescribed_motion is non-NULL, prescribed_body is the one-based moving-body index and multipliers needs one additional row. This callback bridge is synchronous and not reentrant.

Parameters

obj	Dynamic-model handle.
nbody	Moving-body count returned by c_linkage_dynamic_body_count.
nconstraint	Total multiplier rows. Use the base constraint count, or base count plus one when prescribed_motion is non-NULL.
settings	Integration settings.
ntime	Number of returned simulation points, including the initial point.
dt	Positive fixed time step.
gravity	Uniform world-frame gravitational acceleration vector.
body_force	Constant world-frame body forces with shape 3-by-nbody. Supply zeros when unused.
body_torque	Constant body-frame torques with shape 3-by-nbody. Supply zeros when unused.
prescribed_body	One-based moving-body index whose absolute planar angle is prescribed. Ignored when prescribed_motion is NULL.
prescribed_motion	Optional prescribed-angle callback, or NULL for unconstrained actuation.
user_data	Opaque pointer forwarded to prescribed_motion; may be NULL.
position	Output position history with shape 3-by-nbody-by-ntime.
orientation	Output quaternion history with shape nbody-by-ntime.
velocity	Output velocity history with shape 3-by-nbody-by-ntime.
angular_velocity	Output angular-velocity history with shape 3-by-nbody-by-ntime.
multipliers	Output multiplier history with shape nconstraint-by-ntime. If prescribed motion is active, its required actuator torque is the last multiplier row. On failure, only columns for completed steps are valid and the look-ahead column is omitted.
converged	Set to 1 on success and 0 if a numerical solve fails.
iterations	Total Newton iterations across attempted steps.
jacobian_singular	Set to 1 if a Newton Jacobian was detected as singular.
completed_steps	Number of completed time advances. The output histories contain the initial state and these completed steps; unused trailing entries are zero (identity quaternions for orientation).

◆ c_linkage_dynamic_joint_reactions()

void c_linkage_dynamic_joint_reactions	(	c_linkage_dynamic_model	obj,
		int	nbody,
		int	nconstraint,
		double	time,
		const double *	position,
		const c_quaternion *	orientation,
		const double *	velocity,
		const double *	angular_velocity,
		const double *	multipliers,
		c_joint_reaction *	reactions
	)

Convert one state's linkage multipliers into joint reaction wrenches.

Each reaction is expressed in world coordinates and acts on the joint's child link; the parent-link reaction is equal and opposite.

Parameters

obj	Dynamic-model handle.
nbody	Moving-body count returned by c_linkage_dynamic_body_count.
nconstraint	Number of multiplier values supplied. This may include a trailing prescribed-motion multiplier, which is ignored for joint reactions.
time	State time.
position	State world-frame positions with shape 3-by-nbody.
orientation	State body-to-world quaternions, length nbody.
velocity	State world-frame velocities with shape 3-by-nbody.
angular_velocity	State body-frame angular velocities with shape 3-by-nbody.
multipliers	Constraint multiplier vector, length nconstraint.
reactions	Output array of c_linkage_dynamic_joint_count(obj) reaction structures in mechanism joint order.

Functions

Detailed Description

Function Documentation

◆ c_default_variational_integrator_settings()

◆ c_variational_integrator_solve()

◆ c_create_serial_linkage_dynamic_model()

◆ c_create_linkage_dynamic_model()

◆ c_free_linkage_dynamic_model()

◆ c_linkage_dynamic_body_count()

◆ c_linkage_dynamic_joint_count()

◆ c_linkage_dynamic_constraint_count()

◆ c_linkage_dynamic_add_linear_spring()

◆ c_linkage_dynamic_add_linear_damper()

◆ c_linkage_dynamic_add_torsional_spring()

◆ c_linkage_dynamic_add_torsional_damper()

◆ c_linkage_dynamic_axial_element_count()

◆ c_linkage_dynamic_torsional_element_count()

◆ c_linkage_dynamic_axial_element_results()

◆ c_linkage_dynamic_torsional_element_results()

◆ c_linkage_dynamic_solve()

◆ c_linkage_dynamic_joint_reactions()