Two Numbers Under Every Cell

// internal/terra/terra.go

// Ground is what one cell hands a plant in a single tick. The three
// numbers are allowances rather than stores: whatever is not taken this
// tick is not saved for the next one.
type Ground struct {
	Light    float64 // energy units of daylight landing on the cell
	Water    float64 // water units the soil here can give up
	Nutrient float64 // nutrient units the soil here can give up
}

// Plant is one plant's whole physiology. Mass is the only field a tick
// changes; the others are what kind of plant this is.
type Plant struct {
	Mass   float64 // grams of tissue standing right now
	Catch  float64 // the share of its cell's light the crown intercepts
	Thirst float64 // water units spent per energy unit fixed
	Hunger float64 // nutrient units spent per energy unit fixed
	Upkeep float64 // energy units one gram of tissue costs per tick
	Root   float64 // how far the roots reach, in cells
}

// Ledger is one tick's numbers, in the order they are worked out.
type Ledger struct {
	Caught float64 // energy the crown fixed
	Drawn  float64 // water the roots pulled to pay for it
	Ate    float64 // nutrient the roots pulled to pay for it
	Paid   float64 // energy the standing tissue charged
	Grown  float64 // grams the leftover bought; negative when short
	Limit  string  // the resource that decided Caught
}

Five fields are new and everything else is untouched. Ground grows a nutrient allowance beside its water. Plant grows a Hunger, the nutrient twin of the thirst it already had, and a Root, which is the first number on a plant that is about distance instead of physiology: how far from its own cell it can take anything. The ledger gains a line for the nutrient pulled and a name for whatever decided the tick. Nutrient earns its place beside water because the two run out at different speeds, and a resource that never becomes the scarce one might as well be a constant.

// internal/terra/bed.go

// Cell is what one cell of ground is holding. Where a Ground is an
// allowance for a single tick, both of these are stores: what a root
// leaves behind is still there next tick, and what it takes is gone
// until something puts it back.
type Cell struct {
	Moisture float64
	Nutrient float64
}

// Bed is the store underneath the allowances: two numbers for every
// cell of a terrain grid, kept in the same flat row-order slice the
// terrain itself lives in.
type Bed struct {
	W, H  int
	kind  *sim.Grid
	cells []Cell
}

// NewBed lays soil over a terrain grid. Soil cells start full, open
// water holds all the moisture there is and no nutrient, and rock holds
// nothing at all: a root in rock gets nothing because there is nothing
// there.
func NewBed(g *sim.Grid, full Cell) *Bed {
	b := &Bed{W: g.W, H: g.H, kind: g, cells: make([]Cell, g.W*g.H)}
	for y := 0; y < g.H; y++ {
		for x := 0; x < g.W; x++ {
			c := sim.Coord{X: x, Y: y}
			t, err := g.At(c)
			if err != nil {
				continue
			}
			switch t {
			case sim.Soil:
				b.cells[b.index(c)] = full
			case sim.Water:
				b.cells[b.index(c)] = Cell{Moisture: full.Moisture}
			}
		}
	}
	return b
}

The bed is a second grid laid over the first, in the same flat row-order slice, so the arithmetic that turns a coordinate into a slot is the one already learned. What it does not do is copy the terrain. It keeps a pointer to the grid and asks whenever it needs to know what kind of ground a cell is, so there is one authority on that and no chance of two copies disagreeing after something edits one of them.

Cell and Ground hold nearly the same nouns and mean opposite things, so the comment on each of them says which it is. A Ground is what arrives this tick and expires at the end of it. A Cell is a balance that survives every tick until something spends it. Nearly all the mistakes available in this chapter come from treating one as the other.

// internal/terra/bed.go

// Rootable reports whether anything can put a root into this cell. Soil
// can be rooted in; open water and bare rock cannot.
func (b *Bed) Rootable(c sim.Coord) bool {
	t, err := b.kind.At(c)
	return err == nil && t == sim.Soil
}

// Reach is the geometry alone: every cell of the grid whose centre lies
// within r cells of c, walked in row order so two runs visit them in
// the same sequence. Coordinates off the grid are dropped here, which
// is the only place that check has to happen.
func (b *Bed) Reach(c sim.Coord, r float64) []sim.Coord {
	n := int(r)
	var out []sim.Coord
	for dy := -n; dy <= n; dy++ {
		for dx := -n; dx <= n; dx++ {
			if float64(dx*dx+dy*dy) > r*r {
				continue
			}
			p := c.Offset(dx, dy)
			if b.In(p) {
				out = append(out, p)
			}
		}
	}
	return out
}

