Component reference

Two Tesseracts compose in the pipeline, plus a minimal third used only for the day-one boundary proof.

Every table on this page is generated at build time from the component’s own tesseract_api.py. The schema is the only source; nothing here is retyped, so a field cannot be documented with a shape or a differentiability flag it does not have. Where a field has units or a valid range, the schema states them in its description and they are reproduced verbatim.

contact-sim

Julia solver, all differentiable endpoints: apply, jacobian, jacobian_vector_product, vector_jacobian_product, abstract_eval.

Terrain is a sum of Gaussian bumps, h(x) = Σ ampᵢ exp(-(x - ctrᵢ)² / 2 widᵢ²), with amp, ctr and wid sharing one length, so the parameter count follows the bump count. The guard is g(q) = y - h(x).

Inputs

Field	Type	Shape	Diff.	Description
v0	Float64	(2)	yes	Launch velocity (vx, vy). Launch position is (0, y0).
y0	Float64	scalar	yes	Launch height (must start above the terrain). Default 1.0.
e	Float64	scalar	yes	Normal restitution coefficient in (0, 1]. Default 0.7.
mu	Float64	scalar	yes	Tangential velocity loss factor in [0, 1). Default 0.1.
amp	Float64	(n)	yes	Terrain Gaussian bump amplitudes (any number of bumps; amp/ctr/wid must share one length).
ctr	Float64	(n)	yes	Terrain bump centers.
wid	Float64	(n)	yes	Terrain bump widths (> 0).
drag	Float64	scalar	no	Linear drag coefficient, >= 0 (negative drag would add energy without bound). Also bounded jointly with dt: drag * dt must not exceed 2.785293563, the explicit RK4 stability limit, past which a dissipative force gains energy. Not differentiated. Default 0.0.
t_final	Float64	scalar	no	Simulation end time. Default 2.0.
dt	Float64	scalar	no	Integrator step size. Terrain features narrower than |vx|*dt/3 can be stepped over; choose dt <= min(wid)/(3 |vx|). With drag, dt is also bounded by drag * dt <= 2.785293563, the explicit RK4 stability limit. Default 0.001.
n_samples	int	scalar	no	Trajectory sample rows returned for visualization. Default 0.
v_stop	Float64	scalar	no	Normal-velocity floor, >= 0: if the post-impact normal velocity falls below this, the simulation stops at that impact with status=2 (chatter / settled contact; sticking and sliding are outside this model). Default 0.0001.

Outputs

Field	Type	Shape	Diff.	Description
qf	Float64	(4)	yes	State (x, y, vx, vy) at t_end. For status != 0 this is the state at the truncating event, and its Jacobian is the total derivative including event-time dependence.
impact_x	Float64	(MAX_EVENTS)	yes	x-coordinate of each impact, zero-padded to MAX_EVENTS. Only entries [:n_events] are meaningful; padded entries are exactly 0 with exactly-zero derivative rows, so gradient checks stay coherent. Always mask by n_events.
n_events	Int32	scalar	no	Number of impacts.
traj	Float64	(n, 5)	no	Sampled (t, x, y, vx, vy) rows for visualization.
status	Int32	scalar	no	0: ran to t_final. 1: event capacity (MAX_EVENTS) hit; stopped at that crossing. 2: contact settled (post-impact normal velocity < v_stop).
t_end	Float64	scalar	no	Time at which qf is measured (== t_final iff status == 0).

Padded entries of impact_x are exactly zero and carry exactly-zero derivative rows, so a gradient checker stays coherent across trajectories with different impact counts. Only impact_x[:n_events] is meaningful.

status is 0 when the run reached t_final, 1 when it hit the event capacity, and 2 when contact settled. For a nonzero status, qf is the state at the truncating event and its Jacobian is the total derivative including the event-time dependence, which is what keeps an optimizer from consuming a silently nonphysical state.

score-target

JAX objective built with the tesseract init --recipe jax endpoints. It takes the solver’s qf, a target position and three weights, and returns the scalar being optimized along with the miss distance used for reporting.

Inputs

Field	Type	Shape	Diff.	Description
qf	Float64	(4)	yes	Final state (x, y, vx, vy) from the contact solver.
target	Float64	(2)	yes	Cup position (x*, y*).
weights	Float64	(3)	no	Loss weights (position-x, position-y, kinetic).

Outputs

Field	Type	Shape	Diff.	Description
loss	Float64	scalar	yes	w1 (x - x*)^2 + w2 (y - y*)^2 + w3 |v|^2. Land in the cup, gently.
miss_distance	Float64	scalar	yes	Euclidean distance from (x, y) to the cup.

julia_kernel

The minimal day-one boundary proof: a Julia function with a hand-written adjoint, used by scripts/proof_local.py and scripts/proof_container.py to show jax.grad crossing the component boundary and matching the analytic derivative to 1e-12. It computes y = sin(x) · x² elementwise, and is not part of the E1 to E6 pipeline.

Inputs

Field	Type	Shape	Diff.	Description
x	Float64	(n)	yes	Input vector passed to the Julia kernel.

Outputs

Field	Type	Shape	Diff.	Description
y	Float64	(n)	yes	Kernel output sin(x) * x^2, computed in Julia.