# agri.gross-margin

The gross margin of a farm enterprise (a crop, a flock, a herd): its output
less the variable costs that rise and fall with it, in total and per hectare
or per head, with the margin as a share of output. Fixed costs (labour,
machinery depreciation, rent, overheads) are deliberately not in it; that is
what makes gross margins comparable between farms and against the published
benchmarks.

`grossMargin(outputs, variableCosts, "hectare", 100, "GBP")` for 100 ha of
wheat with £238,000 output and £52,000 variable costs is a £186,000 margin,
£1,860 per hectare, 78.15% of output.

## How it is worked out

1. Outputs and variable costs are totalled exactly in minor units
   (`money.sum`); every line must be in `currency`. Lines may be negative (a
   clawback, a credit note).
2. The margin is output less variable costs, and may be negative.
3. Each per-unit figure is its own total divided once by the hectares or
   head, half up (away from zero for negatives, `math.round-div`). So the
   per-head margin is not always per-head output less per-head costs: with 3
   head, 10000 output and 5000 costs, that shortcut gives 3333 - 1667 = 1666,
   where 5000 / 3 is 1667.
4. `marginBasisPoints` is the margin over output, half up, and null when
   output is zero.

Hectares are taken to 0.0001 ha (1 m²); head is a whole number.

## What it does not do

It does not decide what is a variable cost, value stock or home-grown feed,
or split shared costs between enterprises: the caller brings the lines. It is
arithmetic, not an assessment of the enterprise.

## Limits

More than 0 and at most 10,000,000 hectares or head; each total within
±900,000,000,000 minor units, which keeps every intermediate below 2^53 so
that TypeScript stays exact.

## Source

The definition (enterprise output less variable costs, before fixed costs)
is the standard one in UK farm management, e.g. the John Nix Farm Management
Pocketbook and AHDB's Farmbench costings.