Mechanics

Mechanics: pendulums, oscillators, friction, projectiles, collisions, rotating bodies, wells, and beam maps.

BallisticPendulumElement(label, visual=None, *, x=-1.0, x_d1=0.0, theta=0.0, theta_d1=0.0, m=0.01, M=1.0, l=1.0, g=9.81)

Bases: Element

Bullet of mass m at the position x flying towards the block of mass M of a pendulum with the angle theta.

The position and the angle have order 2. The bullet flies freely, the pendulum swings, and the impact transfers the momentum of the bullet to the pendulum.

Parameters:

Name	Type	Description	Default
label	str	The label of the bullet and pendulum.	required
visual	VisualSpec | None	How the bullet and pendulum are drawn, or None for none.	None
x	Annotated[float, StateSpec(order=2)]	The initial position of the bullet, negative before the block.	-1.0
x_d1	float	The initial velocity of the bullet.	0.0
theta	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the pendulum.	0.0
theta_d1	float	The initial angular velocity of the pendulum.	0.0
m	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the bullet.	0.01
M	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the block.	1.0
l	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the rod.	1.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.81

Examples:

>>> from skcomplex.systems.physics.mechanics import BallisticPendulumElement
>>> BallisticPendulumElement('pendulum', M=2.0).M
2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec(order=2)] = -1.0,
    x_d1: float = 0.0,
    theta: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.0,
    theta_d1: float = 0.0,
    m: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.01,
    M: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    l: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.81,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.x_d1 = x_d1
    self.theta = theta
    self.theta_d1 = theta_d1
    self.m = m
    self.M = M
    self.l = l
    self.g = g

BeamElement(label, visual=None, *, x=0.5, y=0.0, nu=0.3, c=0.05)

Bases: Element

Transverse position and momentum of a particle of an accelerator beam, kicked by the opposite beam every turn.

Map interactions rotate the particle by the tune and kick its momentum with the field of the opposite beam, so the element holds the states and the parameters they read.

Parameters:

Name	Type	Description	Default
label	str	The label of the particle.	required
visual	VisualSpec | None	How the particle is drawn, or None for default_visual_.	None
x	Annotated[float, StateSpec()]	The initial transverse position.	0.5
y	Annotated[float, StateSpec()]	The initial transverse momentum.	0.0
nu	Annotated[float, ParameterSpec(domain=closed(0, 2))]	The tune, the rotation per turn in units of pi, in [0, 2].	0.3
c	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The strength of the beam-beam kick.	0.05

Attributes:

Name	Type	Description
default_visual_		The visual of the particle when it sets none.

Examples:

>>> from skcomplex.systems.physics.mechanics import BeamElement
>>> BeamElement('particle').nu
0.3

Source code in src/skcomplex/systems/physics/mechanics/_accelerators.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec()] = 0.5,
    y: Annotated[float, StateSpec()] = 0.0,
    nu: Annotated[float, ParameterSpec(domain=RealSet.closed(0, 2))] = 0.3,
    c: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.05,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.nu = nu
    self.c = c

BouncingBallElement(label, visual=None, *, h=1.0, h_d1=0.0, g=9.81)

Bases: Element

Ball at the height h above a floor, falling under the gravitational acceleration g.

The height has order 2 and its first derivative h_d1 is the vertical velocity.

Parameters:

Name	Type	Description	Default
label	str	The label of the ball.	required
visual	VisualSpec | None	How the ball is drawn, or None for none.	None
h	Annotated[float, StateSpec(order=2)]	The initial height.	1.0
h_d1	float	The initial vertical velocity.	0.0
g	Annotated[float, ParameterSpec()]	The gravitational acceleration.	9.81

Examples:

>>> from skcomplex.systems.physics.mechanics import BouncingBallElement
>>> BouncingBallElement('ball', h=2.0).h
2.0

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    h: Annotated[float, StateSpec(order=2)] = 1.0,
    h_d1: float = 0.0,
    g: Annotated[float, ParameterSpec()] = 9.81,
) -> None:
    super().__init__(label, visual=visual)
    self.h = h
    self.h_d1 = h_d1
    self.g = g

CartPendulumElement(label, visual=None, *, y=0.0, y_d1=0.0, theta=0.5, theta_d1=0.0, m1=1.0, m2=1.0, l=1.0, g=9.81, F=0.0)

Bases: Element

Cart on a horizontal track at the position y, with a pendulum of angle theta hanging from it.

The position and the angle have order 2. The motion comes from CartPendulumInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the cart and pendulum.	required
visual	VisualSpec | None	How the cart and pendulum are drawn, or None for its class visual.	None
y	Annotated[float, StateSpec(order=2)]	The initial position of the cart.	0.0
y_d1	float	The initial velocity of the cart.	0.0
theta	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the pendulum.	0.5
theta_d1	float	The initial angular velocity of the pendulum.	0.0
m1	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the cart.	1.0
m2	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the bob.	1.0
l	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the rod.	1.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.81
F	Annotated[float, ParameterSpec()]	A constant horizontal force on the cart.	0.0

Examples:

>>> from skcomplex.systems.physics.mechanics import CartPendulumElement
>>> CartPendulumElement('cart', m1=5.0).m1
5.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    y: Annotated[float, StateSpec(order=2)] = 0.0,
    y_d1: float = 0.0,
    theta: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.5,
    theta_d1: float = 0.0,
    m1: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    m2: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    l: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.81,
    F: Annotated[float, ParameterSpec()] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.y = y
    self.y_d1 = y_d1
    self.theta = theta
    self.theta_d1 = theta_d1
    self.m1 = m1
    self.m2 = m2
    self.l = l
    self.g = g
    self.F = F

CartPendulumInteraction(label, *, target)

Bases: EulerLagrangeInteraction

Motion of a cart and the pendulum that hangs from it, the Euler-Lagrange equations with a force on the cart.

The Lagrangian is (m1 + m2) y'² / 2 + m2 l y' θ' cos θ + m2 l² θ'² / 2 + m2 g l cos θ, and the force F of the target drives the position y of the cart.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the cart and pendulum.	required

Examples:

>>> from skcomplex.systems.physics.mechanics import CartPendulumInteraction
>>> CartPendulumInteraction('motion', target='cart').states
('y', 'theta')

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()]) -> None:
    super().__init__(label, target=target, states=('y', 'theta'), forcing=self._get_forces_on_coordinates)

ClockPendulumElement(label, visual=None, *, theta=0.2, theta_d1=0.0, x=0.0, x_d1=0.0, m=1.0, l=1.0, M=1.0, g=9.8, rho=0.1, lam=0.1, theta_c=0.1)

Bases: Element

Pendulum clock, a pendulum of angle theta hanging from a support at the horizontal position x.

The angle and the position have order 2. The motion comes from ClockPendulumInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the clock.	required
visual	VisualSpec | None	How the clock is drawn, or None for none.	None
theta	Annotated[float, StateSpec(order=2)]	The initial angle of the pendulum.	0.2
theta_d1	float	The initial angular velocity of the pendulum.	0.0
x	Annotated[float, StateSpec(order=2)]	The initial position of the support.	0.0
x_d1	float	The initial velocity of the support.	0.0
m	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the bob.	1.0
l	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the pendulum.	1.0
M	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the support.	1.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.8
rho	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The damping of the support.	0.1
lam	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The strength of the escapement.	0.1
theta_c	Annotated[float, ParameterSpec(domain=open(0, oo))]	The angle below which the escapement pumps energy in.	0.1

Examples:

>>> from skcomplex.systems.physics.mechanics import ClockPendulumElement
>>> ClockPendulumElement('clock', lam=0.2).lam
0.2

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    theta: Annotated[float, StateSpec(order=2)] = 0.2,
    theta_d1: float = 0.0,
    x: Annotated[float, StateSpec(order=2)] = 0.0,
    x_d1: float = 0.0,
    m: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    l: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    M: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.8,
    rho: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
    lam: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
    theta_c: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.1,
) -> None:
    super().__init__(label, visual=visual)
    self.theta = theta
    self.theta_d1 = theta_d1
    self.x = x
    self.x_d1 = x_d1
    self.m = m
    self.l = l
    self.M = M
    self.g = g
    self.rho = rho
    self.lam = lam
    self.theta_c = theta_c

ClockPendulumInteraction(label, *, target)

Bases: EulerLagrangeInteraction

Motion of a pendulum clock on a moving support, the Euler-Lagrange equations with the escapement.

The Lagrangian is (M + m) x'² / 2 + m l x' θ' cos θ + m l² θ'² / 2 + m g l cos θ. The Rayleigh dissipation λ l sgn(|θ| - θ_c) θ'² + rho x'² damps the support and gives the escapement 2 λ l sgn(|θ| - θ_c) θ', which pumps energy into the pendulum below the angle θ_c and takes it out beyond.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the clock.	required

Examples:

>>> from skcomplex.systems.physics.mechanics import ClockPendulumInteraction
>>> ClockPendulumInteraction('motion', target='clock').states
('theta', 'x')

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()]) -> None:
    super().__init__(label, target=target, states=('theta', 'x'), dissipation=self._get_escapement)

DiscBilliardElement(label, visual=None, *, x=0.3, y=0.0, vx=0.4, vy=1.0, radius=1.0)

Bases: Element

Particle moving freely in the plane with the position (x, y) and the velocity (vx, vy), inside a disc.

The position changes at the velocity, which changes only at the reflections off the wall of the disc.

Parameters:

Name	Type	Description	Default
label	str	The label of the particle.	required
visual	VisualSpec | None	How the particle is drawn, or None for its class visual.	None
x	Annotated[float, StateSpec()]	The initial horizontal position.	0.3
y	Annotated[float, StateSpec()]	The initial vertical position.	0.0
vx	Annotated[float, StateSpec()]	The initial horizontal velocity.	0.4
vy	Annotated[float, StateSpec()]	The initial vertical velocity.	1.0
radius	Annotated[float, ParameterSpec(domain=open(0, oo))]	The radius of the disc.	1.0

Examples:

>>> from skcomplex.systems.physics.mechanics import DiscBilliardElement
>>> DiscBilliardElement('particle', radius=2.0).radius
2.0

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec()] = 0.3,
    y: Annotated[float, StateSpec()] = 0.0,
    vx: Annotated[float, StateSpec()] = 0.4,
    vy: Annotated[float, StateSpec()] = 1.0,
    radius: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.y = y
    self.vx = vx
    self.vy = vy
    self.radius = radius

DoublePendulumElement(label, visual=None, *, theta1=math.pi / 2, theta1_d1=0.0, theta2=math.pi / 2, theta2_d1=0.0, m1=1.0, m2=1.0, l1=1.0, l2=1.0, g=9.81)

Bases: Element

Double pendulum, a bob of mass m2 on a rod of length l2 hanging from a bob of mass m1 on a rod l1.

The angles theta1 and theta2 of the rods from the vertical have order 2. The motion comes from DoublePendulumInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the double pendulum.	required
visual	VisualSpec | None	How the double pendulum is drawn, or None for its class visual.	None
theta1	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the upper rod.	pi / 2
theta1_d1	float	The initial angular velocity of the upper rod.	0.0
theta2	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the lower rod.	pi / 2
theta2_d1	float	The initial angular velocity of the lower rod.	0.0
m1	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the upper bob.	1.0
m2	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the lower bob.	1.0
l1	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the upper rod.	1.0
l2	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the lower rod.	1.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.81

Examples:

>>> from skcomplex.systems.physics.mechanics import DoublePendulumElement
>>> DoublePendulumElement('pendulum', m2=2.0).m2
2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    theta1: Annotated[float, StateSpec(period=2 * pi, order=2)] = math.pi / 2,
    theta1_d1: float = 0.0,
    theta2: Annotated[float, StateSpec(period=2 * pi, order=2)] = math.pi / 2,
    theta2_d1: float = 0.0,
    m1: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    m2: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    l1: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    l2: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.81,
) -> None:
    super().__init__(label, visual=visual)
    self.theta1 = theta1
    self.theta1_d1 = theta1_d1
    self.theta2 = theta2
    self.theta2_d1 = theta2_d1
    self.m1 = m1
    self.m2 = m2
    self.l1 = l1
    self.l2 = l2
    self.g = g

DoublePendulumInteraction(label, *, target)

Bases: EulerLagrangeInteraction