// Roots is the reach filtered down to the cells that answer: the disc
// is geometry, and the bed decides which of it is ground a root can
// live in.
func (b *Bed) Roots(c sim.Coord, r float64) []sim.Coord {
	var out []sim.Coord
	for _, p := range b.Reach(c, r) {
		if b.Rootable(p) {
			out = append(out, p)
		}
	}
	return out
}

$ go run ./cmd/bed -mode disc
bed: a root of radius r, and a draw of 1.500 split evenly across it
     r   cells    pi*r*r   cells/pi*r*r   per cell   ticks to dry
   1.0       5     3.142          1.592     0.3000              4.2
   1.5       9     7.069          1.273     0.1667              7.5
   2.0      13    12.566          1.035     0.1154             10.8
   2.5      21    19.635          1.070     0.0714             17.5
   3.0      29    28.274          1.026     0.0517             24.2
   4.0      49    50.265          0.975     0.0306             40.8

Two methods and not one, because two different questions are being asked. Reach is geometry: which cells are near enough. Roots is the ground's answer: which of those hold anything a root can take. Keeping them apart makes the number of cells a plant actually feeds from a fact about where it is standing, so a plant against the rim with a third of its disc in rock has a third less soil to draw on and not one line of special-casing anywhere.

Reach is also where the off-grid check happens, once. A plant near an edge has part of its disc outside the world, and each of those coordinates would index past the end of a slice. Dropping them here means Roots, Draw and everything above them are handed only coordinates that name real cells. The last column divides a full cell by what one cell gives up and says how many ticks that lasts with nothing coming back: a ranking, not a forecast, and it says that quadrupling the cells quadruples the patience of the ground.

// internal/terra/bed.go

// Offer is the Ground under a plant this tick: the light landing on its
// own cell, and everything its roots could pull out of every cell they
// reach. It changes nothing, so two plants asking in the same tick both
// get told the truth as it stands when they ask.
func (b *Bed) Offer(at sim.Coord, r, light float64) Ground {
	g := Ground{Light: light}
	for _, c := range b.Roots(at, r) {
		s := b.cells[b.index(c)]
		g.Water += s.Moisture
		g.Nutrient += s.Nutrient
	}
	return g
}

// Draw pulls want out of the ground under a plant and reports what it
// got. Every root cell gives up a share in proportion to what it is
// holding, so a nearly empty cell is asked for nearly nothing and no
// cell is ever asked for more than it has.
func (b *Bed) Draw(at sim.Coord, r float64, want Cell) Cell {
	cells := b.Roots(at, r)
	var have Cell
	for _, c := range cells {
		s := b.cells[b.index(c)]
		have.Moisture += s.Moisture
		have.Nutrient += s.Nutrient
	}
	var got Cell
	for _, c := range cells {
		s := &b.cells[b.index(c)]
		got.Moisture += bite(&s.Moisture, want.Moisture, have.Moisture)
		got.Nutrient += bite(&s.Nutrient, want.Nutrient, have.Nutrient)
	}
	return got
}

// bite takes one cell's share of a draw: what the cell is holding
// divided by what the whole root can reach, multiplied by what was
// asked for, and never more than the cell has.
func bite(store *float64, want, have float64) float64 {
	if want <= 0 || have <= 0 || *store <= 0 {
		return 0
	}
	take := want * (*store / have)
	if take > *store {
		take = *store
	}
	*store -= take
	return take
}

Offer adds up what the roots can reach and changes nothing, so it can be called as often as anyone likes and two plants asking in the same tick are both told the truth as it stands when they ask. Draw is the half that moves numbers, and it takes from each cell in proportion to what that cell is holding. A cell with half the water gives up half the share; a cell with none gives up none. That rule is what makes the clamp inside bite almost never fire, because a proportional split cannot overdraw a cell unless the total was short to begin with.

An even split is the obvious alternative and it is the one that breaks, further down this page.

// internal/terra/bed.go

// Regen trickles a fixed amount of both resources back into every cell
// a root could reach, never past the cap. This is a placeholder rate
// and nothing more: the amount is the same in the driest corner of the
// valley as it is on the shore of the pond.
func (b *Bed) Regen(rate, cap Cell) {
	for y := 0; y < b.H; y++ {
		for x := 0; x < b.W; x++ {
			c := sim.Coord{X: x, Y: y}
			if !b.Rootable(c) {
				continue
			}
			s := &b.cells[b.index(c)]
			s.Moisture = math.Min(cap.Moisture, s.Moisture+rate.Moisture)
			s.Nutrient = math.Min(cap.Nutrient, s.Nutrient+rate.Nutrient)
		}
	}
}

