pylinkage.joints package

Submodules

pylinkage.joints.crank module

Crank joint definition.

A crank is a driver joint that rotates around a fixed anchor point. This is a thin wrapper around the solver’s solve_crank function.

Deprecated since version 0.7.0: The Crank class is deprecated. Use pylinkage.mechanism.create_crank() instead for clearer terminology. Crank will be removed in version 1.0.0.

class pylinkage.joints.crank.Crank(x: float | None = None, y: float | None = None, joint0: Joint | tuple[float, float] | None = None, distance: float | None = None, angle: float | None = None, name: str | None = None, omega: float | None = None, alpha: float | None = None)

Bases: Joint

Define a crank (rotary driver) joint.

The crank rotates around its anchor point (joint0) at a constant angular velocity. It is the primary driver for linkage mechanisms.

Deprecated since version 0.7.0: Use pylinkage.mechanism.create_crank() instead. The Crank class conflates a joint with a driver link. The new API separates these concepts: create_crank() returns a DriverLink and a RevoluteJoint (the crank output).

Attributes:

r: Distance from anchor to crank (radius). angle: Angular step per iteration (radians per dt=1 step). omega: Angular velocity in rad/s for kinematics computation. alpha: Angular acceleration in rad/s² for kinematics computation.

alpha: float | None
angle: float | None
get_constraints() → tuple[float | None]

Return the distance to the center of rotation.

omega: float | None
r: float | None
reload(dt: float = 1) → None

Make a step of crank using solver function.

Parameters:

dt – Fraction of steps to take (Default value = 1).

set_anchor0(joint: Joint | tuple[float, float], distance: float | None = None) → None

First joint anchor and fixed distance.

Parameters:

  • joint – Joint to set as anchor.

  • distance – Distance from the joint. (Default value = None).

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

Set geometric constraints, only self.r is affected.

Parameters:

  • distance – Distance from the reference point. (Default value = None).

  • args – Unused, but preserves the object structure.

pylinkage.joints.fixed module

Fixed joint (deterministic constraint).

A fixed joint has a position fully determined by its two parent joints with no ambiguity. It uses polar coordinates relative to the line between the two parents.

This is a thin wrapper around the solver’s solve_fixed function.

Deprecated since version 0.7.0: The Fixed class is deprecated. Use pylinkage.mechanism.create_fixed_dyad() instead for clearer terminology. Fixed will be removed in version 1.0.0.

class pylinkage.joints.fixed.Fixed(x: float | None = None, y: float | None = None, joint0: Joint | tuple[float, float] | None = None, joint1: Joint | tuple[float, float] | None = None, distance: float | None = None, angle: float | None = None, name: str | None = None)

Bases: Joint

Fixed joint - deterministic polar constraint.

The position is fully determined by: - joint0: Origin point - joint1: Reference point for angle measurement - r: Distance from joint0 - angle: Angle offset from the joint0→joint1 direction

Unlike Revolute (RRR dyad), this has a unique solution.

Deprecated since version 0.7.0: Use pylinkage.mechanism.create_fixed_dyad() instead. This class represents a fixed angular constraint (deterministic dyad), not a “fixed joint”. The new API uses clearer terminology.

angle: float | None
get_constraints() → tuple[float | None, float | None]

Return the constraining distance and angle parameters.

r: float | None
reload(dt: float = 1) → None

Compute position using solver (deterministic constraint).

Parameters:

dt – Unused, but preserves the object structure.

set_anchor0(joint: Joint | tuple[float, float], distance: float | None = None, angle: float | None = None) → None

First joint anchor and characteristics.

Parameters:

  • joint – Joint to set as anchor.

  • distance – Distance from the joint. (Default value = None).

  • angle – Angle in radians. (Default value = None).

set_anchor1(joint: Joint | tuple[float, float]) → None

Second joint anchor.

Parameters:

joint – Joint to set as anchor.

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

Set geometric constraints.

Parameters:

  • distance – Distance from joint0. (Default value = None).

  • angle – Angle in radians. (Default value = None).

  • args – Unused, but preserves the object structure.

pylinkage.joints.joint module

Definition of the different joints used for pylinkage.

class pylinkage.joints.joint.Joint(x: float | None = 0, y: float | None = 0, joint0: Joint | tuple[float, float] | None = None, joint1: Joint | tuple[float, float] | None = None, name: str | None = None)

Bases: Component

Geometric constraint expressed by two joints.

Abstract class should always be inherited.