Motion of a double pendulum, the Euler-Lagrange equations of its kinetic energy and gravity.

The Lagrangian is (m1 + m2) l1² θ1'² / 2 + m2 l2² θ2'² / 2 + m2 l1 l2 θ1' θ2' cos(θ1 - θ2) + (m1 + m2) g l1 cos θ1 + m2 g l2 cos θ2, with the masses, lengths, and gravity of the target.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the double pendulum.	required

Examples:

>>> from skcomplex.systems.physics.mechanics import DoublePendulumInteraction
>>> DoublePendulumInteraction('motion', target='pendulum').states
('theta1', 'theta2')

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()]) -> None:
    super().__init__(label, target=target, states=('theta1', 'theta2'))

ElasticCollisionInteraction(label, *, left, right, diameter=0.1)

Bases: Interaction

Elastic collision of two equal masses in a row, which exchange their velocities when they touch.

The collision is the event at which the gap x_right - x_left - diameter between the balls falls to zero, and equal masses swap their velocities in an elastic collision.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
left	Annotated[str, RoleSpec()]	The path of the left ball, with a position x of order 2.	required
right	Annotated[str, RoleSpec()]	The path of the right ball, with a position x of order 2.	required
diameter	Annotated[float, ParameterSpec(domain=open(0, oo))]	The diameter of the balls.	0.1

Examples:

>>> from skcomplex.systems.physics.mechanics import ElasticCollisionInteraction
>>> ElasticCollisionInteraction('collision', left='a', right='b', diameter=0.2).diameter
0.2

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

def __init__(
    self,
    label: str,
    *,
    left: Annotated[str, RoleSpec()],
    right: Annotated[str, RoleSpec()],
    diameter: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.1,
) -> None:
    super().__init__(label)
    self.left = left
    self.right = right
    self.diameter = diameter

ExponentialWellInteraction(label, *, target, k=2.0)

Bases: PotentialEnergyInteraction

Potential k x² e^-x on a particle in one dimension, a well at x = 0 behind a barrier at x = 2.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the particle.	required
k	Annotated[float, ParameterSpec(domain=open(0, oo))]	The strength of the potential.	2.0

Examples:

>>> from skcomplex.systems.physics.mechanics import ExponentialWellInteraction
>>> ExponentialWellInteraction('well', target='particle', k=2.0).k
2.0

Source code in src/skcomplex/systems/physics/mechanics/_wells.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    k: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 2.0,
) -> None:
    super().__init__(label, target=target)
    self.k = k

FrictionOscillatorElement(label, visual=None, *, x=1.03, v=0.0, m=1.0, k=1.0, c=0.0, mu_s=0.06, mu_k=0.05, g=1.0, v_stick=0.01)

Bases: Element

Mass on a spring with static, Coulomb, and viscous friction, which sticks and slips.

The mass m at the position x with the velocity v feels the spring -k x and the viscous friction -c v. While it slides it feels the Coulomb friction -mu_k m g sign(v), and at rest it stays at rest while the spring force stays within the static friction mu_s m g. The friction is discontinuous in the velocity, so the mass counts as at rest below the speed v_stick, which must exceed the change of speed of one solver step, and its position stays still while it is at rest.

Parameters:

Name	Type	Description	Default
label	str	The label of the mass.	required
visual	VisualSpec | None	How the mass is drawn, or None for default_visual_.	None
x	Annotated[float, StateSpec()]	The initial position.	1.03
v	Annotated[float, StateSpec()]	The initial velocity.	0.0
m	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass.	1.0
k	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The stiffness of the spring.	1.0
c	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The viscous friction coefficient.	0.0
mu_s	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The static friction coefficient.	0.06
mu_k	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The kinetic friction coefficient.	0.05
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	1.0
v_stick	Annotated[float, ParameterSpec(domain=open(0, oo))]	The speed below which the mass counts as at rest.	0.01

Attributes:

Name	Type	Description
default_visual_		The visual of the mass when it sets none.

Examples:

>>> from skcomplex.systems.physics.mechanics import FrictionOscillatorElement
>>> FrictionOscillatorElement('mass').mu_s
0.06

Source code in src/skcomplex/systems/physics/mechanics/_accelerators.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec()] = 1.03,
    v: Annotated[float, StateSpec()] = 0.0,
    m: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    k: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    c: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    mu_s: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.06,
    mu_k: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.05,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    v_stick: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.01,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.v = v
    self.m = m
    self.k = k
    self.c = c
    self.mu_s = mu_s
    self.mu_k = mu_k
    self.g = g
    self.v_stick = v_stick

GyroscopeElement(label, visual=None, *, alpha=0.0, alpha_d1=0.0, beta=0.3, beta_d1=0.0, gamma=0.0, gamma_d1=0.0, A=1.0, C=2.0, A1=0.5, B1=0.5, C1=0.5, A2=1.0, torque=1.0)

Bases: Element

Gyroscope in a gimbal: a rotor in an inner ring that turns in an outer ring about a fixed axis.

The angle alpha of the outer ring, beta of the inner ring, and gamma of the rotor have order 2. The motion comes from GyroscopeInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the gyroscope.	required
visual	VisualSpec | None	How the gyroscope is drawn, or None for none.	None
alpha	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the outer ring.	0.0
alpha_d1	float	The initial angular velocity of the outer ring.	0.0
beta	Annotated[float, StateSpec(order=2)]	The initial angle of the inner ring.	0.3
beta_d1	float	The initial angular velocity of the inner ring.	0.0
gamma	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the rotor.	0.0
gamma_d1	float	The initial angular velocity of the rotor.	0.0
A	Annotated[float, ParameterSpec(domain=open(0, oo))]	The equatorial moment of inertia of the rotor.	1.0
C	Annotated[float, ParameterSpec(domain=open(0, oo))]	The polar moment of inertia of the rotor.	2.0
A1	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The first principal moment of inertia of the inner ring.	0.5
B1	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The second principal moment of inertia of the inner ring.	0.5
C1	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The third principal moment of inertia of the inner ring.	0.5
A2	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The moment of inertia of the outer ring about its axis.	1.0
torque	Annotated[float, ParameterSpec()]	The torque on the axis of the inner ring.	1.0

Examples:

>>> from skcomplex.systems.physics.mechanics import GyroscopeElement
>>> GyroscopeElement('gyroscope', gamma_d1=10.0).gamma_d1
10.0

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    alpha: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.0,
    alpha_d1: float = 0.0,
    beta: Annotated[float, StateSpec(order=2)] = 0.3,
    beta_d1: float = 0.0,
    gamma: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.0,
    gamma_d1: float = 0.0,
    A: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    C: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 2.0,
    A1: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    B1: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    C1: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    A2: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    torque: Annotated[float, ParameterSpec()] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.alpha = alpha
    self.alpha_d1 = alpha_d1
    self.beta = beta
    self.beta_d1 = beta_d1
    self.gamma = gamma
    self.gamma_d1 = gamma_d1
    self.A = A
    self.C = C
    self.A1 = A1
    self.B1 = B1
    self.C1 = C1
    self.A2 = A2
    self.torque = torque

GyroscopeInteraction(label, *, target)

Bases: EulerLagrangeInteraction

Motion of a gimballed gyroscope, the Euler-Lagrange equations of its kinetic energy with a torque on beta.

The Lagrangian is the kinetic energy [A2 + (A + A1) cos² β + (C + C1) sin² β] alpha'² / 2 + (A + B1) β'² / 2 + C alpha' gamma' sin β + C gamma'² / 2, and the torque of the target acts on the axis of the inner ring.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the gyroscope.	required

Examples:

>>> from skcomplex.systems.physics.mechanics import GyroscopeInteraction
>>> GyroscopeInteraction('motion', target='gyroscope').states
('alpha', 'beta', 'gamma')

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()]) -> None:
    super().__init__(label, target=target, states=('alpha', 'beta', 'gamma'), forcing=self._get_torques)

HangingBallElement(label, visual=None, *, x=0.0, x_d1=0.0, rest=0.0, g=9.81, length=1.0)

Bases: Element

Ball hanging on a string of length length, which swings with small amplitude about its rest position.

The horizontal position x has order 2, and its first derivative x_d1 is the velocity. For small amplitudes the ball moves in the potential g (x - rest)² / (2 length).

Parameters:

Name	Type	Description	Default
label	str	The label of the ball.	required
visual	VisualSpec | None	How the ball is drawn, or None for none.	None
x	Annotated[float, StateSpec(order=2)]	The initial horizontal position.	0.0
x_d1	float	The initial horizontal velocity.	0.0
rest	Annotated[float, ParameterSpec()]	The rest position.	0.0
g	Annotated[float, ParameterSpec()]	The gravitational acceleration.	9.81
length	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the string.	1.0

Examples:

>>> from skcomplex.systems.physics.mechanics import HangingBallElement
>>> HangingBallElement('ball', rest=0.5).rest
0.5

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec(order=2)] = 0.0,
    x_d1: float = 0.0,
    rest: Annotated[float, ParameterSpec()] = 0.0,
    g: Annotated[float, ParameterSpec()] = 9.81,
    length: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.x_d1 = x_d1
    self.rest = rest
    self.g = g
    self.length = length

HarmonicForceInteraction(label, *, target, F=0.0, omega=1.0, state='x', divisor='m')

Bases: RateInteraction

Periodic force F cos(omega t) on a target, the second derivative F cos(omega t) / m of its position.

It is the rate F cos(omega t) with the mass as divisor, applied to every component of the position.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the element or group the force acts on.	required
F	Annotated[float, ParameterSpec()]	The amplitude of the force.	0.0
omega	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The angular frequency of the force.	1.0
state	str	The name of the state of order 2 that holds the position of the target.	'x'
divisor	str	The name of the state or parameter that holds the mass of the target.	'm'

Examples:

>>> from skcomplex.systems.physics.common.particles import HarmonicForceInteraction
>>> HarmonicForceInteraction('drive', target='mass', F=0.5, omega=2.0).omega
2.0

Source code in src/skcomplex/systems/physics/common/particles/_harmonic_force.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    F: Annotated[float, ParameterSpec()] = 0.0,
    omega: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    state: str = 'x',
    divisor: str = 'm',
) -> None:
    super().__init__(label, target=target, state=state, divisor=divisor)
    self.F = F
    self.omega = omega

MagnetInteraction(label, *, target, center=0.0, gamma=1.0, d=0.3)

Bases: PotentialEnergyInteraction

Magnet below the plane of a pendulum bob, which attracts it with energy -gamma / sqrt(|x - center|**2 + d**2).

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the bob.	required
center	Annotated[ArrayLike, ParameterSpec(vector=True)]	The position of the magnet in the plane.	0.0
gamma	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The strength of the magnet.	1.0
d	Annotated[float, ParameterSpec(domain=open(0, oo))]	The height of the bob above the plane of the magnets.	0.3

Examples:

>>> from skcomplex.systems.physics.mechanics import MagnetInteraction
>>> MagnetInteraction('magnet', target='bob', center=[1.0, 0.0]).gamma
1.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    center: Annotated[npt.ArrayLike, ParameterSpec(vector=True)] = 0.0,
    gamma: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    d: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.3,
) -> None:
    super().__init__(label, target=target)
    self.center = center
    self.gamma = gamma
    self.d = d

ParametricPendulumElement(label, visual=None, *, theta=0.1, theta_d1=0.0, g=9.81, l=1.0, epsilon=0.2, Omega=2 * math.sqrt(9.81), c=0.0)

Bases: Element

Pendulum whose suspension point oscillates vertically, with the angle theta of order 2.

The motion comes from ParametricPendulumInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the pendulum.	required
visual	VisualSpec | None	How the pendulum is drawn, or None for none.	None
theta	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle.	0.1
theta_d1	float	The initial angular velocity.	0.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.81
l	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the rod.	1.0
epsilon	Annotated[float, ParameterSpec()]	The amplitude of the acceleration of the suspension point, relative to g.	0.2
Omega	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The angular frequency of the suspension point.	2 * sqrt(9.81)
c	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The friction coefficient.	0.0

Examples:

>>> from skcomplex.systems.physics.mechanics import ParametricPendulumElement
>>> ParametricPendulumElement('swing', epsilon=0.5).epsilon
0.5

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    theta: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.1,
    theta_d1: float = 0.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.81,
    l: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    epsilon: Annotated[float, ParameterSpec()] = 0.2,
    Omega: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 2 * math.sqrt(9.81),
    c: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.theta = theta
    self.theta_d1 = theta_d1
    self.g = g
    self.l = l
    self.epsilon = epsilon
    self.Omega = Omega
    self.c = c

