# No. 24, Spur Gears (Brown 1868, p. 1).
#
# "24. Spur-gears."
#
# The plate shows two spur gears side by side in mesh, both seen face-on, each on its own horizontal
# shaft, with hubs keyed to the shafts. Counted on the plate: the LEFT gear is the smaller, 30 teeth;
# the right one the bigger, 40 (their diameters on the plate stand about 3 : 4) — so the two shafts do
# not turn equally fast, and the left gear must run faster to make the right keep up. Both gears share one module, so
# they mesh at the same tooth size; the radii are m·z/2 each and the shafts stand m·(z1+z2)/2 apart.
#
# Nothing but the left (smaller, driver) gear's shaft is motor-driven. The right gear is turned ONLY
# by tooth-on-tooth contact: one convex hull per tooth (the proven spur-pair fixture's generator,
# src/geom/involute.ts). Gear 2 is phased a half tooth over, so that gear 1's tooth pointing at it
# sits in a gap of gear 2 whose gap points back at gear 1.
#
# Expected ratio, from the pitch radii (hinge/hinge, both rad/s, so the ratio is a plain number):
# ω2/ω1 = -z1/z2 = -30/40 = -0.75 exactly.
number: 24
slug: spur-gears
name: Spur-gears
brown: "Spur-gears."
units: cm
sim:
  timestep: 0.0002
  integrator: implicitfast
  iterations: 100
  solver: CG          # the spur-pair fixture's solver: Newton diverged with tooth friction
  multiccd: true
  duration_s: 5
  floor: false        # the shafts run in their bearings, nothing stands on the ground
bodies:
  # The smaller driver on the left (x = 0), the larger gear on the right (x = 17.5), as the plate.
  - {id: g1, shape: assembly, pos: [0, 0, 10], color: "#e4d9bf"}     # shaft carries the 30-tooth driver
  - {id: g2, shape: assembly, pos: [17.5, 0, 10], color: "#e8dec6"}  # shaft carries the 40-tooth driven gear
  # The two shaft stubs, drawn as fixed rods: each gear turns about its own rod, which is
  # rotationally symmetric, so the stub need not turn with anything.
  - {id: stubs, shape: frame, rods: [{from: [0, -4.4, 10], to: [0, 4.4, 10], radius: 0.75}, {from: [17.5, -4.4, 10], to: [17.5, 4.4, 10], radius: 0.75}], color: "#8f8a80"}

joints:
  - {id: j_g1, type: hinge, body: g1, axis: [0, 1, 0], damping: 0.0005}
  - {id: j_g2, type: hinge, body: g2, axis: [0, 1, 0], damping: 0.05}  # a bearing's load on the driven shaft
spurs:
  # module 0.5 cm: r1 = 7.5, r2 = 10, centres 17.5 apart. Gear 2's phase is the one, of a scan over
  # a tooth pitch, that starts them clear of each other (half a tooth, pi/40).
  - {id: sp1, body: g1, pos: [0, 0, 0], teeth: 30, module: 0.5, width: 2.4, backlash: 0.02, phase: 0}
  - {id: sp2, body: g2, pos: [0, 0, 0], teeth: 40, module: 0.5, width: 2.4, backlash: 0.02, phase: 0.0785398}
# The two shaft stubs are drawn as fixed rods above: each gear turns about its own rod, which is
# rotationally symmetric, so the stub need not turn with anything.

contact: {solref: [0.002, 1], solimp: [0.95, 0.99, 0.0005], margin: 0}   # the teeth's own class, as in the fixture
driver: {joint: j_g1, kind: velocity, rpm: 30, kv: 2, max_torque: 5}
checks:
  # Pitch radii: module m = 0.5 cm, so r1 = 7.5 cm, r2 = 10 cm. Hinge/hinge is rad/rad, so ω2/ω1 =
  # -r1/r2 = -30/40 = -0.75 exactly (± 2 % of |ratio|), taken over a whole-tooth-steady window.
  - {type: ratio, out: j_g2, in: j_g1, expect: -0.75, tol: 0.015, settle_s: 1.5, window_s: 1}
  - {type: penetration, max: 0.0005, settle_s: 1.5}
camera: {target: [8.75, 0, 10], position: [8.75, -55, 12], fov: 34}   # face-on as the plate draws them
display:
  output: j_g2
  labels: {j_g1: "Driver (30 teeth)", j_g2: "Driven (40 teeth)"}
  expect: {default: -0.75}
  proof: {label: "Teeth out of contact", sub: "the driver turns alone: the 40-tooth gear stops"}