Deprecated since version 0.8.0: Legacy base class. New code should use Component and its subclasses directly.

property anchors: tuple[Component, ...]

Return parent joints as a tuple (Component interface compatibility).

abstractmethod get_constraints() → tuple[float | None, ...]

Return geometric constraints applying to this Joint.

joint0: Joint | _StaticBase | Component | None
joint1: Joint | _StaticBase | Component | None
abstractmethod reload(dt: float = 1) → None

Recompute joint coordinates based on constraints and parent joints.

Parameters:

dt – Time step or fraction of movement. The default is 1.

abstractmethod set_constraints(*args: float | None) → None

Set geometric constraints applying to this Joint.

set_coord(*args: float | None | tuple[float, float] | tuple[float | None, float | None]) → None

Take a sequence or two scalars, and assign them to object x, y.

Parameters:

args – Coordinates to set, either as two elements or as a tuple of 2 elements.

class pylinkage.joints.joint.Static(x: float = 0, y: float = 0, name: str | None = None)

Bases: _StaticBase

Special case of Joint that should not move.

Mostly used for the frame.

Deprecated since version 0.7.0: Use pylinkage.mechanism.GroundJoint instead. This class represents a ground joint (fixed point on the frame), not a generic “static” object. The new API uses clearer terminology.

pylinkage.joints.joint.joint_syntax_parser(joint: Joint | tuple[float, float] | None) → Joint | _StaticBase | None

Syntactic parser that understand a joint definition.

Parameters:

joint (Joint | tuple[float, float] | None) – Input joint definition to be parsed.

Returns:

New static joint definition if possible, or None.

Return type:

Joint | _StaticBase | None

pylinkage.joints.prismatic module

Definition of a prismatic joint (RRP dyad).

A prismatic joint is positioned at the intersection of a circle and a line. The circle is centered at a revolute anchor, and the line is defined by two other joints. This corresponds to an RRP (two revolute, one prismatic) dyad in Assur group theory.

This is a thin wrapper around the solver’s solve_linear function.

Deprecated since version 0.7.0: The Prismatic class is deprecated. Use pylinkage.mechanism.create_rrp_dyad() instead for clearer terminology. Prismatic will be removed in version 1.0.0.

class pylinkage.joints.prismatic.Linear(*args: object, **kwargs: object)

Bases: Prismatic

Deprecated alias for Prismatic joint.

Deprecated since version Use: Prismatic instead. The Linear name will be removed in a future version.

joint2
revolute_radius
class pylinkage.joints.prismatic.Prismatic(x: float = 0, y: float = 0, joint0: Joint | tuple[float, float] | None = None, joint1: Joint | tuple[float, float] | None = None, joint2: Joint | tuple[float, float] | None = None, revolute_radius: float | None = None, name: str | None = None)

Bases: Joint

Prismatic joint (RRP dyad) - circle-line intersection.

The position is computed as the intersection of: - Circle: centered at joint0 with radius revolute_radius - Line: passing through joint1 and joint2

When two solutions exist, the nearest to the current position is chosen (hysteresis for continuity during simulation).

Deprecated since version 0.7.0: Use pylinkage.mechanism.create_rrp_dyad() instead. Despite its name, this class is NOT a single prismatic joint - it’s an RRP dyad (2 links including a slider). The new API uses clearer terminology: create_rrp_dyad() returns two Link objects and one PrismaticJoint.

property anchors: tuple[Joint | _StaticBase, ...]

Return all three parent joints (revolute anchor + line endpoints).

get_constraints() → tuple[float | None]

Return the only distance constraint for this joint.

joint2: Joint | Static | None
reload(dt: float = 1) → None

Compute position using solver (RRP dyad - circle-line).

Parameters:

dt – Unused, but preserves the object structure.

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

Set the only distance constraint for this joint.

Parameters:

  • distance0 – Distance from joint0. (Default value = None).

  • args – Unused, but preserves the object structure.

pylinkage.joints.revolute module

Definition of a revolute joint (RRR dyad).

A revolute joint is positioned at the intersection of two circles, each centered at a parent joint. This corresponds to an RRR (three revolute joints) dyad in Assur group theory.

This is a thin wrapper around the solver’s solve_revolute function.

Deprecated since version 0.7.0: The Revolute class is deprecated. Use pylinkage.mechanism.create_rrr_dyad() instead for clearer terminology. Revolute will be removed in version 1.0.0.

