Motion in Three Vectors

// internal/field/vec.go
package field

import "theworld/internal/vec"

// Vec2 is the vector type from package vec, named here so the laws in
// this package read without a prefix.
type Vec2 = vec.Vec2

// internal/field/body.go
// Package field is the moving half of the world: bodies, and the pushes
// that act on them. It knows what a tick is, in the only sense that
// matters here: a tick is one call to Step.
package field

// Body is one moving thing, held as three vectors: where it is, how
// fast it is going, and what this tick's pushes have added up to so
// far. Position is in world pixels, the unit the renderer already
// uses; velocity is world pixels per tick; acceleration is world
// pixels per tick per tick.
type Body struct {
	Pos, Vel Vec2

	acc Vec2 // this tick's pushes, and no other tick's
}

// Push adds one push to whatever this tick has already piled onto the
// body. Adding, never assigning: two callers pushing the same body in
// one tick both get their say.
func (b *Body) Push(a Vec2) { b.acc = b.acc.Add(a) }

// Acc reports what has been pushed onto the body so far this tick.
// Nothing outside this package can write it.
func (b *Body) Acc() Vec2 { return b.acc }

// Step is the update, and the order of these three lines is the law of
// the volume: the velocity takes on this tick's acceleration, the
// position takes on the velocity that resulted, and the acceleration
// goes back to zero because it belonged to the tick that just ended.
func (b *Body) Step() {
	b.Vel = b.Vel.Add(b.acc)
	b.Pos = b.Pos.Add(b.Vel)
	b.acc = Vec2{}
}

The first file is three lines and one idea. The vector type belongs to internal/vec, where the previous chapter built it, and this package gives it a second name with a type alias: field.Vec2 and vec.Vec2 are the same type, not two types that convert, so a vector made anywhere in the volume can be handed to anything else in it. The prefix is the only thing that changed.

Two of the three vectors on Body are public and one is not, and the difference is the chapter in miniature. Anything may read or set a body's position and velocity, because those describe the body. The accumulator can only be added to, by Push, and only emptied by Step, because it describes one tick: if code outside the package could assign to it, the clearing line would guarantee nothing. Push adds instead of assigning, so two callers pushing the same body in one tick both get their say and neither overwrites the other. Everything else this package grows will be code that computes a Vec2 and hands it to Push.

// cmd/bodies/main.go — the hand table, run

// gravity is the one push in this chapter: half a world pixel per tick
// per tick, straight down.
var gravity = field.Vec2{X: 0, Y: 0.5}

// start is the body the hand table follows.
func start() field.Body {
	return field.Body{Pos: field.Vec2{X: 24, Y: 8}, Vel: field.Vec2{X: 2, Y: 0}}
}

func table(ticks int) {
	b := start()
	fmt.Println("  tick           pushed       velocity after        position after")
	fmt.Printf("  %4d  %15s  %15s  %20s\n", 0, "-", vec(b.Vel), vec(b.Pos))
	for t := 1; t <= ticks; t++ {
		b.Push(gravity)
		pushed := b.Acc()
		b.Step()
		fmt.Printf("  %4d  %15s  %15s  %20s\n", t, vec(pushed), vec(b.Vel), vec(b.Pos))
	}
}

$ go run ./cmd/bodies -mode table
  tick           pushed       velocity after        position after
     0                -    2.000,  0.000        24.000,  8.000
     1    0.000,  0.500    2.000,  0.500        26.000,  8.500
     2    0.000,  0.500    2.000,  1.000        28.000,  9.500
     3    0.000,  0.500    2.000,  1.500        30.000, 11.000
     4    0.000,  0.500    2.000,  2.000        32.000, 13.000

Row for row, the table you worked by hand. That agreement is the only reason to run a first version on numbers small enough to check: the same code will soon be producing positions like 63.428194040359003, and there will be no way to tell a correct one from a plausible one by looking. The four rows above are the calibration.

// internal/field/body.go — kept so the two orders can be run against
// each other

// StepLagging is Step with the first two lines swapped: the position
// moves on the velocity the body arrived with, before this tick's
// acceleration reaches it.
func (b *Body) StepLagging() {
	b.Pos = b.Pos.Add(b.Vel)
	b.Vel = b.Vel.Add(b.acc)
	b.acc = Vec2{}
}

$ go run ./cmd/bodies -mode orders
        velocity first, then position    position first, then velocity
  tick        position         speed          position         speed
     1   26.000,  8.500   0.500   26.000,  8.000   0.500
     2   28.000,  9.500   1.000   28.000,  8.500   1.000
     3   30.000, 11.000   1.500   30.000,  9.500   1.500
     4   32.000, 13.000   2.000   32.000, 11.000   2.000

  the gap is 2.000 pixels after 4 ticks and opens by half a pixel per tick:
  the second body's position on tick n is the first body's position on tick n-1

