Documentation — Zymplectic

Setup & system definition

main()

Declare void main(); it runs on initialization. Set Z.* options and register callbacks and system connectors here.

Z.H(H,dH,a) Z.H(H,dH,a,b): Connect a Hamiltonian and its gradient to object a, optionally paired with b. Use for nonseparable systems.
Z.T(T,dT,a) Z.T(T,dT,a,b): Connect kinetic energy and its momentum gradient for a separable system.
Z.V(U,dU,c) Z.V(U,dU,c,d): Connect potential energy and its coordinate gradient to object c, optionally paired with d.

Energy callbacks use double H(Arg); gradients use void dH(Arg) (likewise for T and U). Object indices are zero-based. Repeat connectors to assemble a system; omit energy evaluation with 0. Use either Z.H or the Z.T/Z.V pair.

Callback settings

main()

Register optional void Name() callbacks in main() by assigning their names without parentheses.

Z.OnDraw = DrawFunction;: Every graphical frame. Replaces native drawing with your own graphics; runs asynchronously with simulation iterations.
Z.OnDrawAdd = DrawFunction;: Every graphical frame. Adds your graphics to native track, trail and surface drawing.
Z.OnIter = IterFunction;: Each iteration, including the start. Use for sampling trajectories and updating the track canvas.
Z.OnReset = ResetFunction;: When draw.reset restarts the simulation.
Z.OnStart = StartFunction;: The first event when starting a simulation.
Z.OnInput = InputFunction;: Keyboard presses and mouse click/release events. Read the input variables here.

Drawing

OnDraw / OnDrawAdd

Set appearance, then draw primitives, shapes or text in OnDraw or OnDrawAdd.

Appearance

draw.rgb(v) draw.rgb(v,a) draw.rgb(r,g,b) draw.rgb(r,g,b,a): Set color from v using Z.color3, or explicit RGB; a is alpha. Color values range from 0 to 1.
draw.depth(i): Disable/enable object depth in 3D with 0/1. Useful for transparency or Z-fighting.
draw.light(x,y,z,i): Set light position/direction. i = 0: directional; i = 1: point source.
draw.shine(a,b): Set specular intensity a and shininess b.
draw.pointsize(i): Set point size.
draw.linesize(i): Set line size.
draw.surfopt(a,b,c): Set surface minimum a, maximum b and colormap c. Use c <= 0 for the selected colormap.

Array primitives

draw.lines(X,Y,n) draw.lines(X,Y,Z,n): Separate line segments: n/2 lines, in 2D or 3D.
draw.points(X,Y,n) draw.points(X,Y,Z,n): Draw n points, in 2D or 3D.
draw.line_strip(X,Y,n) draw.line_strip(X,Y,Z,n): Connect consecutive points: n−1 line segments.
draw.quads(X,Y,n) draw.quads(X,Y,Z,n): Draw n/4 filled quadrilaterals.
draw.polygon(X,Y,n) draw.polygon(X,Y,Z,n): Filled polygon. Uses advanced tessellation in 2D and an OpenGL primitive in 3D.
draw.triangles(X,Y,n) draw.triangles(X,Y,Z,n): Draw n/3 filled triangles.

Shapes & surfaces

draw.rod(x1,y1,z1,x2,y2,z2,r) draw.rod(x1,y1,z1,x2,y2,z2,r,a,n): Rod between two endpoints, radius r. Extended form sets rotation a and edge count n; n > 16 uses smooth normals.
draw.rods(X,Y,Z,r,n): Connected rods along n points. Identical first/last coordinates close the loop. Negative r uses joint normals for smooth lighting.
draw.hrod(x1,y1,z1,x2,y2,z2,r1,r2) draw.hrod(x1,y1,z1,x2,y2,z2,r1,r2,a,n): Hollow rod between two endpoints, with radii r1, r2. Extended form sets rotation a and edge count n.
draw.cone(x1,y1,z1,x2,y2,z2,r1,r2) draw.cone(x1,y1,z1,x2,y2,z2,r1,r2,a,n): Cone between two endpoints, with radii r1, r2. Extended form sets rotation a and edge count n.
draw.box(x,y,z,lx,ly,lz,a,b,i): Cuboid centered at (x,y,z), dimensions (lx,ly,lz). a: tessellations; b: rotation about axis i.
draw.sphere(x,y,z,r): Sphere centered at (x,y,z), radius r.
draw.spheres(X,Y,Z,r,n): Draw n low-polygon spheres with radius r.
draw.hoop(x,y,z,a,b,r1,r2,w): Hoop centered at (x,y,z), angles (a,b) = (phi,theta), inner radius r1, outer radius r1+r2, width w.
draw.surf(Y,x1,x2,z1,z2,nx,nz): Heightmap Y[nx][nz] over the xz-plane, bounded by x1, x2, z1, z2.
draw.spring(x1,y1,z1,x2,y2,z2,r) draw.spring(x1,y1,z1,x2,y2,z2,r,o): Spring between two endpoints, radius r; optional spiral offset o. Negative r uses its magnitude with an alternate orientation mode.