class pylinkage.joints.revolute.Pivot(x: float = 0, y: float = 0, joint0: Joint | tuple[float, float] | None = None, joint1: Joint | tuple[float, float] | None = None, distance0: float | None = None, distance1: float | None = None, name: str | None = None)

Bases: Revolute

Revolute Joint definition.

Deprecated since version 0.6.0: This class has been deprecated in favor of Revolute which has a standard name. It will be removed in PyLinkage 0.7.0.

r0
r1
class pylinkage.joints.revolute.Revolute(x: float = 0, y: float = 0, joint0: Joint | tuple[float, float] | None = None, joint1: Joint | tuple[float, float] | None = None, distance0: float | None = None, distance1: float | None = None, name: str | None = None)

Bases: Joint

Revolute joint (RRR dyad) - circle-circle intersection.

The position is computed as the intersection of two circles: - Circle 1: centered at joint0 with radius r0 - Circle 2: centered at joint1 with radius r1

When two solutions exist, the nearest to the current position is chosen (hysteresis for continuity during simulation).

Deprecated since version 0.7.0: Use pylinkage.mechanism.create_rrr_dyad() instead. Despite its name, this class is NOT a single revolute joint - it’s an RRR dyad (2 links + 3 revolute joints). The new API uses clearer terminology: create_rrr_dyad() returns two Link objects and one RevoluteJoint.

circle(joint: Joint) → tuple[float, float, float]

Return the first link between self and parent as a circle.

Parameters:

joint – Parent joint you want to use.

Returns:

Circle is a tuple (abscissa, ordinate, radius).

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

Return the two constraining distances of this joint.

r0: float | None
r1: float | None
reload(dt: float = 1) → None

Compute position using solver (RRR dyad - circle-circle).

Parameters:

dt – Unused, but preserves the object structure.

set_anchor0(joint: Joint | tuple[float, float], distance: float | None = None) → None

Set the first anchor for this Joint.

Parameters:

  • joint – The joint to use as anchor.

  • distance – Distance to keep constant from the anchor. The default is None.

set_anchor1(joint: Joint | tuple[float, float], distance: float | None = None) → None

Set the second anchor for this Joint.

Parameters:

  • joint – The joint to use as anchor.

  • distance – Distance to keep constant from the anchor. The default is None.

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

Set geometric constraints.

Parameters:

  • distance0 – Distance to the first reference (Default value = None).

  • distance1 – Distance to the second reference (Default value = None).

  • args – Unused, but preserves the object structure.

pylinkage.joints.static module

Static joint definition file.

Deprecated since version 0.7.0: The Static class is deprecated. Use pylinkage.mechanism.GroundJoint instead for clearer terminology. Static will be removed in version 1.0.0.

class pylinkage.joints.static.Static(x: float = 0, y: float = 0, name: str | None = None)

Bases: Joint

Special case of Joint that should not move.

Mostly used for the frame.

Deprecated since version 0.7.0: Use pylinkage.mechanism.GroundJoint instead. This class represents a ground joint (fixed point on the frame), not a generic “static” object. The new API uses clearer terminology.

get_constraints() → tuple[()]

Return an empty tuple.

reload(dt: float = 1) → None

Do nothing, for consistency only.

Args:

dt: Unused, but preserves the object structure.

set_anchor0(joint: pl_joint.Joint | Coord) → None

First joint anchor.

Args:

joint: Joint to set as anchor.

set_anchor1(joint: pl_joint.Joint | Coord) → None

Second joint anchor.

Args:

joint: Joint to set as anchor.

set_constraints(*args: float | None) → None

Do nothing, for consistency only.

Args:

args: Unused.

Module contents

Legacy joint definitions (Assur groups).

Deprecated since version 0.8.0: This module uses misleading terminology. What are called “joints” here are actually Assur groups (combinations of joints and links).

Migration guide: - Static -> dyads.Ground - Crank -> dyads.Crank - Revolute -> dyads.RRRDyad - Prismatic -> dyads.RRPDyad - Fixed -> dyads.FixedDyad

For Assur group decomposition, use pylinkage.assur module directly.

Example migration:

# Old (deprecated):
from pylinkage.joints import Static, Crank, Revolute
A = Static(x=0, y=0, name="A")
B = Crank(x=1, y=0, joint0=A, distance=1, angle=0.1)

# New (preferred):
from pylinkage.dyads import Ground, Crank, RRRDyad, Linkage
A = Ground(0, 0, name="A")
B = Crank(anchor=A, radius=1.0, angular_velocity=0.1)