ParametricPendulumInteraction(label, *, target, direction='vertical')

Bases: EulerLagrangeInteraction

Motion of a pendulum whose suspension point oscillates vertically or horizontally, an Euler-Lagrange equation.

The suspension point accelerates by ε g cos Ω t. Vertically, the Lagrangian per moment of inertia is θ'² / 2 + (g / l)(1 + ε cos Ω t) cos θ, and the acceleration modulates gravity, a parametric forcing. Horizontally, it is θ'² / 2 + (g / l)(cos θ - ε cos Ω t sin θ), and the acceleration pushes the bob sideways, an external forcing. The Rayleigh dissipation c θ'² / 2 adds the friction, so the angle follows θ'' + c θ' + (g / l)(1 + ε cos Ω t) sin θ = 0 or θ'' + c θ' + (g / l)(sin θ + ε cos Ω t cos θ) = 0, with the parameters of the target.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the pendulum.	required
direction	str	The direction in which the suspension point oscillates, 'vertical' or 'horizontal'.	'vertical'

Raises:

Type	Description
ValidationError	The direction is unknown.

Examples:

>>> from skcomplex.systems.physics.mechanics import ParametricPendulumInteraction
>>> ParametricPendulumInteraction('swing', target='pendulum').states
'theta'

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()], direction: str = 'vertical') -> None:
    super().__init__(label, target=target, states='theta', dissipation=self._get_friction)
    self.direction = direction

PendulumElement(label, visual=None, *, theta=0.5, theta_d1=0.0, m=1.0, g=9.81, l=1.0)

Bases: Element

Pendulum, a bob of mass m on a rigid rod of length l that swings by the angle theta under gravity g.

The angle has order 2 and its first derivative theta_d1 is the angular velocity. The motion comes from an interaction such as PendulumInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the pendulum.	required
visual	VisualSpec | None	How the pendulum is drawn, or None for its class visual.	None
theta	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle from the vertical, in radians.	0.5
theta_d1	float	The initial angular velocity.	0.0
m	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the bob.	1.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.81
l	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the rod.	1.0

Examples:

>>> from skcomplex.systems.physics.common.mechanics import PendulumElement
>>> PendulumElement('bob', theta=0.2, l=2.0).l
2.0

Source code in src/skcomplex/systems/physics/common/mechanics/_pendulum.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    theta: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.5,
    theta_d1: float = 0.0,
    m: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.81,
    l: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.theta = theta
    self.theta_d1 = theta_d1
    self.m = m
    self.g = g
    self.l = l

PendulumInteraction(label, *, target)

Bases: EulerLagrangeInteraction

Motion of a pendulum, the Euler-Lagrange equation of L = m l² θ'² / 2 + m g l cos θ.

The equation is Newton's law m l² θ'' = -m g l sin θ for the angle θ of the target, whose mass m, length l, and gravity g are parameters of the target.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the pendulum.	required

Examples:

>>> from skcomplex.systems.physics.common.mechanics import PendulumInteraction
>>> PendulumInteraction('swing', target='bob').states
'theta'

Source code in src/skcomplex/systems/physics/common/mechanics/_pendulum_interaction.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()]) -> None:
    super().__init__(label, target=target, states='theta')

PendulumSpringInteraction(label, *, first, second, k=1.0)

Bases: EulerLagrangeInteraction

Spring between the bobs of two pendulums, which stretches with the horizontal distance of the bobs.

The spring of stiffness k adds the Lagrangian -k (l2 sin θ2 - l1 sin θ1)² / 2 to the Euler-Lagrange equations of the two angles, so its torque on every pendulum divides by the moment of inertia m l² of the pendulum's own Lagrangian.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
first	Annotated[str, RoleSpec()]	The path of the first pendulum, with the angle theta, the mass m, and the length l.	required
second	Annotated[str, RoleSpec()]	The path of the second pendulum.	required
k	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The stiffness of the spring.	1.0

Examples:

>>> from skcomplex.systems.physics.mechanics import PendulumSpringInteraction
>>> PendulumSpringInteraction('spring', first='left', second='right', k=2.0).k
2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    *,
    first: Annotated[str, RoleSpec()],
    second: Annotated[str, RoleSpec()],
    k: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, target=first, states='theta')
    self.first = first
    self.second = second
    self.k = k

RotatingBallElement(label, visual=None, *, theta=0.0, m=1.0, r=1.0, beta=math.pi / 2, H=1.0)

Bases: Element

Ball of mass m on a rod at the distance r from the joint, turning about a vertical axis by the angle theta.

The rod is fixed at the angle beta to the axis, so the ball is at the distance r sin β from it, and H is its angular momentum about the axis.

Parameters:

Name	Type	Description	Default
label	str	The label of the ball.	required
visual	VisualSpec | None	How the ball is drawn, or None for none.	None
theta	Annotated[float, StateSpec(period=2 * pi)]	The initial angle about the axis.	0.0
m	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of the ball.	1.0
r	Annotated[float, ParameterSpec(domain=open(0, oo))]	The distance of the ball from the joint of the rod.	1.0
beta	Annotated[float, ParameterSpec(domain=open(0, oo))]	The angle of the rod to the axis, in radians.	pi / 2
H	Annotated[float, ParameterSpec()]	The angular momentum of the ball about the axis.	1.0

Examples:

>>> from skcomplex.systems.physics.mechanics import RotatingBallElement
>>> RotatingBallElement('ball', H=2.0).H
2.0

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    theta: Annotated[float, StateSpec(period=2 * pi)] = 0.0,
    m: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    r: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    beta: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = math.pi / 2,
    H: Annotated[float, ParameterSpec()] = 1.0,
) -> None:
    super().__init__(label, visual=visual)
    self.theta = theta
    self.m = m
    self.r = r
    self.beta = beta
    self.H = H

RotatingSwingElement(label, visual=None, *, phi=0.0, phi_d1=0.0, theta=0.1, theta_d1=0.0, J=10.0, m=1.0, n_chairs=8.0, a=1.0, l=1.0, g=9.81, torque=0.0, friction=0.0)

Bases: Element

Rotating swing: chairs on chains hanging from the rods of a stand that turns about a vertical axis.

The angle phi of the stand and the angle theta of the chains from the vertical have order 2. The motion comes from RotatingSwingInteraction.

Parameters:

Name	Type	Description	Default
label	str	The label of the swing.	required
visual	VisualSpec | None	How the swing is drawn, or None for none.	None
phi	Annotated[float, StateSpec(period=2 * pi, order=2)]	The initial angle of the stand.	0.0
phi_d1	float	The initial angular velocity of the stand.	0.0
theta	Annotated[float, StateSpec(order=2)]	The initial angle of the chains.	0.1
theta_d1	float	The initial angular velocity of the chains.	0.0
J	Annotated[float, ParameterSpec(domain=open(0, oo))]	The moment of inertia of the stand.	10.0
m	Annotated[float, ParameterSpec(domain=open(0, oo))]	The mass of every chair.	1.0
n_chairs	Annotated[float, ParameterSpec(domain=open(0, oo))]	The number of chairs.	8.0
a	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The length of the rods.	1.0
l	Annotated[float, ParameterSpec(domain=open(0, oo))]	The length of the chains.	1.0
g	Annotated[float, ParameterSpec(domain=open(0, oo))]	The gravitational acceleration.	9.81
torque	Annotated[float, ParameterSpec()]	The torque that drives the stand.	0.0
friction	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The friction coefficient of the stand's axis.	0.0

Examples:

>>> from skcomplex.systems.physics.mechanics import RotatingSwingElement
>>> RotatingSwingElement('swing', n_chairs=4.0).n_chairs
4.0

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    phi: Annotated[float, StateSpec(period=2 * pi, order=2)] = 0.0,
    phi_d1: float = 0.0,
    theta: Annotated[float, StateSpec(order=2)] = 0.1,
    theta_d1: float = 0.0,
    J: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
    m: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    n_chairs: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 8.0,
    a: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    l: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    g: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 9.81,
    torque: Annotated[float, ParameterSpec()] = 0.0,
    friction: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.phi = phi
    self.phi_d1 = phi_d1
    self.theta = theta
    self.theta_d1 = theta_d1
    self.J = J
    self.m = m
    self.n_chairs = n_chairs
    self.a = a
    self.l = l
    self.g = g
    self.torque = torque
    self.friction = friction

RotatingSwingInteraction(label, *, target)

Bases: EulerLagrangeInteraction

Motion of a rotating swing, the Euler-Lagrange equations with a torque and friction on the stand.

The Lagrangian is [J + n m (a + l sin θ)²] φ'² / 2 + n m l² θ'² / 2 + n m g l cos θ, the torque drives the angle φ of the stand, and the Rayleigh dissipation c φ'² / 2 adds the friction of its axis.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
target	Annotated[str, RoleSpec()]	The path of the swing.	required

Examples:

>>> from skcomplex.systems.physics.mechanics import RotatingSwingInteraction
>>> RotatingSwingInteraction('motion', target='swing').states
('phi', 'theta')

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

def __init__(self, label: str, *, target: Annotated[str, RoleSpec()]) -> None:
    super().__init__(
        label,
        target=target,
        states=('phi', 'theta'),
        dissipation=self._get_friction,
        forcing=self._get_torques,
    )

SupportSpringInteraction(label, *, first, second, k=1.0)

Bases: EulerLagrangeInteraction

Spring of stiffness k between the supports of two pendulum clocks.

The spring adds the Lagrangian -k (x2 - x1)² / 2 to the Euler-Lagrange equations of the supports, so every clock answers with the accelerations of its support and its pendulum through the mass matrix of its own Lagrangian.

Parameters:

Name	Type	Description	Default
label	str	The label of the interaction.	required
first	Annotated[str, RoleSpec()]	The path of the first clock.	required
second	Annotated[str, RoleSpec()]	The path of the second clock.	required
k	Annotated[float, ParameterSpec(domain=closed_open(0, oo))]	The stiffness of the spring.	1.0

Examples:

>>> from skcomplex.systems.physics.mechanics import SupportSpringInteraction
>>> SupportSpringInteraction('spring', first='clock_0', second='clock_1', k=2.0).k
2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

def __init__(
    self,
    label: str,
    *,
    first: Annotated[str, RoleSpec()],
    second: Annotated[str, RoleSpec()],
    k: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, target=first, states='x')
    self.first = first
    self.second = second
    self.k = k

ballistic_pendulum(speed=200.0, distance=1.0, *, m=0.01, M=1.0, l=1.0, g=9.81)

Return a bullet that sticks in the block of a pendulum at rest, which then swings up.

The bullet flies horizontally towards the block, and the impact is an event. Momentum is conserved in the perfectly inelastic collision, so the pendulum starts with the speed m v / (m + M) and rises to the height (m v / (m + M))² / (2 g). The bullet position stops at the block after the impact.

Parameters:

Name	Type	Description	Default
speed	float	The speed of the bullet.	200.0
distance	float	The initial distance of the bullet from the block.	1.0
m	float	The mass of the bullet.	0.01
M	float	The mass of the block.	1.0
l	float	The length of the rod.	1.0
g	float	The gravitational acceleration.	9.81

Returns:

