sots-engine/docs/N-output-term.md

N — the population → base-output term

The formula that a colony's whole economy hangs off, and the one src/app names as its largest unmodelled input. It is now read from the instruction stream and compared against the running game.

What it is

Output points are linear in population:

outputPerHead = populationTypeOutputModifier x 1.8 / 500000

1.8 and 500000 are literals in the executable, and so are the imperial (1.0) and civilian (0.33f) type modifiers — the three-row population-type table is built in code, not loaded from the data files. Only the slave row's modifier comes from the data. An imperial population with no station therefore contributes exactly 3.6e-6 output points per head.

A system's total output is a sum of three independent terms, not one multiplicative chain:

base = overHarvestDemand x speciesResourceOutputFactor
     + (transitResources + availableResources) x stripMineFraction x 0.9
     + imperialOutput + civilianOutput + slaveOutput

total = addictionModifier x base
      x playerOutMod x systemOutMod x setupOutputMult x rebOutMod x scOutMod

The station bonus multiplies only the imperial term; the morale modifier multiplies only the civilian term. The previous model in this module applied both to the whole thing, which is why OutputModifiers no longer carries morale or stations — they belong to GroupOutputInputs, one population row at a time.

API

src/game/sim/colony.h:

function	what
PopTypeOf(group, tuning)	the population-type row: output/income modifiers and the row's population cap (imperial 50,000,000, civilian 20,000,000)
GroupOutput(GroupOutputInputs, tuning)	one (group, species) row's contribution — the per-capita law
MoraleOutputMultiplier(morale, tuning)	the civilian morale factor, with both of the original's guards
StripMineFraction(StripMineInputs)	resource extraction efficiency
OverHarvestDemand(OverHarvestInputs)	the strip-mining resource demand, which is also a summand of output
SystemBaseOutput(BaseOutputInputs, tuning)	the three terms summed in the original's association
TotalSystemOutputRaw / TotalSystemOutput	the multiplier tail, unrounded and rounded half-to-even

Verified against the running game

Two hooks in src/shim/hooks/system_output.{h,cpp}, both compare mode, config src/shim/shim.cfg.output:

• Game::ServerSystem::GroupOutput — the per-capita law itself. 13,105 calls, 0 divergences across two species and two workloads.
• Game::ServerSystem::ComputeTotalOutput — the whole sum and multiplier tail. 11,252 calls, 1 divergence, and that one is a single ulp on one system, in a value the caller rounds to an integer before using — so it cannot move any number the game stores. It is recorded, not fixed.

Both functions were checked for stores to the game state before being chosen as compare targets, and each declares a Guard region over the whole system object: 0 undeclared writes in 24,357 calls turns that check from a claim into a measurement. The neighbouring ComputeOutputFromRates is deliberately not hooked — it repairs damaged ships in orbit.

Coverage — read this before quoting the zero

24,357 calls is 13 distinct system states. Unexercised, and therefore hypotheses:

• the over-harvest branch (SRoh is 0 on every call in the corpus), including its max(v, 1) floor;
• the station factor (no system in the corpus has a station);
• the slave term (no system in the corpus holds slaves);
• both morale branches (every colony sits at 75, strictly between the two thresholds);
• the addiction multiplier and the civilian capacity surplus.

sim::Narrow

A 32-bit x87 build may leave an intermediate in a register at the register's own precision; the original's x87 runs with its precision-control field at 53 bits and rounds every multiply to double. The first live run made that visible as a one-ulp low result on every civilian row — 4,957 divergences that were all the same defect, and none of them the model's. sim::Narrow forces the round the original performs anyway, and is a no-op on any SSE2 target.

Correction shipped alongside

ComputeBankruptcyLimits used the decimal -0.15 as the elimination-limit divisor. The image holds -0.15000000596046448, a widened float literal. The two disagree for every maximum income divisible by 3 — from maxIncome = 3 upward — and for essentially every empire above about 3,000,000, which is six of the twenty-five bankruptcy records recoverable from the save corpus. Fixed, with kBankruptcyInterestDivisor named in the header and a test at the value where it first bites.

What this does and does not unblock

It does not unblock P01. ComputeBudget's missing input is a system's money, which runs this verified total through a second chain with its own population law (incomeModifier / 14000, no 1.8) and its own multipliers. Checked against the bankruptcy-limit oracle over the whole save corpus, that composition reproduces 6 of 25 player-records exactly — every record whose owner is the human player or an independent colony — and the single-system misses are short by a clean factor of 1.1, the AI trade/income difficulty multiplier, which is not on the wire.

So the blocker has moved from the output term to the income tail. src/app is unchanged: 5 leaves closed, 0 regressed, on both save pairs.