pylinkage.actuators package

Submodules

pylinkage.actuators.arc_crank module

Arc crank actuator - motor-driven oscillating rotary input.

An arc crank is a driver link that oscillates between angle limits at a constant angular velocity, reversing direction at boundaries.

class pylinkage.actuators.arc_crank.ArcCrank(anchor: Ground, radius: float, angular_velocity: float = 0.017453292519943295, arc_start: float = 0.0, arc_end: float = 3.141592653589793, initial_angle: float | None = None, name: str | None = None)

Bases: ConnectedComponent

A motor-driven oscillating rotary input (arc crank).

An arc crank oscillates around a ground anchor between two angle limits at constant angular velocity, producing an output point that traces an arc. Direction reverses (“bounces”) when reaching angle limits, similar to LinearActuator behavior at stroke limits.

Variables:

anchor (Ground) – The ground point this arc crank rotates around.
radius (float) – Distance from anchor to output.
angular_velocity (float) – Rotation rate magnitude in radians per step.
arc_start (float) – Minimum angle limit in radians.
arc_end (float) – Maximum angle limit in radians.
initial_angle (float) – Starting angle in radians (must be between arc_start and arc_end).

Example

>>> O1 = Ground(0.0, 0.0, name="O1")
>>> arc_crank = ArcCrank(
...     anchor=O1,
...     radius=1.0,
...     angular_velocity=0.1,
...     arc_start=0.0,
...     arc_end=math.pi/2,
... )
>>> arc_crank.position
(1.0, 0.0)

anchor: Ground

property anchors: tuple[Ground]: Return the parent dyads (just the ground anchor).

property angle: float: Return current angle.

angular_velocity: float

arc_end: float

arc_start: float

get_constraints() → tuple[float, float, float]

Return optimizable constraints.

Returns:: Tuple containing (radius, arc_start, arc_end).

initial_angle: float

property output: _AnchorProxy

Return the output joint (end of the arc crank).

This proxy can be used as an anchor for other dyads.

Returns:: An anchor proxy representing the arc crank output.

radius: float

reload(dt: float = 1) → None

Advance the arc crank by one step.

Rotates the arc crank position by angular_velocity * dt radians, reversing direction when hitting angle limits.

Parameters:: dt – Time step multiplier.
Raises:: ValueError – If anchor position is undefined.

set_constraints(radius: float | None = None, arc_start: float | None = None, arc_end: float | None = None, *args: float | None) → None

Set the constraints.

Parameters:

radius – New radius value.
arc_start – New arc_start value.
arc_end – New arc_end value.
*args – Ignored (for interface compatibility).

pylinkage.actuators.crank module

Crank actuator - motor-driven rotary input.

A crank is a driver link that rotates around a ground anchor at a constant angular velocity.

class pylinkage.actuators.crank.Crank(anchor: Ground, radius: float, angular_velocity: float = 0.017453292519943295, initial_angle: float = 0.0, name: str | None = None)

Bases: ConnectedComponent

A motor-driven rotary input (crank).

A crank rotates around a ground anchor at constant angular velocity, producing an output point that traces a circle. This is the primary input driver for most linkage mechanisms.

Variables:

anchor (Ground) – The ground point this crank rotates around.
radius (float) – Distance from anchor to output.
angular_velocity (float) – Rotation rate in radians per step.
initial_angle (float) – Starting angle in radians.

Example

>>> O1 = Ground(0.0, 0.0, name="O1")
>>> crank = Crank(anchor=O1, radius=1.0)
>>> crank.position
(1.0, 0.0)
>>> crank.output.position  # Same as crank.position
(1.0, 0.0)

anchor: Ground

property anchors: tuple[Ground]: Return the parent dyads (just the ground anchor).

angular_velocity: float

get_constraints() → tuple[float]

Return the radius (optimizable constraint).

Returns:: Tuple containing the crank radius.

initial_angle: float

property output: _AnchorProxy

Return the output joint (end of the crank).

This proxy can be used as an anchor for other dyads.

Returns:: An anchor proxy representing the crank output.

radius: float

reload(dt: float = 1) → None

Advance the crank by one step.

Rotates the crank position by angular_velocity * dt radians.

Parameters:: dt – Time step multiplier.
Raises:: ValueError – If anchor position is undefined.

set_constraints(distance: float | None = None, *args: float | None) → None

Set the radius constraint.

Parameters:

distance – New radius value.
*args – Ignored (for interface compatibility).

pylinkage.actuators.crank.DEFAULT_ANGULAR_VELOCITY = 0.017453292519943295

one degree per step (360 steps per full rotation).

Type:: Default angular velocity

pylinkage.actuators.linear module

Linear actuator - motor-driven linear input.