$ go run ./cmd/bed -mode cell -ticks 10
bed: one cell holding 1.250, one root asking 0.250 a tick,
     the trickle putting back 0.050
  tick   holding    asked     got     left   after trickle
     1     1.250    0.250   0.250    1.000           1.050
     2     1.050    0.250   0.250    0.800           0.850
     3     0.850    0.250   0.250    0.600           0.650
     4     0.650    0.250   0.250    0.400           0.450
     5     0.450    0.250   0.250    0.200           0.250
     6     0.250    0.250   0.250    0.000           0.050
     7     0.050    0.250   0.050    0.000           0.050
     8     0.050    0.250   0.050    0.000           0.050
     9     0.050    0.250   0.050    0.000           0.050
    10     0.050    0.250   0.050    0.000           0.050

Six full draws, one short draw of 0.050 at tick 7, and the refill rate from then on. That is the pencil arithmetic from the top of the chapter, printed by the code, and every column matches to the last digit.

Regen is the weakest thing on this page and its comment says so. It adds the same amount to every soil cell on the grid, capped at full, whether the cell is on the shore of the pond or in the driest corner under the rim. Ground does not work like that: water arrives somewhere in particular, and where it goes after that is decided by the heights. The constant is a placeholder holding the position until moisture is allowed to move, and it is labelled as one where somebody editing the file will see it.

// internal/terra/terra.go

// Limit is the resource holding this plant back on this ground, and the
// energy it can pay for. Light pays for whatever the crown intercepts;
// water and nutrient each pay for as much energy as the plant's rate of
// spending them stretches to. Growth follows the smallest of the three
// and never their average.
func (p Plant) Limit(g Ground) (float64, string) {
	e, name := g.Light*p.Catch, "light"
	if w := g.Water / p.Thirst; w < e {
		e, name = w, "water"
	}
	if n := g.Nutrient / p.Hunger; n < e {
		e, name = n, "nutrient"
	}
	return e, name
}

// Fix is the energy this plant can turn over in one tick: its share of
// the light landing on the cell, or as much of that as the ground's
// water or nutrient will pay for, whichever runs out first.
func (p Plant) Fix(g Ground) float64 { e, _ := p.Limit(g); return e }

// Tick charges one plant one tick against one cell and hands back the
// numbers that moved. The plant's mass is the only thing it changes,
// and it changes it exactly once.
func (p *Plant) Tick(g Ground) Ledger {
	l := Ledger{}
	l.Caught, l.Limit = p.Limit(g)
	l.Drawn = l.Caught * p.Thirst
	l.Ate = l.Caught * p.Hunger
	l.Paid = p.Mass * p.Upkeep
	l.Grown = l.Caught - l.Paid
	p.Mass += l.Grown
	return l
}

$ go run ./cmd/bed -mode law
bed: three resources, each priced in the energy it can pay for
                            light    water    nutrient      min      mean
  full soil, full sun        2.500   12.500      24.000    2.500    13.000  <- light
  most of the water gone     2.500    1.667      24.000    1.667     9.389  <- water
  nutrients nearly out       2.500   12.500       0.667    0.667     5.222  <- nutrient
  deep shade, wet ground     0.250   12.500      24.000    0.250    12.250  <- light
  bone-dry ground            2.500    0.000      24.000    0.000     8.833  <- water

The previous chapter wrote this comparison as an if between two resources, which is what two resources deserve. Three of them turn it into a running minimum, and Limit carries out a name along with the number because that name costs nothing. The comparison that found the smallest already knows which one it was, and a growth figure alone says how fast while the name says what to fix.

Read the mean column against the min column and the strength of the objection is in the gap. Averaging never produces a number a resource can actually deliver; it produces the average of a bottleneck and two surpluses, which is a quantity nothing in the world corresponds to.

// cmd/bed/main.go

// full is what an untouched soil cell holds, and the cap the trickle
// refills towards.
var full = terra.Cell{Moisture: 1.25, Nutrient: 0.60}

// regen is the placeholder: the same small amount put back into every
// soil cell every tick, wherever the cell is.
var regen = terra.Cell{Moisture: 0.050, Nutrient: 0.004}

// even switches the draw from proportional to an equal split, which is
// this chapter's worked failure.
var even bool

// seedling is the plant every run in this chapter starts with: the
// previous chapter's physiology, plus a nutrient rate and a root that
// reaches beyond the cell it stands on.
func seedling() terra.Plant {
	return terra.Plant{
		Mass: 1, Catch: 0.25, Thirst: 0.6, Hunger: 0.15, Upkeep: 0.02, Root: 1.5,
	}
}