Name	Type	Description
system	System	The system, with the bullet position pendulum.x and the angle pendulum.theta, both of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import ballistic_pendulum
>>> ballistic_pendulum(distance=2.0).elements[0].x
-2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'events', 'impacts', 'momentum', 'hybrid'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 3.0, 'dt': 0.01},
)
def ballistic_pendulum(
    speed: float = 200.0,
    distance: float = 1.0,
    *,
    m: float = 0.01,
    M: float = 1.0,
    l: float = 1.0,
    g: float = 9.81,
) -> System:
    """Return a bullet that sticks in the block of a pendulum at rest, which then swings up.

    The bullet flies horizontally towards the block, and the impact is an event. Momentum is conserved in the
    perfectly inelastic collision, so the pendulum starts with the speed `m v / (m + M)` and rises to the height
    `(m v / (m + M))² / (2 g)`. The bullet position stops at the block after the impact.

    Args:
        speed:
            The speed of the bullet.

        distance:
            The initial distance of the bullet from the block.

        m:
            The mass of the bullet.

        M:
            The mass of the block.

        l:
            The length of the rod.

        g:
            The gravitational acceleration.

    Returns:
        system:
            The system, with the bullet position `pendulum.x` and the angle `pendulum.theta`, both of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import ballistic_pendulum
        >>> ballistic_pendulum(distance=2.0).elements[0].x
        -2.0
    """
    swing = EulerLagrangeInteraction(
        'swing',
        target='pendulum',
        states='theta',
        lagrangian=lambda s: s.target.l * derivative(s.target.theta, 1) ** 2 / 2 + s.target.g * cos(s.target.theta),
    )
    impact = CrossingInteraction(
        'impact',
        target='pendulum',
        guard=lambda s: s.target.x,
        reset={
            'x_d1': lambda s: 0,
            'theta_d1': lambda s: s.target.m * s.target.x_d1 / ((s.target.m + s.target.M) * s.target.l),
        },
        direction=1,
    )
    return System(
        elements=[BallisticPendulumElement('pendulum', x=-distance, x_d1=speed, m=m, M=M, l=l, g=g)],
        interactions=[swing, impact],
    )

beam_beam_map(x=0.5, y=0.0, *, nu=0.3, c=0.05)

Return the beam-beam map of a particle of an accelerator beam that meets the opposite beam once every turn.

Every turn the transverse position and momentum rotate by the angle pi nu of the tune, u = a x + b y with a = cos(pi nu) and b = sin(pi nu), and the round Gaussian charge of the opposite beam kicks the momentum: x' = u, y' = -b x + a y - 8 pi c (1 - exp(-u² / 2)) / u. The map preserves area, as the composition of a rotation and a kick. The origin is a fixed point, whose linearisation has the trace 2 a - 4 pi c b and is elliptic when the trace lies in (-2, 2), and the phase space mixes invariant curves, island chains, and chaotic layers.

Parameters:

Name	Type	Description	Default
x	float	The initial transverse position.	0.5
y	float	The initial transverse momentum.	0.0
nu	float	The tune, in [0, 2].	0.3
c	float	The strength of the beam-beam kick.	0.05

Returns:

Name	Type	Description
system	System	The system, with the states particle.x and particle.y.

Examples:

>>> from skcomplex.systems.physics.mechanics import beam_beam_map
>>> beam_beam_map(nu=0.5).elements[0].nu
0.5

Source code in src/skcomplex/systems/physics/mechanics/_accelerators.py

@register_system(
    field='physics/mechanics',
    tags=('discrete map', 'hamiltonian', 'area preserving', 'accelerator', 'chaos'),
    references=('Dilão and Alves-Pires 1996', 'Dilão 2023'),
    defaults={'until': 2000, 'dt': 1},
)
def beam_beam_map(x: float = 0.5, y: float = 0.0, *, nu: float = 0.3, c: float = 0.05) -> System:
    """Return the beam-beam map of a particle of an accelerator beam that meets the opposite beam once every turn.

    Every turn the transverse position and momentum rotate by the angle `pi nu` of the tune, `u = a x + b y` with
    `a = cos(pi nu)` and `b = sin(pi nu)`, and the round Gaussian charge of the opposite beam kicks the momentum:
    `x' = u`, `y' = -b x + a y - 8 pi c (1 - exp(-u² / 2)) / u`. The map preserves area, as the composition of a
    rotation and a kick. The origin is a fixed point, whose linearisation has the trace `2 a - 4 pi c b` and is
    elliptic when the trace lies in `(-2, 2)`, and the phase space mixes invariant curves, island chains, and chaotic
    layers.

    Args:
        x:
            The initial transverse position.

        y:
            The initial transverse momentum.

        nu:
            The tune, in `[0, 2]`.

        c:
            The strength of the beam-beam kick.

    Returns:
        system:
            The system, with the states `particle.x` and `particle.y`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import beam_beam_map
        >>> beam_beam_map(nu=0.5).elements[0].nu
        0.5
    """
    rotation = MapInteraction('x_map', target='particle', state='x', function=lambda s: _rotate(s)[0])
    kick = MapInteraction('y_map', target='particle', state='y', function=_kick)
    return System(
        elements=[BeamElement('particle', x=x, y=y, nu=nu, c=c)],
        interactions=[rotation, kick],
        time=DiscreteTime(),
    )

bouncing_ball(h=1.0, v=0.0, *, g=9.81, e=0.8)

Return a ball that falls under gravity and bounces off the floor, losing speed by a coefficient of restitution.

Every impact is an event that reverses the velocity and scales it by e. The impacts accumulate at the Zeno time sqrt(2 h / g) (1 + e) / (1 - e) for a ball dropped from rest, so runs should end before it.

Parameters:

Name	Type	Description	Default
h	float	The initial height.	1.0
v	float	The initial vertical velocity.	0.0
g	float	The gravitational acceleration.	9.81
e	float	The coefficient of restitution.	0.8

Returns:

Name	Type	Description
system	System	The system, with the height ball.h of order 2 and its velocity ball.h_d1.

Examples:

>>> from skcomplex.systems.physics.mechanics import bouncing_ball
>>> from skcomplex.core.engine.runtime import Simulation
>>> trajectory = Simulation(bouncing_ball(), dt=0.01).prepare().run(until=1.0).trajectory_
>>> round(trajectory.events[0].time, 6)
0.451524

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'events', 'impacts'),
    references=('Strogatz 2015', 'Hairer, Nørsett, and Wanner 1993'),
    defaults={'until': 3.0, 'dt': 0.01},
)
def bouncing_ball(h: float = 1.0, v: float = 0.0, *, g: float = 9.81, e: float = 0.8) -> System:
    """Return a ball that falls under gravity and bounces off the floor, losing speed by a coefficient of restitution.

    Every impact is an event that reverses the velocity and scales it by `e`. The impacts accumulate at the Zeno time
    `sqrt(2 h / g) (1 + e) / (1 - e)` for a ball dropped from rest, so runs should end before it.

    Args:
        h:
            The initial height.

        v:
            The initial vertical velocity.

        g:
            The gravitational acceleration.

        e:
            The coefficient of restitution.

    Returns:
        system:
            The system, with the height `ball.h` of order 2 and its velocity `ball.h_d1`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import bouncing_ball
        >>> from skcomplex.core.engine.runtime import Simulation
        >>> trajectory = Simulation(bouncing_ball(), dt=0.01).prepare().run(until=1.0).trajectory_
        >>> round(trajectory.events[0].time, 6)
        0.451524
    """
    return System(
        elements=[BouncingBallElement('ball', h=h, h_d1=v, g=g)],
        interactions=[
            RateInteraction('gravity', target='ball', state='h', rate=lambda s: -s.target.g),
            ReflectionInteraction(
                'impact',
                target='ball',
                guard=lambda s: s.target.h,
                positions=('h',),
                velocities=('h_d1',),
                direction=-1,
                restitution=e,
            ),
        ],
    )

cart_pendulum(theta=0.5, y=0.0, *, m1=1.0, m2=1.0, l=1.0, g=9.81, F=0.0)

Return a pendulum hanging from a cart that slides without friction along a horizontal track.

The Lagrange equations (m1 + m2) y'' + m2 l (θ'' cos θ - θ'² sin θ) = F and l θ'' + y'' cos θ + g sin θ = 0 couple the position y of the cart and the angle θ of the pendulum. Without a force the horizontal momentum is conserved, so the cart swings against the pendulum.

Parameters:

Name	Type	Description	Default
theta	float	The initial angle of the pendulum.	0.5
y	float	The initial position of the cart.	0.0
m1	float	The mass of the cart.	1.0
m2	float	The mass of the bob.	1.0
l	float	The length of the rod.	1.0
g	float	The gravitational acceleration.	9.81
F	float	A constant horizontal force on the cart.	0.0

Returns:

Name	Type	Description
system	System	The system, with the cart position cart.y and the angle cart.theta, both of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import cart_pendulum
>>> cart_pendulum(m1=5.0).elements[0].m1
5.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'lagrangian', 'momentum'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 10.0, 'dt': 0.02},
)
def cart_pendulum(
    theta: float = 0.5,
    y: float = 0.0,
    *,
    m1: float = 1.0,
    m2: float = 1.0,
    l: float = 1.0,
    g: float = 9.81,
    F: float = 0.0,
) -> System:
    """Return a pendulum hanging from a cart that slides without friction along a horizontal track.

    The Lagrange equations `(m1 + m2) y'' + m2 l (θ'' cos θ - θ'² sin θ) = F` and `l θ'' + y'' cos θ + g sin θ = 0`
    couple the position `y` of the cart and the angle `θ` of the pendulum. Without a force the horizontal momentum is
    conserved, so the cart swings against the pendulum.

    Args:
        theta:
            The initial angle of the pendulum.

        y:
            The initial position of the cart.

        m1:
            The mass of the cart.

        m2:
            The mass of the bob.

        l:
            The length of the rod.

        g:
            The gravitational acceleration.

        F:
            A constant horizontal force on the cart.

    Returns:
        system:
            The system, with the cart position `cart.y` and the angle `cart.theta`, both of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import cart_pendulum
        >>> cart_pendulum(m1=5.0).elements[0].m1
        5.0
    """
    return System(
        elements=[CartPendulumElement('cart', y=y, theta=theta, m1=m1, m2=m2, l=l, g=g, F=F)],
        interactions=[CartPendulumInteraction('motion', target='cart')],
    )

circular_billiard(x=0.3, y=0.0, vx=0.4, vy=1.0, *, radius=1.0)

Return a particle moving freely inside a circle and reflecting specularly off its wall.

The angle of incidence is the same at every bounce, so the circular billiard is integrable.

Parameters:

Name	Type	Description	Default
x	float	The initial horizontal position.	0.3
y	float	The initial vertical position.	0.0
vx	float	The initial horizontal velocity.	0.4
vy	float	The initial vertical velocity.	1.0
radius	float	The radius of the table.	1.0

Returns:

Name	Type	Description
system	System	The system, with the position particle.x, particle.y and the velocity particle.vx, particle.vy.

Examples:

>>> from skcomplex.systems.physics.mechanics import circular_billiard
>>> circular_billiard(radius=2.0).elements[0].radius
2.0

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'events', 'billiard', 'integrable'),
    references=('Tabachnikov 2005', 'Datseris and Parlitz 2022'),
    defaults={'until': 20.0, 'dt': 0.05},
)
def circular_billiard(
    x: float = 0.3,
    y: float = 0.0,
    vx: float = 0.4,
    vy: float = 1.0,
    *,
    radius: float = 1.0,
) -> System:
    """Return a particle moving freely inside a circle and reflecting specularly off its wall.

    The angle of incidence is the same at every bounce, so the circular billiard is integrable.

    Args:
        x:
            The initial horizontal position.

        y:
            The initial vertical position.

        vx:
            The initial horizontal velocity.

        vy:
            The initial vertical velocity.

        radius:
            The radius of the table.

    Returns:
        system:
            The system, with the position `particle.x`, `particle.y` and the velocity `particle.vx`, `particle.vy`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import circular_billiard
        >>> circular_billiard(radius=2.0).elements[0].radius
        2.0
    """
    wall = ReflectionInteraction(
        'bounce',
        target='particle',
        guard=lambda s: s.target.x**2 + s.target.y**2 - s.target.radius**2,
        positions=('x', 'y'),
        velocities=('vx', 'vy'),
        direction=1,
    )
    return System(
        elements=[DiscBilliardElement('particle', x=x, y=y, vx=vx, vy=vy, radius=radius)],
        interactions=[wall],
    )

coupled_pendulums(theta1=0.2, theta2=0.0, *, k=0.5, m1=1.0, m2=1.0, l1=1.0, l2=1.0, g=9.81)

Return two pendulums whose bobs are joined by a spring, which pass their energy back and forth.

The spring stretches with the horizontal distance l2 sin θ2 - l1 sin θ1 of the bobs and adds the torque k l1 (l2 sin θ2 - l1 sin θ1) cos θ1 to the first pendulum and the opposite one to the second. Identical pendulums have the normal modes sqrt(g / l) in phase and sqrt(g / l + 2 k / m) in antiphase.

Parameters:

Name	Type	Description	Default
theta1	float	The initial angle of the first pendulum.	0.2
theta2	float	The initial angle of the second pendulum.	0.0
k	float	The stiffness of the spring.	0.5
m1	float	The mass of the first bob.	1.0
m2	float	The mass of the second bob.	1.0
l1	float	The length of the first pendulum.	1.0
l2	float	The length of the second pendulum.	1.0
g	float	The gravitational acceleration.	9.81

Returns:

Name	Type	Description
system	System	The system, with the pendulums left and right and their angles left.theta and right.theta.

Examples:

>>> from skcomplex.systems.physics.mechanics import coupled_pendulums
>>> coupled_pendulums(k=2.0).interactions[0].k
2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'oscillation', 'normal modes'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 40.0, 'dt': 0.05},
)
def coupled_pendulums(
    theta1: float = 0.2,
    theta2: float = 0.0,
    *,
    k: float = 0.5,
    m1: float = 1.0,
    m2: float = 1.0,
    l1: float = 1.0,
    l2: float = 1.0,
    g: float = 9.81,
) -> System:
    """Return two pendulums whose bobs are joined by a spring, which pass their energy back and forth.

    The spring stretches with the horizontal distance `l2 sin θ2 - l1 sin θ1` of the bobs and adds the torque
    `k l1 (l2 sin θ2 - l1 sin θ1) cos θ1` to the first pendulum and the opposite one to the second. Identical pendulums
    have the normal modes `sqrt(g / l)` in phase and `sqrt(g / l + 2 k / m)` in antiphase.

    Args:
        theta1:
            The initial angle of the first pendulum.

        theta2:
            The initial angle of the second pendulum.

        k:
            The stiffness of the spring.

        m1:
            The mass of the first bob.

        m2:
            The mass of the second bob.

        l1:
            The length of the first pendulum.

        l2:
            The length of the second pendulum.

        g:
            The gravitational acceleration.

    Returns:
        system:
            The system, with the pendulums `left` and `right` and their angles `left.theta` and `right.theta`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import coupled_pendulums
        >>> coupled_pendulums(k=2.0).interactions[0].k
        2.0
    """
    return System(
        elements=[
            PendulumElement('left', theta=theta1, m=m1, l=l1, g=g),
            PendulumElement('right', theta=theta2, m=m2, l=l2, g=g),
        ],
        interactions=[
            PendulumSpringInteraction('spring', first='left', second='right', k=k),
            PendulumInteraction('left_swing', target='left'),
            PendulumInteraction('right_swing', target='right'),
        ],
    )

double_pendulum(theta1=math.pi / 2, theta2=math.pi / 2, omega1=0.0, omega2=0.0, *, m1=1.0, m2=1.0, l1=1.0, l2=1.0, g=9.81)

Return a double pendulum, a pendulum hanging from the bob of another, written as its two Lagrange equations.

The equations (m1 + m2) l1 θ1'' + m2 l2 θ2'' cos(θ1 - θ2) + m2 l2 θ2'² sin(θ1 - θ2) + (m1 + m2) g sin θ1 = 0 and l2 θ2'' + l1 θ1'' cos(θ1 - θ2) - l1 θ1'² sin(θ1 - θ2) + g sin θ2 = 0 are solved jointly for the angular accelerations. The motion is chaotic at large amplitudes.

Parameters:

Name	Type	Description	Default
theta1	float	The initial angle of the upper rod from the vertical, in radians.	pi / 2
theta2	float	The initial angle of the lower rod from the vertical, in radians.	pi / 2
omega1	float	The initial angular velocity of the upper rod.	0.0
omega2	float	The initial angular velocity of the lower rod.	0.0
m1	float	The mass of the upper bob.	1.0
m2	float	The mass of the lower bob.	1.0
l1	float	The length of the upper rod.	1.0
l2	float	The length of the lower rod.	1.0
g	float	The gravitational acceleration.	9.81

Returns:

Name	Type	Description
system	System	The system, with the angles pendulum.theta1 and pendulum.theta2 of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import double_pendulum
>>> double_pendulum(m2=2.0).elements[0].m2
2.0

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'chaos', 'lagrangian'),
    references=('Ryzhov et al. 2021', 'Argun et al. 2021'),
    defaults={'until': 20.0, 'dt': 0.02},
)
def double_pendulum(
    theta1: float = math.pi / 2,
    theta2: float = math.pi / 2,
    omega1: float = 0.0,
    omega2: float = 0.0,
    *,
    m1: float = 1.0,
    m2: float = 1.0,
    l1: float = 1.0,
    l2: float = 1.0,
    g: float = 9.81,
) -> System:
    """Return a double pendulum, a pendulum hanging from the bob of another, written as its two Lagrange equations.

    The equations `(m1 + m2) l1 θ1'' + m2 l2 θ2'' cos(θ1 - θ2) + m2 l2 θ2'² sin(θ1 - θ2) + (m1 + m2) g sin θ1 = 0`
    and `l2 θ2'' + l1 θ1'' cos(θ1 - θ2) - l1 θ1'² sin(θ1 - θ2) + g sin θ2 = 0` are solved jointly for the angular
    accelerations. The motion is chaotic at large amplitudes.

    Args:
        theta1:
            The initial angle of the upper rod from the vertical, in radians.

        theta2:
            The initial angle of the lower rod from the vertical, in radians.

        omega1:
            The initial angular velocity of the upper rod.

        omega2:
            The initial angular velocity of the lower rod.

        m1:
            The mass of the upper bob.

        m2:
            The mass of the lower bob.

        l1:
            The length of the upper rod.

        l2:
            The length of the lower rod.

        g:
            The gravitational acceleration.

    Returns:
        system:
            The system, with the angles `pendulum.theta1` and `pendulum.theta2` of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import double_pendulum
        >>> double_pendulum(m2=2.0).elements[0].m2
        2.0
    """
    return System(
        elements=[
            DoublePendulumElement(
                'pendulum',
                theta1=theta1,
                theta2=theta2,
                theta1_d1=omega1,
                theta2_d1=omega2,
                m1=m1,
                m2=m2,
                l1=l1,
                l2=l2,
                g=g,
            ),
        ],
        interactions=[DoublePendulumInteraction('motion', target='pendulum')],
    )

driven_damped_oscillator(x=1.0, v=0.0, *, m=1.0, k=1.0, c=0.1, F=0.0, omega=1.0)

Return a mass on a spring with damping and a periodic force, m x'' = -k x - c x' + F cos(ω t).

Parameters:

Name	Type	Description	Default
x	float	The initial displacement.	1.0
v	float	The initial velocity.	0.0
m	float	The mass.	1.0
k	float	The stiffness.	1.0
c	float	The damping coefficient.	0.1
F	float	The amplitude of the driving force.	0.0
omega	float	The angular frequency of the driving force.	1.0

Returns:

Name	Type	Description
system	System	The system, with the mass mass in one dimension, whose displacement mass.x has order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import driven_damped_oscillator
>>> driven_damped_oscillator(F=0.5).interactions[2].F
0.5

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'oscillation', 'forcing'),
    references=('Hooke 1678',),
    defaults={'until': 50.0, 'dt': 0.05},
)
def driven_damped_oscillator(
    x: float = 1.0,
    v: float = 0.0,
    *,
    m: float = 1.0,
    k: float = 1.0,
    c: float = 0.1,
    F: float = 0.0,
    omega: float = 1.0,
) -> System:
    """Return a mass on a spring with damping and a periodic force, `m x'' = -k x - c x' + F cos(ω t)`.

    Args:
        x:
            The initial displacement.

        v:
            The initial velocity.

        m:
            The mass.

        k:
            The stiffness.

        c:
            The damping coefficient.

        F:
            The amplitude of the driving force.

        omega:
            The angular frequency of the driving force.

    Returns:
        system:
            The system, with the mass `mass` in one dimension, whose displacement `mass.x` has order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import driven_damped_oscillator
        >>> driven_damped_oscillator(F=0.5).interactions[2].F
        0.5
    """
    return System(
        elements=[MassPointElement('mass', x=x, x_d1=v, m=m)],
        interactions=[
            HarmonicPotentialInteraction('spring', target='mass', k=k),
            DampingInteraction('damping', target='mass', gamma=c),
            HarmonicForceInteraction('drive', target='mass', F=F, omega=omega),
        ],
        space=ContinuousSpace(n_dim=1),
    )

friction_oscillator(x=1.03, v=0.0, *, m=1.0, k=1.0, c=0.0, mu_s=0.06, mu_k=0.05, g=1.0, v_stick=0.01)

Return a mass on a linear spring with static, Coulomb, and viscous friction, m x'' + c x' + k x + f = 0.

While the mass slides, the friction f = mu_k m g sign(x') opposes its motion, so in each half of the phase plane the motion is linear, around the shifted centres x = ∓ mu_k m g / k. At rest the static friction holds the mass while |k x| <= mu_s m g, so the system has a whole segment of equilibria rather than isolated ones. Without viscous friction, every half swing ends 2 mu_k m g / k closer to the origin, and the mass sticks at the first turning point inside the segment, after finitely many swings. The friction is discontinuous, so the mass counts as at rest below the speed v_stick.

Parameters:

Name	Type	Description	Default
x	float	The initial position.	1.03
v	float	The initial velocity.	0.0
m	float	The mass.	1.0
k	float	The stiffness of the spring.	1.0
c	float	The viscous friction coefficient.	0.0
mu_s	float	The static friction coefficient.	0.06
mu_k	float	The kinetic friction coefficient.	0.05
g	float	The gravitational acceleration.	1.0
v_stick	float	The speed below which the mass counts as at rest.	0.01

Returns:

Name	Type	Description
system	System	The system, with the position mass.x and the velocity mass.v.

Examples:

>>> from skcomplex.systems.physics.mechanics import friction_oscillator
>>> friction_oscillator(mu_k=0.1).elements[0].mu_k
0.1

Source code in src/skcomplex/systems/physics/mechanics/_accelerators.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'friction', 'stick-slip', 'piecewise linear'),
    references=('Khalil 2002', 'Trzaska 2023'),
    defaults={'until': 40.0, 'dt': 0.01, 'solver': RK4Solver(dt=0.005)},
)
def friction_oscillator(
    x: float = 1.03,
    v: float = 0.0,
    *,
    m: float = 1.0,
    k: float = 1.0,
    c: float = 0.0,
    mu_s: float = 0.06,
    mu_k: float = 0.05,
    g: float = 1.0,
    v_stick: float = 0.01,
) -> System:
    """Return a mass on a linear spring with static, Coulomb, and viscous friction, `m x'' + c x' + k x + f = 0`.

    While the mass slides, the friction `f = mu_k m g sign(x')` opposes its motion, so in each half of the phase plane
    the motion is linear, around the shifted centres `x = ∓ mu_k m g / k`. At rest the static friction holds the mass
    while `|k x| <= mu_s m g`, so the system has a whole segment of equilibria rather than isolated ones. Without
    viscous friction, every half swing ends `2 mu_k m g / k` closer to the origin, and the mass sticks at the first
    turning point inside the segment, after finitely many swings. The friction is discontinuous, so the mass counts
    as at rest below the speed `v_stick`.

    Args:
        x:
            The initial position.

        v:
            The initial velocity.

        m:
            The mass.

        k:
            The stiffness of the spring.

        c:
            The viscous friction coefficient.

        mu_s:
            The static friction coefficient.

        mu_k:
            The kinetic friction coefficient.

        g:
            The gravitational acceleration.

        v_stick:
            The speed below which the mass counts as at rest.

    Returns:
        system:
            The system, with the position `mass.x` and the velocity `mass.v`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import friction_oscillator
        >>> friction_oscillator(mu_k=0.1).elements[0].mu_k
        0.1
    """
    mass = FrictionOscillatorElement('mass', x=x, v=v, m=m, k=k, c=c, mu_s=mu_s, mu_k=mu_k, g=g, v_stick=v_stick)
    return System(elements=[mass])

gimballed_gyroscope(spin=50.0, beta=0.3, *, A=1.0, C=2.0, A1=0.5, B1=0.5, C1=0.5, A2=1.0, torque=1.0)

Return a gyroscope in a gimbal: a rotor in an inner ring that turns in an outer ring about a fixed axis.

The outer ring turns by alpha about the fixed axis, the inner ring by beta in the outer ring, and the rotor spins by gamma in the inner ring. The equations are the Lagrange equations of the kinetic energy [A2 + (A + A1) cos² beta + (C + C1) sin² beta] alpha'² / 2 + (A + B1) beta'² / 2 + C alpha' gamma' sin beta + C gamma'² / 2, with a torque on the axis of the inner ring, which makes the fast rotor precess about the fixed axis. The momenta conjugate to alpha and gamma are conserved.