A linear actuator is a driver that moves along a straight line at constant velocity, oscillating between 0 and stroke limits.

class pylinkage.actuators.linear.LinearActuator(anchor: Ground, angle: float, stroke: float, speed: float = 0.1, initial_extension: float = 0.0, name: str | None = None)

Bases: ConnectedComponent

A motor-driven linear input (linear actuator).

A linear actuator moves along a line from its anchor at constant speed, producing an output point that oscillates between 0 and the stroke limit. This provides linear reciprocating motion.

Variables:

anchor (Ground) – The ground point this actuator extends from.
angle (float) – Direction angle in radians (from +x axis).
stroke (float) – Maximum extension distance.
speed (float) – Linear speed magnitude (units per step).
initial_extension (float) – Starting extension from anchor.

Example

>>> O1 = Ground(0.0, 0.0, name="O1")
>>> actuator = LinearActuator(anchor=O1, angle=0.0, stroke=2.0, speed=0.1)
>>> actuator.position
(0.0, 0.0)
>>> actuator.reload()
>>> actuator.position  # Moved 0.1 units along x-axis
(0.1, 0.0)

anchor: Ground

property anchors: tuple[Ground]: Return the parent dyads (just the ground anchor).

angle: float

property extension: float: Return current extension from anchor.

get_constraints() → tuple[float, float]

Return the stroke and speed (optimizable constraints).

Returns:: Tuple containing (stroke, speed).

initial_extension: float

property output: _AnchorProxy

Return the output joint (end of the actuator).

This proxy can be used as an anchor for other dyads.

Returns:: An anchor proxy representing the actuator output.

reload(dt: float = 1) → None

Advance the actuator by one step.

Moves the actuator position by speed * dt, reversing direction when hitting stroke limits.

Parameters:: dt – Time step multiplier.
Raises:: ValueError – If anchor position is undefined.

set_constraints(stroke: float | None = None, speed: float | None = None, *args: float | None) → None

Set the constraints.

Parameters:

stroke – New stroke value (must be positive).
speed – New speed value.
*args – Ignored (for interface compatibility).

speed: float

stroke: float

Module contents

Actuators - motor-driven input drivers for linkage mechanisms.

This module provides actuator classes that provide input motion to mechanisms:

Classes:: Crank: Motor-driven rotary input (rotating around a ground point) ArcCrank: Motor-driven oscillating rotary input (oscillates between angle limits) LinearActuator: Motor-driven linear input (oscillating piston/cylinder)

Actuators are input drivers that actively move during simulation, as opposed to passive dyads which react to their parent positions.

Example

Create a crank that rotates around a ground point:

from pylinkage.components import Ground
from pylinkage.actuators import Crank

O1 = Ground(0.0, 0.0, name="O1")
crank = Crank(anchor=O1, radius=1.0)

Create an arc crank that oscillates between angle limits:

from pylinkage.components import Ground
from pylinkage.actuators import ArcCrank
import math

O1 = Ground(0.0, 0.0, name="O1")
arc_crank = ArcCrank(anchor=O1, radius=1.0, arc_start=0, arc_end=math.pi/2)

Create a linear actuator:

from pylinkage.components import Ground
from pylinkage.actuators import LinearActuator

O1 = Ground(0.0, 0.0, name="O1")
actuator = LinearActuator(anchor=O1, angle=0.0, stroke=2.0, speed=0.1)

class pylinkage.actuators.ArcCrank(anchor: Ground, radius: float, angular_velocity: float = 0.017453292519943295, arc_start: float = 0.0, arc_end: float = 3.141592653589793, initial_angle: float | None = None, name: str | None = None)

Bases: ConnectedComponent

A motor-driven oscillating rotary input (arc crank).

An arc crank oscillates around a ground anchor between two angle limits at constant angular velocity, producing an output point that traces an arc. Direction reverses (“bounces”) when reaching angle limits, similar to LinearActuator behavior at stroke limits.

Variables:

anchor (Ground) – The ground point this arc crank rotates around.
radius (float) – Distance from anchor to output.
angular_velocity (float) – Rotation rate magnitude in radians per step.
arc_start (float) – Minimum angle limit in radians.
arc_end (float) – Maximum angle limit in radians.
initial_angle (float) – Starting angle in radians (must be between arc_start and arc_end).

Example

>>> O1 = Ground(0.0, 0.0, name="O1")
>>> arc_crank = ArcCrank(
...     anchor=O1,
...     radius=1.0,
...     angular_velocity=0.1,
...     arc_start=0.0,
...     arc_end=math.pi/2,
... )
>>> arc_crank.position
(1.0, 0.0)

anchor: Ground

property anchors: tuple[Ground]: Return the parent dyads (just the ground anchor).

