Hit Crossing

Shipping

hit_crossing

Zero-crossing event source: fires when a signal crosses a level in the chosen direction

Signature

Inputs

signalSignal|Scalar— The watched value (e.g. ball height y). Unwired = treated as 0.

Outputs

eventSignal— The zero-crossing function g = signal − level, watched by the solver for a sign change.

Parameters

Key	Type	Default	Notes
`level`	float	0.0	The event fires when the input signal crosses this level (e.g. 0 = the floor).
`direction`	enum	falling	one of: falling, rising, either

Description

Hit Crossing is a zero-crossing event source for the simulation engine — Captyse's version of Simulink's Hit Crossing block. It emits the crossing function $g = signal - level$ on its event output. Inside a Simulation compound running the adaptive ode45 solver, the solver watches $g$ for a sign change in the configured direction across each step, then localizes the exact crossing time by dense-output bisection and fires whatever is wired from event (typically an integrator's reset port).

This is what makes discontinuous physics correct: a bouncing ball reverses exactly at the floor rather than tunneling a bit past it and losing energy. Because the crossing is a modular block rather than baked into the integrator, you can watch any expression — a height, a switching surface, a threshold — and route the event anywhere.

On the ordinary acyclic dataflow path, or with a fixed-step solver, it is a benign passthrough emitting $g$ (the current signal minus level); only the adaptive solver acts on the sign change.

Mathematics

g (t) = signal (t) - level

event fires at t^{*} where g (t^{*}) = 0 with the chosen sign change

falling: g crosses 0^{+} \to 0^{-}, rising: 0^{-} \to 0^{+}, either: any

Examples

Detecting the floor for a bouncing ball

Wire the ball's height integrator output $y$ into signal, set level = 0 and direction = falling. The event output carries $g = y$ . On the adaptive solver, the exact moment $y$ crosses zero downward is localized and the wired velocity-integrator reset fires ( $v \leftarrow - e v$ ).

Rising threshold trigger

Watch a growing state against a trip level: set level = 5, direction = rising. The event fires the instant the signal passes $5$ upward — use it to reset an accumulator or latch a downstream block precisely at the threshold crossing.

Applications

Impact / contact events in mechanical simulation (bouncing ball, ratchet, clamped stop) that reset an integrator's state.
Threshold and switching-surface detection in hybrid/piecewise dynamics, localized to the exact crossing time.
Triggering state resets, mode switches, or event counts in a Simulation compound without smearing the discontinuity across a step.

Neat

The crossing is a first-class modular block, not baked into the integrator: any expression can be watched and the event routed to any reset port — a clean seam validated against analytic physics facts.

Localization is by dense-output bisection on the adaptive ode45 solver, so the event time is resolved far tighter than the visible step size.

The engine refuses to run event-bearing models on an event-blind (fixed-step) solver rather than silently producing wrong physics — an explicit honesty gate.

Known issues

Exact crossing localization requires the adaptive ode45 solver; with a fixed-step solver or on the acyclic path the block is just a passthrough emitting g and no event fires.

The `event` output carries no unit (it is the bare crossing function value).