Text

draw.text(x,y,S) draw.text(x,y,z,S): Draw text at world coordinates, in 2D or 3D.
draw.textscreen(x,y,S): Text at screen pixel coordinates, centered on (0,0). Default 768 × 768 resolution spans −384 to 384.
draw.font(n): Select GLUT font n = 0…6.

Canvas & trails

Track & trail data

OnIter

draw.track(x,y): Add 1 to the canvas pixel value at (x,y).
draw.trackb(x,y): Like draw.track, with a 2 × 2 brush.
draw.track_set(x,y,n): Set the canvas pixel at (x,y) to n.
draw.track_get(x,y): Return the canvas pixel value; returns −1 outside the canvas.
draw.trail(x,y) draw.trail(x,y,z) draw.trail(x,y,n) draw.trail(x,y,z,n): Add a 2D/3D trail point, retained over Z.tspan. Two arguments imply z = 0. An integer third argument selects a 2D trail; a double is the 3D z coordinate. Configure multiple trails with Z.trail in main().

Trail appearance

OnDraw / OnDrawAdd

draw.trailrgb(r,g,b,i): Set trail i color (RGB 0–1); negative values use the last draw.rgb color. Trail index i must be less than Z.trail.
draw.trailsize(i): Set trail size.

View & control

OnDraw / OnDrawAdd

draw.cam(x,y) draw.cam(x1,y1,z1,x2,y2,z2): Center the 2D camera at (x,y); in 3D, place it at (x1,y1,z1), looking at (x2,y2,z2).
draw.wrap(x,y,a,b,r,o): With 3D Z.wrap enabled, position a cylindrical canvas at (x,y), rotation o, radius r, z-span a…b. r, a, b scale with the world box; 1, −1, 1 spans it.
draw.reset(i): Restart the simulation and trigger OnReset. i = 0 keeps the canvas; i = 1 clears the track canvas.
draw.screenshot(S)All events: Request a screenshot named by S. Capture occurs in the graphics thread; slow the simulation when timing matters. The input guide demonstrates an OnInput hotkey.

Reserved variables

q1, q2, … and p1, p2, … are only available in derivative and Hamiltonian functions. Use obj_q and obj_p only in events, where those shortcuts are unavailable.

Simulation state

All events · read-only

_t: Simulation time. Also available in energy/derivative functions for time-dependent systems.
obj_q[a][b] obj_p[a][b]: Canonical coordinates and momenta. a is the object index; b is the dimension index. Both are zero-based.
c_: Composition coefficient used in the simulation of constrained systems. Experimental.

Drawing state

OnDraw / OnDrawAdd · read-only

ScreenX1, ScreenX2 ScreenY1, ScreenY2 ScreenZ1, ScreenZ2 ScreenX, ScreenY: Current border coordinates on each axis. ScreenX and ScreenY give graphics window resolution.

Input state

OnInput

KeyStroke, KeyState MousePixX, MousePixY MouseX, MouseY, MouseZ: Integer key code/state and mouse pixel coordinates; double mouse world coordinates. In 3D, world coordinates are projected onto the world box.

Simulation settings

main()

Set initial GUI values with Z.name = value; in main(). Hover the matching GUI control for its value range and behavior.

Z.benchmark, Z.speed, Z.tspan, Z.tstep, Z.time_scale, Z.amp, Z.t1, Z.t2: Simulation & timing. Z.speed sets iterations per second; Z.tstep sets the time step. With “periodic _t”, Z.t1/Z.t2 bound _t.
Z.dot_size, Z.axes, Z.inset, Z.x, Z.y, Z.z, Z.graph3D: Display & axes. Configure the GUI’s display options and 3D mode.
Z.xres, Z.yres, Z.fps, Z.buffer: Graphics output. The guide specifies a maximum pixel count of xres × yres = 3840 × 2160.
Z.track, Z.trail, Z.wrap, Z.object, Z.surf: Native graphics modes. Configure track, trail, wrapped canvas, object and surface drawing.
Z.q_size, Z.p_size, Z.clear_gradient: State & gradient options. See the matching GUI tooltips for details.
Z.color1, Z.color2, Z.color3: Trail, track and surface colors, respectively. Z.color3 also applies to draw.surf and draw.rgb(v).
Z.x1, Z.x2, Z.y1, Z.y2, Z.z1, Z.z2, Z.xangle, Z.yangle: Camera bounds & angles.
Z.xmintrack, Z.xmaxtrack, Z.ymintrack, Z.ymaxtrack, Z.surfmin, Z.surfmax: Track canvas bounds & surface value range.