Both bodies have the identical speed at every tick, and the right-hand one is always exactly one tick behind in where that speed has taken it: 8.5 on tick 2 against 8.5 on tick 1, 11.0 on tick 4 against 11.0 on tick 3. That is the arrangement's whole character with a push that never changes. Every tick it spends the velocity from before the push landed, so a body pushed on tick 1 does not respond until tick 2, and the delay is one tick forever.

// cmd/bodies/main.go

// middle is the point the tether pulls toward.
var middle = field.Vec2{X: ViewW / 2, Y: ViewH / 2}

// tether is a push computed from where the body is standing: toward the
// middle of the window, in proportion to how far out it has drifted.
func tether(b field.Body) field.Vec2 { return middle.Sub(b.Pos).Scale(0.02) }

$ go run ./cmd/bodies -mode held -ticks 400
        velocity first, then position    position first, then velocity
  tick     distance out       speed     distance out       speed
   100          4.208       6.804         11.380      18.200
   200         47.859       0.228        342.347       8.630
   300          5.814       6.797        244.772     127.761
   400         47.664       0.456       2364.121     123.100

  furthest out in 400 ticks: 48.120 and 2364.121, from a start of 48.000

One body on a tether, started 48 pixels out from the middle and let go. Under this volume's order it swings: out to 48, in through the middle at speed, back out to 48, and after 400 ticks the furthest it has ever been is 48.120, a tenth of a pixel more than it started with. Under the swapped order it is still swinging too, and the swings are getting wider: 342 pixels out at tick 200, 2,364 at tick 400, moving 123 pixels in a single tick. The window is 192 pixels across.

The mechanism is the delay, compounding. Coming inward, the tether should already be easing off as the body closes on the middle, but the swapped order computes the push from a position the body has left, so the pull it gets is the one for further out, slightly too strong. Going outward, the same lag makes the restraining pull slightly too weak. Each tick hands the body a little more speed than it should have, in the direction it was already going, and 400 ticks of a little more compounds into a body that has escaped. Doing the velocity first spends this tick's push inside this tick, and the small error it still makes changes sign as the body swings, so it cancels instead of piling up.

Neither arrangement is exact. Both are a stack of straight-line steps standing in for a smooth curve, and both are a little wrong at every tick. What separates them is what happens to the wrongness over a long run, and this world runs for months. The order in Step is the one that holds a swinging body inside a tenth of a pixel of where it started.

// cmd/bodies/main.go

// state is SHA-256 over the numbers themselves: every body's position
// and velocity, as the bits the machine holds them in. A frame hash
// answers whether two runs look the same; this answers whether they
// are the same.
func state(bodies []field.Body) string {
	h := sha256.New()
	var buf [8]byte
	for _, b := range bodies {
		for _, f := range []float64{b.Pos.X, b.Pos.Y, b.Vel.X, b.Vel.Y} {
			binary.BigEndian.PutUint64(buf[:], math.Float64bits(f))
			h.Write(buf[:])
		}
	}
	return hex.EncodeToString(h.Sum(nil))[:16]
}

// advance runs one swarm for one tick: the tether first, then whatever
// constant pushes this run applies, in the order it was given them.
func advance(bodies []field.Body, pushes []field.Vec2) {
	for i := range bodies {
		bodies[i].Push(tether(bodies[i]))
		for _, p := range pushes {
			bodies[i].Push(p)
		}
		bodies[i].Step()
	}
}

$ go run ./cmd/bodies -mode swarm
  seed 7, 24 bodies, 400 ticks, run twice

  tick     run 1 frame   run 2 frame     run 1 numbers     run 2 numbers
     1    ab3baf07877d  ab3baf07877d  853d2457ce69c2a6  853d2457ce69c2a6
    10    9bf47983fcab  9bf47983fcab  a2ccb47bd60aba50  a2ccb47bd60aba50
   100    7f4fc1c2519c  7f4fc1c2519c  e68c58bcebeb42be  e68c58bcebeb42be
   400    e26f340169c2  e26f340169c2  0fc375fcf682483c  0fc375fcf682483c

  all 400 frame hashes equal:   true
  all 400 number hashes equal:  true

  body 0 starts at y = 63.428194040359003
  and on the next call to swarm, y = 63.428194040359003