property angle: float: Return current angle.

angular_velocity: float

arc_end: float

arc_start: float

get_constraints() → tuple[float, float, float]

Return optimizable constraints.

Returns:: Tuple containing (radius, arc_start, arc_end).

initial_angle: float

property output: _AnchorProxy

Return the output joint (end of the arc crank).

This proxy can be used as an anchor for other dyads.

Returns:: An anchor proxy representing the arc crank output.

radius: float

reload(dt: float = 1) → None

Advance the arc crank by one step.

Rotates the arc crank position by angular_velocity * dt radians, reversing direction when hitting angle limits.

Parameters:: dt – Time step multiplier.
Raises:: ValueError – If anchor position is undefined.

set_constraints(radius: float | None = None, arc_start: float | None = None, arc_end: float | None = None, *args: float | None) → None

Set the constraints.

Parameters:

radius – New radius value.
arc_start – New arc_start value.
arc_end – New arc_end value.
*args – Ignored (for interface compatibility).

class pylinkage.actuators.Crank(anchor: Ground, radius: float, angular_velocity: float = 0.017453292519943295, initial_angle: float = 0.0, name: str | None = None)

Bases: ConnectedComponent

A motor-driven rotary input (crank).

A crank rotates around a ground anchor at constant angular velocity, producing an output point that traces a circle. This is the primary input driver for most linkage mechanisms.

Variables:

anchor (Ground) – The ground point this crank rotates around.
radius (float) – Distance from anchor to output.
angular_velocity (float) – Rotation rate in radians per step.
initial_angle (float) – Starting angle in radians.

Example

>>> O1 = Ground(0.0, 0.0, name="O1")
>>> crank = Crank(anchor=O1, radius=1.0)
>>> crank.position
(1.0, 0.0)
>>> crank.output.position  # Same as crank.position
(1.0, 0.0)

anchor: Ground

property anchors: tuple[Ground]: Return the parent dyads (just the ground anchor).

angular_velocity: float

get_constraints() → tuple[float]

Return the radius (optimizable constraint).

Returns:: Tuple containing the crank radius.

initial_angle: float

property output: _AnchorProxy

Return the output joint (end of the crank).

This proxy can be used as an anchor for other dyads.

Returns:: An anchor proxy representing the crank output.

radius: float

reload(dt: float = 1) → None

Advance the crank by one step.

Rotates the crank position by angular_velocity * dt radians.

Parameters:: dt – Time step multiplier.
Raises:: ValueError – If anchor position is undefined.

set_constraints(distance: float | None = None, *args: float | None) → None

Set the radius constraint.

Parameters:

distance – New radius value.
*args – Ignored (for interface compatibility).

class pylinkage.actuators.LinearActuator(anchor: Ground, angle: float, stroke: float, speed: float = 0.1, initial_extension: float = 0.0, name: str | None = None)

Bases: ConnectedComponent

A motor-driven linear input (linear actuator).

A linear actuator moves along a line from its anchor at constant speed, producing an output point that oscillates between 0 and the stroke limit. This provides linear reciprocating motion.

Variables:

anchor (Ground) – The ground point this actuator extends from.
angle (float) – Direction angle in radians (from +x axis).
stroke (float) – Maximum extension distance.
speed (float) – Linear speed magnitude (units per step).
initial_extension (float) – Starting extension from anchor.

Example

>>> O1 = Ground(0.0, 0.0, name="O1")
>>> actuator = LinearActuator(anchor=O1, angle=0.0, stroke=2.0, speed=0.1)
>>> actuator.position
(0.0, 0.0)
>>> actuator.reload()
>>> actuator.position  # Moved 0.1 units along x-axis
(0.1, 0.0)

anchor: Ground

property anchors: tuple[Ground]: Return the parent dyads (just the ground anchor).

angle: float

property extension: float: Return current extension from anchor.

get_constraints() → tuple[float, float]

Return the stroke and speed (optimizable constraints).

Returns:: Tuple containing (stroke, speed).

initial_extension: float

property output: _AnchorProxy

Return the output joint (end of the actuator).

This proxy can be used as an anchor for other dyads.

Returns:: An anchor proxy representing the actuator output.

reload(dt: float = 1) → None

Advance the actuator by one step.

Moves the actuator position by speed * dt, reversing direction when hitting stroke limits.

Parameters:: dt – Time step multiplier.
Raises:: ValueError – If anchor position is undefined.

set_constraints(stroke: float | None = None, speed: float | None = None, *args: float | None) → None

Set the constraints.

Parameters:

stroke – New stroke value (must be positive).
speed – New speed value.
*args – Ignored (for interface compatibility).

speed: float

stroke: float