Parameters:

Name	Type	Description	Default
spin	float	The initial angular velocity of the rotor in the inner ring.	50.0
beta	float	The initial angle of the inner ring.	0.3
A	float	The equatorial moment of inertia of the rotor.	1.0
C	float	The polar moment of inertia of the rotor.	2.0
A1	float	The first principal moment of inertia of the inner ring.	0.5
B1	float	The second principal moment of inertia of the inner ring.	0.5
C1	float	The third principal moment of inertia of the inner ring.	0.5
A2	float	The moment of inertia of the outer ring about its axis.	1.0
torque	float	The torque on the axis of the inner ring.	1.0

Returns:

Name	Type	Description
system	System	The system, with the angles gyroscope.alpha, gyroscope.beta, and gyroscope.gamma, all of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import gimballed_gyroscope
>>> gimballed_gyroscope(spin=10.0).elements[0].gamma_d1
10.0

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'rotation', 'gyroscope', 'lagrangian'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 10.0, 'dt': 0.01},
)
def gimballed_gyroscope(
    spin: float = 50.0,
    beta: float = 0.3,
    *,
    A: float = 1.0,
    C: float = 2.0,
    A1: float = 0.5,
    B1: float = 0.5,
    C1: float = 0.5,
    A2: float = 1.0,
    torque: float = 1.0,
) -> System:
    """Return a gyroscope in a gimbal: a rotor in an inner ring that turns in an outer ring about a fixed axis.

    The outer ring turns by `alpha` about the fixed axis, the inner ring by `beta` in the outer ring, and the rotor
    spins by `gamma` in the inner ring. The equations are the Lagrange equations of the kinetic energy
    `[A2 + (A + A1) cos² beta + (C + C1) sin² beta] alpha'² / 2 + (A + B1) beta'² / 2 + C alpha' gamma' sin beta
    + C gamma'² / 2`, with a torque on the axis of the inner ring, which makes the fast rotor precess about the fixed
    axis. The momenta conjugate to `alpha` and `gamma` are conserved.

    Args:
        spin:
            The initial angular velocity of the rotor in the inner ring.

        beta:
            The initial angle of the inner ring.

        A:
            The equatorial moment of inertia of the rotor.

        C:
            The polar moment of inertia of the rotor.

        A1:
            The first principal moment of inertia of the inner ring.

        B1:
            The second principal moment of inertia of the inner ring.

        C1:
            The third principal moment of inertia of the inner ring.

        A2:
            The moment of inertia of the outer ring about its axis.

        torque:
            The torque on the axis of the inner ring.

    Returns:
        system:
            The system, with the angles `gyroscope.alpha`, `gyroscope.beta`, and `gyroscope.gamma`, all of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import gimballed_gyroscope
        >>> gimballed_gyroscope(spin=10.0).elements[0].gamma_d1
        10.0
    """
    return System(
        elements=[
            GyroscopeElement(
                'gyroscope',
                beta=beta,
                gamma_d1=spin,
                A=A,
                C=C,
                A1=A1,
                B1=B1,
                C1=C1,
                A2=A2,
                torque=torque,
            ),
        ],
        interactions=[GyroscopeInteraction('motion', target='gyroscope')],
    )

harmonic_oscillator(x=1.0, v=0.0, *, k=1.0, mass=1.0, damping=0.0)

Return a particle on a spring, optionally damped.

Parameters:

Name	Type	Description	Default
x	float	The initial displacement.	1.0
v	float	The initial velocity.	0.0
k	float	The stiffness.	1.0
mass	float	The mass.	1.0
damping	float	The linear damping coefficient.	0.0

Returns:

Name	Type	Description
system	System	The system, with the particle mass in one dimension.

Examples:

>>> from skcomplex.systems.physics.mechanics import harmonic_oscillator
>>> harmonic_oscillator(k=4.0).interactions[0].k
4.0

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'oscillation'),
    references=('Hooke 1678',),
    defaults={'until': 20.0, 'dt': 0.05},
)
def harmonic_oscillator(
    x: float = 1.0,
    v: float = 0.0,
    *,
    k: float = 1.0,
    mass: float = 1.0,
    damping: float = 0.0,
) -> System:
    """Return a particle on a spring, optionally damped.

    Args:
        x:
            The initial displacement.

        v:
            The initial velocity.

        k:
            The stiffness.

        mass:
            The mass.

        damping:
            The linear damping coefficient.

    Returns:
        system:
            The system, with the particle `mass` in one dimension.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import harmonic_oscillator
        >>> harmonic_oscillator(k=4.0).interactions[0].k
        4.0
    """
    interactions: list[BaseInteraction] = [HarmonicPotentialInteraction('spring', target='mass', k=k)]
    if damping:
        interactions.append(DampingInteraction('damping', target='mass', gamma=damping))
    return System(
        elements=[MassPointElement('mass', x=x, x_d1=v, m=mass)],
        interactions=interactions,
        space=ContinuousSpace(n_dim=1),
    )

huygens_clocks(n_clocks=2, *, theta=0.2, k=1.0, m=1.0, l=1.0, M=1.0, g=9.8, rho=0.1, lam=0.1, theta_c=0.1)

Return pendulum clocks on supports joined by springs, which synchronize through the motion of the supports.

Every pendulum hangs from a support of mass M that moves horizontally with damping rho, and neighbouring supports are joined by springs of stiffness k. A pendulum follows m l θ'' + f(θ) θ' + m g sin θ = -m x'' cos θ and its support (M + m) x'' + 2 rho x' + m l θ'' cos θ = m l θ'² sin θ + spring forces. The escapement f(θ) = 2 λ sgn(|θ| - θ_c) is -2 λ for |θ| < θ_c, pumping energy in, and 2 λ beyond, so every clock has a limit cycle. With λ = 0 the clocks are plain pendulums. Two identical clocks synchronize in antiphase. The first clock starts at theta, away from the switch of the escapement at θ_c, and the others at rest.

Parameters:

Name	Type	Description	Default
n_clocks	int	The number of clocks in the row.	2
theta	float	The initial angle of the first clock. The others start at rest.	0.2
k	float	The stiffness of the springs between neighbouring supports.	1.0
m	float	The mass of every bob.	1.0
l	float	The length of every pendulum.	1.0
M	float	The mass of every support.	1.0
g	float	The gravitational acceleration.	9.8
rho	float	The damping of the supports.	0.1
lam	float	The strength of the escapement.	0.1
theta_c	float	The angle below which the escapement pumps energy in.	0.1

Returns:

Name	Type	Description
system	System	The system, with the angles clock_<i>.theta and the support positions clock_<i>.x, all of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import huygens_clocks
>>> len(huygens_clocks(3).interactions)
5

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'synchronization', 'limit cycle'),
    references=('Huygens 1673', 'Dilão 2023', 'Dilão 2023'),
    defaults={'until': 20.0, 'dt': 0.05},
)
def huygens_clocks(
    n_clocks: int = 2,
    *,
    theta: float = 0.2,
    k: float = 1.0,
    m: float = 1.0,
    l: float = 1.0,
    M: float = 1.0,
    g: float = 9.8,
    rho: float = 0.1,
    lam: float = 0.1,
    theta_c: float = 0.1,
) -> System:
    """Return pendulum clocks on supports joined by springs, which synchronize through the motion of the supports.

    Every pendulum hangs from a support of mass `M` that moves horizontally with damping `rho`, and neighbouring
    supports are joined by springs of stiffness `k`. A pendulum follows `m l θ'' + f(θ) θ' + m g sin θ = -m x'' cos θ`
    and its support `(M + m) x'' + 2 rho x' + m l θ'' cos θ = m l θ'² sin θ + spring forces`. The escapement
    `f(θ) = 2 λ sgn(|θ| - θ_c)` is `-2 λ` for `|θ| < θ_c`, pumping energy in, and `2 λ` beyond, so every clock has a
    limit cycle. With `λ = 0` the clocks are plain pendulums. Two identical clocks synchronize in antiphase. The
    first clock starts at `theta`, away from the switch of the escapement at `θ_c`, and the others at rest.

    Args:
        n_clocks:
            The number of clocks in the row.

        theta:
            The initial angle of the first clock. The others start at rest.

        k:
            The stiffness of the springs between neighbouring supports.

        m:
            The mass of every bob.

        l:
            The length of every pendulum.

        M:
            The mass of every support.

        g:
            The gravitational acceleration.

        rho:
            The damping of the supports.

        lam:
            The strength of the escapement.

        theta_c:
            The angle below which the escapement pumps energy in.

    Returns:
        system:
            The system, with the angles `clock_<i>.theta` and the support positions `clock_<i>.x`, all of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import huygens_clocks
        >>> len(huygens_clocks(3).interactions)
        5
    """
    clocks = [
        ClockPendulumElement(
            f'clock_{index}',
            theta=theta if index == 0 else 0.0,
            m=m,
            l=l,
            M=M,
            g=g,
            rho=rho,
            lam=lam,
            theta_c=theta_c,
        )
        for index in range(n_clocks)
    ]
    springs = [
        SupportSpringInteraction(f'spring_{index}', first=f'clock_{index}', second=f'clock_{index + 1}', k=k)
        for index in range(n_clocks - 1)
    ]
    motions = [ClockPendulumInteraction(f'motion_{index}', target=f'clock_{index}') for index in range(n_clocks)]
    return System(elements=clocks, interactions=[*springs, *motions])

magnetic_pendulum(x=1.0, y=1.5, *, n_magnets=3, omega=1.0, q=0.2, gamma=1.0, d=0.3)

Return a magnetic bob on a string swinging above magnets on a circle, which comes to rest at one of them.

The bob follows x'' = -ω² x - q x' - Σ gamma (x - x_i) / d_i³ with d_i = sqrt(|x - x_i|² + d²). The basins of the magnets have fractal boundaries.

Parameters:

Name	Type	Description	Default
x	float	The initial horizontal position of the bob.	1.0
y	float	The initial vertical position of the bob.	1.5
n_magnets	int	The number of magnets, evenly spaced on the unit circle.	3
omega	float	The natural frequency of the pendulum.	1.0
q	float	The friction coefficient.	0.2
gamma	float	The strength of every magnet.	1.0
d	float	The height of the bob above the plane of the magnets.	0.3

Returns:

Name	Type	Description
system	System	The system, with the bob bob and its position bob.x in two dimensions.

Examples:

>>> from skcomplex.systems.physics.mechanics import magnetic_pendulum
>>> len(magnetic_pendulum(n_magnets=4).interactions)
6

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'multistability', 'fractal basins'),
    references=('Datseris and Parlitz 2022',),
    defaults={'until': 50.0, 'dt': 0.05},
)
def magnetic_pendulum(
    x: float = 1.0,
    y: float = 1.5,
    *,
    n_magnets: int = 3,
    omega: float = 1.0,
    q: float = 0.2,
    gamma: float = 1.0,
    d: float = 0.3,
) -> System:
    """Return a magnetic bob on a string swinging above magnets on a circle, which comes to rest at one of them.

    The bob follows `x'' = -ω² x - q x' - Σ gamma (x - x_i) / d_i³` with `d_i = sqrt(|x - x_i|² + d²)`. The basins of
    the magnets have fractal boundaries.

    Args:
        x:
            The initial horizontal position of the bob.

        y:
            The initial vertical position of the bob.

        n_magnets:
            The number of magnets, evenly spaced on the unit circle.

        omega:
            The natural frequency of the pendulum.

        q:
            The friction coefficient.

        gamma:
            The strength of every magnet.

        d:
            The height of the bob above the plane of the magnets.

    Returns:
        system:
            The system, with the bob `bob` and its position `bob.x` in two dimensions.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import magnetic_pendulum
        >>> len(magnetic_pendulum(n_magnets=4).interactions)
        6
    """
    angles = 2 * np.pi * np.arange(n_magnets) / n_magnets
    magnets = [
        MagnetInteraction(
            f'magnet_{index}',
            target='bob',
            center=[round(float(np.cos(angle)), 12), round(float(np.sin(angle)), 12)],
            gamma=gamma,
            d=d,
        )
        for index, angle in enumerate(angles)
    ]
    return System(
        elements=[MassPointElement('bob', x=[x, y], x_d1=[0.0, 0.0])],
        interactions=[
            HarmonicPotentialInteraction('string', target='bob', k=omega**2),
            DampingInteraction('friction', target='bob', gamma=q),
            *magnets,
        ],
        space=ContinuousSpace(n_dim=2),
    )