// step is one plant's whole tick against the ground it stands on: ask
// the bed what is there, run the books against that offer, and charge
// the bed for exactly what the books spent.
func step(b *terra.Bed, p *terra.Plant, at sim.Coord) terra.Ledger {
	g := b.Offer(at, p.Root, Light)
	l := p.Tick(g)
	want := terra.Cell{Moisture: l.Drawn, Nutrient: l.Ate}
	if even {
		b.DrawEven(at, p.Root, want)
	} else {
		b.Draw(at, p.Root, want)
	}
	return l
}

$ go run ./cmd/bed -mode grow -ticks 40
bed: a 12x8 valley from seed 5, one seedling at 4,1, root radius 1.5
     the disc covers 9 cells and 6 of them are soil
  tick    caught   drawn     ate    paid    grown      mass  ceiling  limit     under the plant
     1     2.500   1.500   0.375   0.020    2.480     3.480   125.00  light      1.050  0.541
     2     2.500   1.500   0.375   0.070    2.430     5.910   125.00  light      0.850  0.483
     3     2.500   1.500   0.375   0.118    2.382     8.292   125.00  light      0.650  0.424
     4     2.500   1.500   0.375   0.166    2.334    10.626   125.00  light      0.450  0.366
     5     2.500   1.500   0.375   0.213    2.287    12.914   125.00  light      0.250  0.307
     6     2.500   1.500   0.375   0.258    2.242    15.156   125.00  light      0.050  0.249
     7     0.500   0.300   0.075   0.303    0.197    15.352    25.00  water      0.050  0.240
     8     0.500   0.300   0.075   0.307    0.193    15.545    25.00  water      0.050  0.232
     9     0.500   0.300   0.075   0.311    0.189    15.734    25.00  water      0.050  0.223
    10     0.500   0.300   0.075   0.315    0.185    15.920    25.00  water      0.050  0.215
    15     0.500   0.300   0.075   0.332    0.168    16.792    25.00  water      0.050  0.172
    20     0.500   0.300   0.075   0.349    0.151    17.581    25.00  water      0.050  0.130
    25     0.500   0.300   0.075   0.363    0.137    18.294    25.00  water      0.050  0.087
    30     0.500   0.300   0.075   0.376    0.124    18.938    25.00  water      0.050  0.045
    35     0.440   0.264   0.066   0.388    0.052    19.460    22.00  nutrient   0.056  0.004
    40     0.160   0.096   0.024   0.371   -0.211    18.359     8.00  nutrient   0.226  0.004
     the bed holds 68.856 of moisture and 22.824 of nutrient, numbers 0b3d4e61f1836901

step is three lines and each is a different kind of thing: ask the ground, run the books, charge the ground. The books are the previous chapter's, unchanged in what they do. What is new is that their input is now computed from state that the same plant spent down last tick.

The column under the plant is the pencil arithmetic again: 1.050, 0.850, 0.650, 0.450, 0.250, and 0.050 at tick 6, which is the one-cell walk from the top of the chapter appearing inside a six-cell root without being told to. Six cells hold 7.500 of water, the refill puts back 0.300 a tick, the plant draws 1.500, so the store loses 1.200 a tick and covers six ticks and no more.

At tick 7 the limit column changes to water and everything falls at once. Caught goes from 2.500 to 0.500, the whole income the refill can support, and the ceiling with it: from 125 grams to 25. The plant is at 15.352 grams and still under the new ceiling, so it keeps growing, slowly. At tick 35 the nutrient runs short as well and takes the limit over, and by tick 40 the ceiling is down to 8 grams with the plant at more than twice that. Growth has turned negative and mass is coming off: 19.460 at tick 35, 18.359 at tick 40. Nothing in the code makes a plant shrink. It falls out of an income that collapsed while the upkeep bill did not.

$ go run ./cmd/bed -mode grow -ticks 40 -maps | tail -10
     the bed holds 68.856 of moisture and 22.824 of nutrient, numbers 0b3d4e61f1836901
     moisture, ' ' empty . : o O @ full
     ############
     #@@...@@@@@#
     #@@...@@@@@#
     #@~~~~~@@@@#
     #@~~~~~~@@@#
     #@@@~~~~@@@#
     #@@@~@@@@@@#
     ############

One plant, forty ticks, and a rectangle of spent ground where the rest of the valley is untouched. Six cells, three across and two down, which is a disc of radius 1.5 with its top row cut off by the rim. That patch is the plant's biography written into the world: anything arriving later can read it, because it is state on the grid and not a private field inside the plant.