Twenty-four bodies, each placed and launched from the world's seeded stream, each carrying positions like 63.428194040359003 that no one could type by hand, all of them pulled by a tether that is recomputed from a fresh position every tick. Four hundred ticks, 9,600 body updates, tens of thousands of floating-point additions, and the two runs agree on every one of the 400 frame hashes and every one of the 400 number hashes. The second hash is the stronger claim: a frame hash only sees whole pixels, while the number hash is taken over the raw bits of every position and velocity, so it notices a disagreement in the seventeenth digit that no picture could show.

Nothing exotic is holding that up. The bodies live in a slice, so they are stepped in index order. The pushes are applied in the order the slice lists them. The seed feeds one stream, drawn from in one sequence. There is no map anywhere in the loop, and no law reads a clock. Same inputs, same operations, same order, same bits.

$ go run ./cmd/bodies -mode reorder
  the three pushes:
    gravity    0.000,  0.500
    breeze     0.120, -0.200
    swirl     -0.050,  0.100

  every order they can be added in, and the y that comes out:
    gr br sw   y = 0.40000000000000002  bits 3fd999999999999a
    gr sw br   y = 0.39999999999999997  bits 3fd9999999999999
    br gr sw   y = 0.40000000000000002  bits 3fd999999999999a
    br sw gr   y = 0.40000000000000002  bits 3fd999999999999a
    sw gr br   y = 0.39999999999999997  bits 3fd9999999999999
    sw br gr   y = 0.40000000000000002  bits 3fd999999999999a

  distinct answers from those six orders: 2
  distinct answers from a thousand walks over a map of the same three: 2

Three pushes that a leaf might plausibly feel at once, and the y component of their total depends on which of them you add first. Two of the six orders produce 3fd9999999999999 and the other four produce 3fd999999999999a: one step apart in the last bit, and neither of them exactly 0.4, which is not a number binary floating point can hold at all. Each addition rounds its result to the nearest value the format has, and rounding a different intermediate total rounds by a different amount.

The last line raises the alarm. Put the same three pushes in a map, walk the map a thousand times adding them up, and two different totals come back, because Go deliberately hands map entries out in an order it chooses fresh. That is chapter 5's roster reshuffling itself, arriving in a place you would not think to look for it: not deciding who moves first, just deciding which of two sums a body gets. Chapter 10 drew the boundary and named what may cross it, seed and tick count, and listed map order among the things that may not. A push accumulator that iterates a map has walked that fact straight back across the line.

$ go run ./cmd/bodies -mode clash
  seed 7, 24 bodies, the same three pushes, added in two orders

  tick   order A frame  order B frame     order A numbers   order B numbers
     1    6b31eddcfb8b   6b31eddcfb8b  1aef2cd9d81a0893  0950cb717fcb178c
     2    d4c878025213   d4c878025213  12b667346a7893a7  7d5b2f0490dfd81c
    10    351b02233d2c   351b02233d2c  70bfad10d10fab8c  db4fb5b822860c02
   400    e26f340169c2   e26f340169c2  af3752fb4bd4389e  2e714bcd7f54e086

  first tick whose numbers differ: 1
  first tick whose picture differs: never, in 400 ticks

  tick      widest gap between the two runs, in world pixels
      1      1.421e-14
     10      1.421e-14
    100      9.948e-14
   1000      3.587e-13
  10000      3.111e-12

One seed, one swarm, the same three pushes, applied gravity-breeze-swirl in the left column and swirl-breeze-gravity in the right. The number hashes disagree on tick 1 and never agree again: the two runs are different histories from their first instant. The frame hashes are identical for all 400 ticks, and would stay identical for a great many more, because the disagreement between the two runs starts at 1.4 × 10⁻¹⁴ of a pixel. That figure is not arbitrary either. It is one step in the last bit of a number near 64, which is where these bodies are, and a pixel is 1.0.

So a reordered accumulator gives you a run that is wrong from tick 1 and looks perfect for as long as anyone is likely to watch. The gap does grow, as the two runs' roundings wander apart: 3.1 × 10⁻¹² after ten thousand ticks, which is still a millionth of a millionth of a pixel. Waiting for it to become visible is not a plan.

What makes a difference that small matter is a comparison. This world is full of them: is this body inside the radius, has the leaf crossed into water, which of the two neighbours is nearer, did the creature reach the food this tick or next. A comparison takes two numbers that differ in their last bit and returns one bit that is completely different, and from there the two runs are not describing the same afternoon. The rule that keeps it from happening is the same one volume 1 arrived at by another road, stated in its general form: every accumulation in this world happens in an order the code chose. Bodies step in slice order, pushes are applied in list order, neighbours are visited in an order somebody sorted. Any total whose order is decided by the language, the runtime or the hardware is a total the seed does not control.