newtons_cradle(n_balls=5, *, speed=0.5, diameter=0.1, gap=0.001, length=1.0, g=9.81)

Return Newton's cradle: pendulum balls in a row that pass momentum along by elastic collisions.

The balls swing with small amplitude about rest positions that leave a small gap between neighbours, so collisions are separate events. The first ball starts with a speed towards the others, and equal masses exchange velocities at every collision.

Parameters:

Name	Type	Description	Default
n_balls	int	The number of balls.	5
speed	float	The initial speed of the first ball.	0.5
diameter	float	The diameter of the balls.	0.1
gap	float	The gap between neighbouring balls at rest.	0.001
length	float	The length of the pendulums.	1.0
g	float	The gravitational acceleration.	9.81

Returns:

Name	Type	Description
system	System	The system, with the horizontal positions ball_<i>.x and velocities ball_<i>.x_d1.

Examples:

>>> from skcomplex.systems.physics.mechanics import newtons_cradle
>>> len(newtons_cradle(n_balls=3).interactions)
5

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'events', 'impacts', 'momentum'),
    references=('Hinch and Saint-Jean 1999',),
    defaults={'until': 5.0, 'dt': 0.01},
)
def newtons_cradle(
    n_balls: int = 5,
    *,
    speed: float = 0.5,
    diameter: float = 0.1,
    gap: float = 0.001,
    length: float = 1.0,
    g: float = 9.81,
) -> System:
    """Return Newton's cradle: pendulum balls in a row that pass momentum along by elastic collisions.

    The balls swing with small amplitude about rest positions that leave a small gap between neighbours, so collisions
    are separate events. The first ball starts with a speed towards the others, and equal masses exchange velocities
    at every collision.

    Args:
        n_balls:
            The number of balls.

        speed:
            The initial speed of the first ball.

        diameter:
            The diameter of the balls.

        gap:
            The gap between neighbouring balls at rest.

        length:
            The length of the pendulums.

        g:
            The gravitational acceleration.

    Returns:
        system:
            The system, with the horizontal positions `ball_<i>.x` and velocities `ball_<i>.x_d1`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import newtons_cradle
        >>> len(newtons_cradle(n_balls=3).interactions)
        5
    """
    spacing = diameter + gap
    elements = [
        HangingBallElement(
            f'ball_{index}',
            x=index * spacing,
            x_d1=speed if index == 0 else 0.0,
            rest=index * spacing,
            g=g,
            length=length,
        )
        for index in range(n_balls)
    ]
    swings: list[BaseInteraction] = [
        GradientInteraction(
            f'swing_{index}',
            target=f'ball_{index}',
            potential=lambda s: s.target.g * (s.target.x - s.target.rest) ** 2 / (2 * s.target.length),
        )
        for index in range(n_balls)
    ]
    collisions: list[BaseInteraction] = [
        ElasticCollisionInteraction(
            f'collision_{index}',
            left=f'ball_{index}',
            right=f'ball_{index + 1}',
            diameter=diameter,
        )
        for index in range(n_balls - 1)
    ]
    return System(elements=elements, interactions=[*swings, *collisions])

parametric_pendulum(theta=0.1, omega=0.0, *, g=9.81, l=1.0, epsilon=0.2, Omega=2 * math.sqrt(9.81), c=0.0, direction='vertical')

Return a pendulum whose suspension point oscillates vertically or horizontally, with acceleration ε g cos Ω t.

Vertically, the acceleration of the suspension point modulates gravity, θ'' + c θ' + (g / l)(1 + ε cos Ω t) sin θ = 0. Small oscillations grow when Ω is close to twice the natural frequency sqrt(g / l), the parametric resonance of a swing, while a pendulum at rest stays at rest. Horizontally, the acceleration pushes the bob sideways, θ'' + c θ' + (g / l)(sin θ + ε cos Ω t cos θ) = 0, which for small angles is a harmonic oscillator under an external force. Its amplitude grows linearly in time, as ε Ω t / 2, when Ω equals the natural frequency, the linear resonance, and the pendulum starts to swing even from rest.

Parameters:

Name	Type	Description	Default
theta	float	The initial angle.	0.1
omega	float	The initial angular velocity.	0.0
g	float	The gravitational acceleration.	9.81
l	float	The length of the rod.	1.0
epsilon	float	The amplitude of the acceleration of the suspension point, relative to g.	0.2
Omega	float	The angular frequency of the suspension point.	2 * sqrt(9.81)
c	float	The friction coefficient.	0.0
direction	str	The direction in which the suspension point oscillates, 'vertical' or 'horizontal'.	'vertical'

Returns:

Name	Type	Description
system	System	The system, with the angle swing.theta of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import parametric_pendulum
>>> parametric_pendulum(epsilon=0.5).elements[0].epsilon
0.5

Source code in src/skcomplex/systems/physics/mechanics/_pendulums.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'forcing', 'parametric resonance'),
    references=('Dilão 2023',),
    defaults={'until': 30.0, 'dt': 0.02},
)
def parametric_pendulum(
    theta: float = 0.1,
    omega: float = 0.0,
    *,
    g: float = 9.81,
    l: float = 1.0,
    epsilon: float = 0.2,
    Omega: float = 2 * math.sqrt(9.81),
    c: float = 0.0,
    direction: str = 'vertical',
) -> System:
    """Return a pendulum whose suspension point oscillates vertically or horizontally, with acceleration `ε g cos Ω t`.

    Vertically, the acceleration of the suspension point modulates gravity, `θ'' + c θ' + (g / l)(1 + ε cos Ω t) sin θ
    = 0`. Small oscillations grow when `Ω` is close to twice the natural frequency `sqrt(g / l)`, the parametric
    resonance of a swing, while a pendulum at rest stays at rest. Horizontally, the acceleration pushes the bob
    sideways, `θ'' + c θ' + (g / l)(sin θ + ε cos Ω t cos θ) = 0`, which for small angles is a harmonic oscillator under
    an external force. Its amplitude grows linearly in time, as `ε Ω t / 2`, when `Ω` equals the natural frequency,
    the linear resonance, and the pendulum starts to swing even from rest.

    Args:
        theta:
            The initial angle.

        omega:
            The initial angular velocity.

        g:
            The gravitational acceleration.

        l:
            The length of the rod.

        epsilon:
            The amplitude of the acceleration of the suspension point, relative to `g`.

        Omega:
            The angular frequency of the suspension point.

        c:
            The friction coefficient.

        direction:
            The direction in which the suspension point oscillates, `'vertical'` or `'horizontal'`.

    Returns:
        system:
            The system, with the angle `swing.theta` of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import parametric_pendulum
        >>> parametric_pendulum(epsilon=0.5).elements[0].epsilon
        0.5
    """
    return System(
        elements=[
            ParametricPendulumElement(
                'swing',
                theta=theta,
                theta_d1=omega,
                g=g,
                l=l,
                epsilon=epsilon,
                Omega=Omega,
                c=c,
            ),
        ],
        interactions=[ParametricPendulumInteraction('motion', target='swing', direction=direction)],
    )

particle_in_a_well(x=1.0, v=0.5, *, k=2.0, m=1.0)

Return a particle moving without friction in the potential U(x) = k x² e^-x.

The potential has a stable equilibrium at x = 0 and an unstable one at x = 2, the top of a barrier of height 4 k e^-2. A particle in the well with less energy than the barrier oscillates, and one with more escapes to large x.

Parameters:

Name	Type	Description	Default
x	float	The initial position.	1.0
v	float	The initial velocity.	0.5
k	float	The strength of the potential.	2.0
m	float	The mass of the particle.	1.0

Returns:

Name	Type	Description
system	System	The system, with the particle particle and its position particle.x in one dimension.

Examples:

>>> from skcomplex.systems.physics.mechanics import particle_in_a_well
>>> particle_in_a_well(k=3.0).interactions[0].k
3.0

Source code in src/skcomplex/systems/physics/mechanics/_wells.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'potential', 'hamiltonian'),
    references=('Starkovich 2021',),
    defaults={'until': 20.0, 'dt': 0.05},
)
def particle_in_a_well(x: float = 1.0, v: float = 0.5, *, k: float = 2.0, m: float = 1.0) -> System:
    """Return a particle moving without friction in the potential `U(x) = k x² e^-x`.

    The potential has a stable equilibrium at `x = 0` and an unstable one at `x = 2`, the top of a barrier of height
    `4 k e^-2`. A particle in the well with less energy than the barrier oscillates, and one with more escapes to
    large `x`.

    Args:
        x:
            The initial position.

        v:
            The initial velocity.

        k:
            The strength of the potential.

        m:
            The mass of the particle.

    Returns:
        system:
            The system, with the particle `particle` and its position `particle.x` in one dimension.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import particle_in_a_well
        >>> particle_in_a_well(k=3.0).interactions[0].k
        3.0
    """
    return System(
        elements=[MassPointElement('particle', x=x, x_d1=v, m=m)],
        interactions=[ExponentialWellInteraction('well', target='particle', k=k)],
        space=ContinuousSpace(n_dim=1),
    )

pendulum(theta=0.5, omega=0.0, *, m=1.0, g=9.81, l=1.0)

Return a pendulum, whose angle follows Newton's second law m l θ'' = -m g sin θ.

Parameters:

Name	Type	Description	Default
theta	float	The initial angle, in radians.	0.5
omega	float	The initial angular velocity.	0.0
m	float	The mass of the bob.	1.0
g	float	The gravitational acceleration.	9.81
l	float	The length of the rod.	1.0

Returns:

Name	Type	Description
system	System	The system, with the pendulum bob, whose angle has order 2 and angular velocity bob.theta_d1.

Examples:

>>> from skcomplex.systems.physics.mechanics import pendulum
>>> pendulum(theta=0.1).elements[0].theta_d1
0.0

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'oscillation'),
    references=('Newton 1687',),
    defaults={'until': 10.0, 'dt': 0.01},
)
def pendulum(
    theta: float = 0.5,
    omega: float = 0.0,
    *,
    m: float = 1.0,
    g: float = 9.81,
    l: float = 1.0,
) -> System:
    """Return a pendulum, whose angle follows Newton's second law `m l θ'' = -m g sin θ`.

    Args:
        theta:
            The initial angle, in radians.

        omega:
            The initial angular velocity.

        m:
            The mass of the bob.

        g:
            The gravitational acceleration.

        l:
            The length of the rod.

    Returns:
        system:
            The system, with the pendulum `bob`, whose angle has order 2 and angular velocity `bob.theta_d1`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import pendulum
        >>> pendulum(theta=0.1).elements[0].theta_d1
        0.0
    """
    return System(
        elements=[PendulumElement('bob', theta=theta, theta_d1=omega, m=m, g=g, l=l)],
        interactions=[PendulumInteraction('swing', target='bob')],
    )

projectile(speed=10.0, angle=45.0, *, mass=1.0, drag=0.0)

Return a particle launched under uniform gravity, optionally slowed by linear drag.

Parameters:

Name	Type	Description	Default
speed	float	The launch speed.	10.0
angle	float	The launch angle above the horizon, in degrees.	45.0
mass	float	The mass.	1.0
drag	float	The linear drag coefficient.	0.0

Returns:

Name	Type	Description
system	System	The system, with the particle ball in two dimensions.

Examples:

>>> from skcomplex.systems.physics.mechanics import projectile
>>> projectile(speed=5.0, angle=90.0).elements[0].x_d1[1]
5.0

Source code in src/skcomplex/systems/physics/mechanics/_mechanics.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode'),
    references=('Newton 1687',),
    defaults={'until': 2.0, 'dt': 0.01},
)
def projectile(speed: float = 10.0, angle: float = 45.0, *, mass: float = 1.0, drag: float = 0.0) -> System:
    """Return a particle launched under uniform gravity, optionally slowed by linear drag.

    Args:
        speed:
            The launch speed.

        angle:
            The launch angle above the horizon, in degrees.

        mass:
            The mass.

        drag:
            The linear drag coefficient.

    Returns:
        system:
            The system, with the particle `ball` in two dimensions.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import projectile
        >>> projectile(speed=5.0, angle=90.0).elements[0].x_d1[1]
        5.0
    """
    radians = np.radians(angle)
    velocity = [round(float(speed * np.cos(radians)), 12), round(float(speed * np.sin(radians)), 12)]
    interactions: list[BaseInteraction] = [
        ConstantForceInteraction('gravity', target='ball', F=[0.0, -GRAVITY * mass]),
    ]
    if drag:
        interactions.append(DampingInteraction('drag', target='ball', gamma=drag))
    return System(
        elements=[MassPointElement('ball', x=[0.0, 0.0], x_d1=velocity, m=mass)],
        interactions=interactions,
        space=ContinuousSpace(n_dim=2),
    )

rotating_balls_on_rods(omega=1.0, *, r=1.0, beta=math.pi / 2, m=1.0)

Return two balls on rods that turn about a vertical axis and conserve their angular momentum.

Each ball sits at the distance r along a rod fixed at the angle β to the axis, so its distance from the axis is r sin β. Its angular momentum H = m ω r² sin² β is fixed by the initial angular velocity, and the balls turn at θ' = H / (m r² sin² β), so changing r during a run changes the angular velocity by 1 / r².

Parameters:

Name	Type	Description	Default
omega	float	The initial angular velocity.	1.0
r	float	The distance of the balls from the joint of the rods.	1.0
beta	float	The angle of the rods to the vertical axis, in radians.	pi / 2
m	float	The mass of every ball.	1.0

Returns:

Name	Type	Description
system	System	The system, with the angles right.theta and left.theta of the two balls.

Examples:

>>> from skcomplex.systems.physics.mechanics import rotating_balls_on_rods
>>> rotating_balls_on_rods(omega=2.0).elements[0].H
2.0

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'rotation', 'angular momentum'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 10.0, 'dt': 0.02},
)
def rotating_balls_on_rods(
    omega: float = 1.0,
    *,
    r: float = 1.0,
    beta: float = math.pi / 2,
    m: float = 1.0,
) -> System:
    """Return two balls on rods that turn about a vertical axis and conserve their angular momentum.

    Each ball sits at the distance `r` along a rod fixed at the angle `β` to the axis, so its distance from the axis is
    `r sin β`. Its angular momentum `H = m ω r² sin² β` is fixed by the initial angular velocity, and the balls turn at
    `θ' = H / (m r² sin² β)`, so changing `r` during a run changes the angular velocity by `1 / r²`.

    Args:
        omega:
            The initial angular velocity.

        r:
            The distance of the balls from the joint of the rods.

        beta:
            The angle of the rods to the vertical axis, in radians.

        m:
            The mass of every ball.

    Returns:
        system:
            The system, with the angles `right.theta` and `left.theta` of the two balls.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import rotating_balls_on_rods
        >>> rotating_balls_on_rods(omega=2.0).elements[0].H
        2.0
    """
    momentum = m * omega * r**2 * math.sin(beta) ** 2
    return System(
        elements=[
            RotatingBallElement('right', theta=0.0, m=m, r=r, beta=beta, H=momentum),
            RotatingBallElement('left', theta=math.pi, m=m, r=r, beta=beta, H=momentum),
        ],
        interactions=[
            RateInteraction(
                f'{ball}_turn',
                target=ball,
                state='theta',
                rate=lambda s: s.target.H / (s.target.m * s.target.r**2 * sin(s.target.beta) ** 2),
            )
            for ball in ('right', 'left')
        ],
    )

rotating_swing(omega=2.0, theta=0.1, *, n_chairs=8, J=10.0, m=1.0, a=1.0, l=1.0, g=9.81, torque=0.0, friction=0.0)

Return a rotating swing: chairs on chains hanging from the rods of a stand that turns about a vertical axis.

The stand of inertia J turns by the angle φ, and the chairs, all deflected by the same angle θ, follow the Lagrange equations [J + n m (a + l sin θ)²] φ'' + 2 n m l φ' θ' (a + l sin θ) cos θ = M - c φ' and l θ'' - φ'² (a + l sin θ) cos θ + g sin θ = 0. At a steady speed ω the chairs settle at the angle where g tan θ = ω² (a + l sin θ). Without torque and friction the angular momentum of the swing is conserved.

Parameters:

Name	Type	Description	Default
omega	float	The initial angular velocity of the stand.	2.0
theta	float	The initial angle of the chains from the vertical.	0.1
n_chairs	int	The number of chairs.	8
J	float	The moment of inertia of the stand.	10.0
m	float	The mass of every chair.	1.0
a	float	The length of the rods.	1.0
l	float	The length of the chains.	1.0
g	float	The gravitational acceleration.	9.81
torque	float	The torque that drives the stand.	0.0
friction	float	The friction coefficient of the stand's axis.	0.0

Returns:

Name	Type	Description
system	System	The system, with the angle of the stand swing.phi and of the chains swing.theta, both of order 2.

Examples:

>>> from skcomplex.systems.physics.mechanics import rotating_swing
>>> rotating_swing(omega=1.0).elements[0].phi_d1
1.0

Source code in src/skcomplex/systems/physics/mechanics/_rotations.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'second order', 'rotation', 'lagrangian'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 20.0, 'dt': 0.05},
)
def rotating_swing(
    omega: float = 2.0,
    theta: float = 0.1,
    *,
    n_chairs: int = 8,
    J: float = 10.0,
    m: float = 1.0,
    a: float = 1.0,
    l: float = 1.0,
    g: float = 9.81,
    torque: float = 0.0,
    friction: float = 0.0,
) -> System:
    """Return a rotating swing: chairs on chains hanging from the rods of a stand that turns about a vertical axis.

    The stand of inertia `J` turns by the angle `φ`, and the chairs, all deflected by the same angle `θ`, follow the
    Lagrange equations `[J + n m (a + l sin θ)²] φ'' + 2 n m l φ' θ' (a + l sin θ) cos θ = M - c φ'` and
    `l θ'' - φ'² (a + l sin θ) cos θ + g sin θ = 0`. At a steady speed `ω` the chairs settle at the angle where
    `g tan θ = ω² (a + l sin θ)`. Without torque and friction the angular momentum of the swing is conserved.

    Args:
        omega:
            The initial angular velocity of the stand.

        theta:
            The initial angle of the chains from the vertical.

        n_chairs:
            The number of chairs.

        J:
            The moment of inertia of the stand.

        m:
            The mass of every chair.

        a:
            The length of the rods.

        l:
            The length of the chains.

        g:
            The gravitational acceleration.

        torque:
            The torque that drives the stand.

        friction:
            The friction coefficient of the stand's axis.

    Returns:
        system:
            The system, with the angle of the stand `swing.phi` and of the chains `swing.theta`, both of order 2.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import rotating_swing
        >>> rotating_swing(omega=1.0).elements[0].phi_d1
        1.0
    """
    return System(
        elements=[
            RotatingSwingElement(
                'swing',
                phi_d1=omega,
                theta=theta,
                n_chairs=n_chairs,
                J=J,
                m=m,
                a=a,
                l=l,
                g=g,
                torque=torque,
                friction=friction,
            ),
        ],
        interactions=[RotatingSwingInteraction('motion', target='swing')],
    )

two_mass_spring_damper(x1=1.2, x2=2.0, *, m1=1.0, m2=1.0, k1=1.0, k2=1.0, k=1.0, b1=0.0, b2=0.0, l1=1.0, l2=1.0, F1=0.0, F2=0.0, omega1=1.0, omega2=1.0)

Return two masses between two walls, tied to the walls and to each other by springs, with dampers and forces.

The first mass rests at x01 = l1 and the second at x02 = l1 + l2. They follow m1 x1'' = -k1 (x1 - x01) + k ((x2 - x1) - (x02 - x01)) - b1 x1' + F1 cos(ω1 t) and m2 x2'' = -k ((x2 - x1) - (x02 - x01)) - k2 (x2 - x02) - b2 x2' + F2 cos(ω2 t).

Parameters:

Name	Type	Description	Default
x1	float	The initial position of the first mass.	1.2
x2	float	The initial position of the second mass.	2.0
m1	float	The first mass.	1.0
m2	float	The second mass.	1.0
k1	float	The stiffness of the spring between the left wall and the first mass.	1.0
k2	float	The stiffness of the spring between the second mass and the right wall.	1.0
k	float	The stiffness of the spring between the masses.	1.0
b1	float	The damping coefficient of the first mass.	0.0
b2	float	The damping coefficient of the second mass.	0.0
l1	float	The rest length of the first spring.	1.0
l2	float	The rest length of the middle spring.	1.0
F1	float	The amplitude of the periodic force on the first mass.	0.0
F2	float	The amplitude of the periodic force on the second mass.	0.0
omega1	float	The angular frequency of the force on the first mass.	1.0
omega2	float	The angular frequency of the force on the second mass.	1.0

Returns:

Name	Type	Description
system	System	The system, with the masses first and second and their positions first.x and second.x.

Examples:

>>> from skcomplex.systems.physics.mechanics import two_mass_spring_damper
>>> two_mass_spring_damper(l1=2.0).interactions[0].center
2.0

Source code in src/skcomplex/systems/physics/mechanics/_springs.py

@register_system(
    field='physics/mechanics',
    tags=('mechanics', 'ode', 'oscillation', 'normal modes', 'forcing'),
    references=('Ryzhov et al. 2021',),
    defaults={'until': 30.0, 'dt': 0.05},
)
def two_mass_spring_damper(
    x1: float = 1.2,
    x2: float = 2.0,
    *,
    m1: float = 1.0,
    m2: float = 1.0,
    k1: float = 1.0,
    k2: float = 1.0,
    k: float = 1.0,
    b1: float = 0.0,
    b2: float = 0.0,
    l1: float = 1.0,
    l2: float = 1.0,
    F1: float = 0.0,
    F2: float = 0.0,
    omega1: float = 1.0,
    omega2: float = 1.0,
) -> System:
    """Return two masses between two walls, tied to the walls and to each other by springs, with dampers and forces.

    The first mass rests at `x01 = l1` and the second at `x02 = l1 + l2`. They follow
    `m1 x1'' = -k1 (x1 - x01) + k ((x2 - x1) - (x02 - x01)) - b1 x1' + F1 cos(ω1 t)` and
    `m2 x2'' = -k ((x2 - x1) - (x02 - x01)) - k2 (x2 - x02) - b2 x2' + F2 cos(ω2 t)`.

    Args:
        x1:
            The initial position of the first mass.

        x2:
            The initial position of the second mass.

        m1:
            The first mass.

        m2:
            The second mass.

        k1:
            The stiffness of the spring between the left wall and the first mass.

        k2:
            The stiffness of the spring between the second mass and the right wall.

        k:
            The stiffness of the spring between the masses.

        b1:
            The damping coefficient of the first mass.

        b2:
            The damping coefficient of the second mass.

        l1:
            The rest length of the first spring.

        l2:
            The rest length of the middle spring.

        F1:
            The amplitude of the periodic force on the first mass.

        F2:
            The amplitude of the periodic force on the second mass.

        omega1:
            The angular frequency of the force on the first mass.

        omega2:
            The angular frequency of the force on the second mass.

    Returns:
        system:
            The system, with the masses `first` and `second` and their positions `first.x` and `second.x`.

    Examples:
        >>> from skcomplex.systems.physics.mechanics import two_mass_spring_damper
        >>> two_mass_spring_damper(l1=2.0).interactions[0].center
        2.0
    """
    rest1, rest2 = l1, l1 + l2
    return System(
        elements=[MassPointElement('first', x=x1, x_d1=0.0, m=m1), MassPointElement('second', x=x2, x_d1=0.0, m=m2)],
        interactions=[
            HarmonicPotentialInteraction('left_spring', target='first', k=k1, center=rest1),
            HarmonicPotentialInteraction('right_spring', target='second', k=k2, center=rest2),
            SpringInteraction('middle_spring', first='first', second='second', k=k, length=l2),
            DampingInteraction('first_damper', target='first', gamma=b1),
            DampingInteraction('second_damper', target='second', gamma=b2),
            HarmonicForceInteraction('first_force', target='first', F=F1, omega=omega1),
            HarmonicForceInteraction('second_force', target='second', F=F2, omega=omega2),
        ],
        space=ContinuousSpace(n_dim=1),
    )