User guide

1Five minutes to a first answer

1. Open Run the model. It starts on the Waikato dairy pasture example and has already run: the answer is on the Results tab and the headline is in the brown bar on the left, which stays there while you work.
2. On the Site & land use tab, click your block on the map. The soil order, the carbon percentage with its mapped range, the pH, the drainage, the depth and the seasonal temperatures are read at that point and go straight into the Soil and Climate tabs, and the region is found from it.
3. Beside the map, the Land use list now holds the land uses practised in that region, taken from KiwiFert’s rotations: those KiwiFert names your region for carry a ★, the rest are practised nationwide. Choose yours. The run is built in one step — the soil and climate from the point, the rotation, grazing animal and fertiliser and lime programme from KiwiFert calculated for that soil — and the model re-runs.
4. Open the Soil tab and check what arrived. If you have a laboratory analysis, type your own carbon percentage and bulk density into the properties grid — those two numbers change the answer more than anything else you can enter, and a measurement from your own block always beats a national raster.
5. Open the Plants & grazing and Fertiliser & lime tabs and check the rotation and the programme. The plant names are matched to this model’s plants by keyword, and every number can be typed over.
6. Read the scoreboard at the top of the Results tab, then read the band on the first chart.

2The input tabs

Where everything is

The workspace is a row of tabs, one destination each, as in every KiwiScience application: Site & land use, Climate, Soil, Plants & grazing, Fertiliser & lime, Water, Organic imports, Settings and Parameters hold everything the model is told; Results holds everything it returns. The brown bar down the left is the site menu and the Run button, and it stays put: below 960 pixels wide it folds away behind the hamburger in the top-left, because at that width a fixed 280-pixel bar would leave nothing for the model.

The model re-runs on every change, so there is no Run to press in normal use — the button is there for when you want to force a fresh set of uncertainty draws. The headline figure and the net change appear in the brown bar as soon as a run finishes, and on the Results tab as a small badge, so you can keep working on the inputs and still see what your last change did.

Land use

Before a block is picked, the list holds the model’s twenty worked New Zealand examples, each with its own district’s soil and climate. After a click it holds the land uses practised in the clicked region: every KiwiFert rotation names the regions it is practised in, and those naming this region (★) or the whole country are listed, together with the cases KiwiFert has no rotation for — retirement, native forest, wetland, compost and biochar. The region is the regional council area of the nearest NIWA climate station, shown above the list, so a click within a few kilometres of a boundary can land in the neighbour. A tick below the list adds the land uses KiwiFert does not name for the region.

Choosing a land use builds the whole run: soil and climate from the point; rotation, grazing animal and fertiliser programme from KiwiFert; irrigation switched on for dairy, arable, vegetable and orchard land where the evapotranspiration deficit is 250 mm or more; and the organic imports from the nearest worked example. The notes under the list say where each piece came from. A land use is a starting point, not a template: every value it sets is yours to edit.

Site — picking a block on KiwiMap

A live KiwiMap. Click anywhere on New Zealand and the model reads, at that point: the soil order and the full New Zealand Soil Classification subgroup, topsoil carbon with the mapped minimum and maximum, pH, cation exchange capacity, S-map drainage, texture and depth classes, relative bypass flow, land cover, land use, ecological district, and the seasonal climate. The table beside the map lists every value; the tick list beneath it decides which of them are written into the model. A click applies them straight away, so every tab describes the block you clicked; with a KiwiFert land use chosen, the whole run is rebuilt for the new point, fertiliser programme included. Re-apply the ticked values is for after you change the ticks.

Everything imported lands in the ordinary editable tabs. There is no protected “map value” anywhere: type over an imported carbon percentage and the model uses what you typed, which is the expected thing to do rather than a workaround. A measurement from your own block always outranks a national raster.

Two ticks are off by default and worth knowing about. Topsoil texture is offered because S-map's five broad classes are coarser than this model's twelve, and the soil order already supplies a texture for each horizon separately, which is usually better. pH buffer capacity writes a model parameter: it scales the lime requirement by the mapped cation exchange capacity, which is a better estimate of your block's buffering than a national default, but it is a parameter override and so is offered rather than assumed.

Site & climate

Twenty-seven locations. The monthly values are smoothed normals reconstructed from published NIWA station statistics, so they are representative of a district rather than exact. Any cell can be overwritten with your own data; a button appears to restore the library values.

Importing a point from KiwiMap does not replace this library, and it is worth being clear about why. KiwiMap carries seasonal mean temperatures but neither monthly rainfall nor monthly evapotranspiration, and a soil carbon model needs both every month. So an import picks the nearest station in the library, keeps that station's shape of the year, and shifts its twelve monthly temperatures so that the four seasonal means match the mapped ones. Rainfall and PET stay exactly as the station recorded them, and the tab tells you which station it used and how far away it is. If that station is a poor match for your block — a coastal station for an inland site, or a valley station for a hill block — overwrite the rainfall row with your own figures.

The three multipliers below the table let you explore a drier or warmer version of the same site without editing twelve numbers. The warming trend adds to air temperature progressively through the run, which is the right way to ask what a changing climate does to a stock.

Soil profile

Choosing an order from the New Zealand Soil Classification fills a whole three-horizon profile. Horizons can be added, removed and re-depthed. The properties grid holds the values you are most likely to have measured.

The drainage class deserves more attention than it usually gets. It sets where the water table sits, which sets water-filled pore space, which decides whether the soil respires aerobically or produces methane. On a wet site it changes the answer more than any rate constant.

Under Uncertainty ranges you can set the minimum and maximum for each property. They move automatically in proportion when you change a nominative value, so you only need to open that section if you know the real spread — for example, if you have replicate cores and a standard deviation.

Plants, rotation & grazing

Each row is one phase of the rotation, in order, with a length in years. The sequence repeats for the whole run, so one row means a permanent land cover and six rows means a six-year rotation. Fractional years work: 0.5 for a winter crop grazed off before spring.

Grazed is the fraction of above-ground growth eaten in place — utilisation, not stocking rate. Cut off is the fraction carted away as silage, hay, grain or fruit. The two must sum to no more than 100%; the model warns you if they do not.

Production overrides let you pin a yield you actually know. Leave a cell blank and the library value is used together with its uncertainty range, which is what the Monte Carlo run samples. Type a number and it is fixed. Note that above-ground NPP is total annual growth, not harvested yield: a maize silage crop yielding 20 t DM/ha of silage has an ANPP of about 22.

Fertiliser, lime & nitrogen

The tab that tells the model what is being spread on the block, and the one most soil carbon tools leave out. It is switched off by default on a custom run and on by default in every library scenario; switched off, every nitrogen and lime term in the model vanishes and the answer is the one the model gave before the regime existed, which makes the comparison between on and off a clean one.

From KiwiFert. Choosing a land use on the Site tab already sets the regime from KiwiFert. To take a different one, use KiwiFert's own data and calculation engine here — it connects by itself when the page is served, from the folder next door, with 51 plant types and 45 New Zealand rotations. Choose a sector, a plant type and a rotation, and it computes the programme for the block you picked on the map and hands back the nitrogen, phosphorus, potassium, sulphur and lime. Take the regime and the rotation also rewrites the Plants panel from the rotation's phases. That second step is a keyword match from KiwiFert's plant names to this model's twenty-five plants, so check what it produced before trusting it.

If the pages are opened off the disk, or KiwiFert is not beside this folder, save a scenario in KiwiFert and load the file here instead: the file carries a snapshot of the programme and needs no KiwiFert folder at all. It does not carry the annual maintenance lime, so set that yourself — or press Size the maintenance lime to hold the pH, which computes the lime that exactly neutralises the acidity the nitrogen generates.

What the model does with it. Nitrogen supply speeds the decay of nitrogen-poor residue, slows the oxidation of humified mineral-associated carbon, raises microbial carbon use efficiency, and grows more plant. Nitrogen fertiliser acidifies and lime neutralises, and the net balance moves the topsoil pH through the run — which then multiplies every decay constant in the model. The three nitrogen effects pull in different directions on purpose: the net result is the carbon line, not any one of them. Section 10 of the model description sets out every equation.

Watch the acid-and-base table at the foot of the tab. If the acid load exceeds the lime, the soil acidifies through the run and some of the carbon the model reports as retained is retained only because the soil is becoming too acid for the microorganisms. That is a real mechanism and a poor way to farm, and the results tab flags it when it happens.

Water & irrigation

Three modes. None is rain-fed. Trigger waters whenever the root-zone deficit passes a threshold in the months you tick, subject to monthly and annual caps — this is how a real irrigator behaves, and it is the mode to use unless you have records. Fixed takes twelve monthly depths, for when you do.

Organic matter imports

Compost, effluent, manure, mulch, biochar and imported feed. Rates are per year unless once is ticked, which is how to model a single biochar or compost application. Watch the units: effluent is quoted as tonnes of fresh weight and at 4% dry matter carries very little carbon, while biochar at 90% dry matter and 75% carbon carries a great deal.

Mix means the material is worked in; leave it unticked and the material lies on the surface as mulch, where it decomposes at its own rate and is drawn in slowly by soil fauna.

Model settings

Run length, the depth the headline stock is reported to (30 cm by convention, which is what most inventories use), the starting-pool choice discussed in section 4, and the uncertainty settings.

Advanced: process parameters

Every rate constant, with its default range. Anything typed here overrides the library for this run only; clear a cell to go back. Hover over a parameter name for a note on what it does and where its range comes from.

A few parameters are marked not sampled: the uncertainty run holds them at their nominative value, so their minimum and maximum are shown greyed out rather than as boxes that would quietly discard whatever you typed. Their nominative values are still editable and still change the run.

3Which inputs actually matter

Not all inputs are equal. Spending an afternoon refining a number in the bottom half of this table is wasted effort.

4Choosing the starting pools

This single setting, in Model settings, changes what the run means.

As entered (measured or library)

The run starts from the carbon concentrations in the Soil tab. Use this when you have measured them and want to know where that soil is heading. The first years will often show a steep adjustment as the pools move towards what this combination of climate, soil and management can actually hold. That adjustment is informative — it is the model telling you the soil is not in equilibrium with its management — but it is not caused by anything you changed.

Equilibrium under this management

The model runs the same management for a long time first, then starts recording. The run shows only the effect of a change you make afterwards, with no start-up drift. Use this when you are comparing two managements rather than forecasting a particular paddock.

5Reading the results

The scoreboard

Starting stock, final stock, net change and rate are for the whole modelled profile, so they will be larger than a 0–30 cm figure from an inventory. The stock to the reference depth is given separately for that comparison.

Topsoil saturation is the one to look at before getting excited about any carbon-building proposal. It is the fraction of the estimated mineral capacity that is already occupied in the top horizon. Above about 85%, additional carbon inputs will build the particulate pool — real carbon, but reversible within a few years of stopping.

The charts

Soil carbon over time

Whole profile and to the reference depth, with the uncertainty band behind each.

Carbon by pool

The stacked areas show where the carbon sits. Watch which layer is changing: a gain that is all in the particulate band is not the same result as a gain in the mineral-associated band, even though the totals are identical.

Carbon down the profile

Drawn to depth scale, so the visual weight matches the real depth of soil. Gains below the topsoil come from roots and from dissolved carbon sorbing at depth — never from anything spread on the surface.

Soil respiration

Heterotrophic only. It excludes root respiration, so it is lower than a chamber measurement of total soil respiration, typically by about half.

Methane and leached carbon

In kilograms per hectare per year. Negative methane means the soil is a net sink, which is normal for a well drained soil.

Microbial biomass carbon

Small in absolute terms but the earliest indicator in the model. A sustained change here precedes a change in the mineral-associated pool by years.

The mass balance

Every tonne is accounted for, from photosynthesis to each exit route. The Net Ecosystem Carbon Balance at the foot is computed from the fluxes; the measured change in soil and litter carbon is computed from the pools. They should agree, and the closure error is the check. If it is more than a small fraction of a tonne, something is wrong and the interface will say so.

6Reading the uncertainty band

The shaded band is the 5th to 95th percentile of repeated runs in which every uncertain input — rate constants, bulk density, carbon concentration, yield, climate — is resampled together from its range. It is not a confidence interval in the statistical sense. It is the range of answers consistent with what is currently known about the parameters.

Read it this way:

What would narrow it

Less than you would hope, and not the one thing you would expect. The uncertainty run resamples every minimum-to-maximum range in the model together: the process parameters in the Parameters tab, but also the bulk densities, carbon percentages, pH values and C:N ratios in the Soil tab and the production figures behind the Plants tab. Pinning all forty-six varying process parameters at once — every rate constant in the model known exactly — narrows the band by only about 40%. The rest is the site.

Among the process parameters, which one matters depends on the land use, and none of them dominates:

So: on an undisturbed site the mineral-associated decay constant is worth constraining, and the practical ways to do it are a repeat carbon measurement on the same site several years apart, a radiocarbon age, or a long-term incubation. On a farmed site the microbial parameters matter more. But on every land use the biggest single win is not a parameter at all — it is a measured bulk density and carbon percentage for your own horizons, with your own minimum and maximum typed into the uncertainty grid in the Soil tab. Nothing in the Parameters tab substitutes for knowing your own soil.

Increasing the number of uncertainty runs makes the band smoother, not narrower. A hundred runs is enough for a stable picture; five hundred is for a figure you are going to publish.

7Comparing two managements

The model runs one scenario at a time, which makes the comparison procedure deliberate:

1. Set up the baseline. Set the starting pools to equilibrium so the comparison is not contaminated by start-up drift.
2. Note the final stock, or download the CSV.
3. Save the scenario in the browser, under a name you will recognise.
4. Change the one thing you are testing, and nothing else. Keep the random seed the same, so the two uncertainty runs draw the same sequence of parameter sets and the difference between them is the management rather than the sampling.
5. Compare the final stocks, and compare the pool charts as well as the totals.

8Saving, loading and sharing

Save / load in the top bar offers four routes:

• Save in this browser — quick, private to that browser, and lost if the browser's storage is cleared. Good for working comparisons.
• Download as a file — a JSON file holding the complete state, including the random seed. This is the durable form: attach it to a report and anyone can reproduce the run exactly.
• Load from a file — the reverse.
• Paste JSON — for moving a scenario through email or a chat window.

The results themselves export as CSV from the button at the foot of the results, with one row per year. The whole results column also prints cleanly: the input tabs and navigation drop away, so "print to PDF" gives a clean record.

9Editing the libraries

All the reference data lives in seven plain JavaScript files in the data/ directory, each a single array of objects with a header explaining every field:

To add your own district, soil or crop, copy an existing object, change the values and give it a new id. It appears in the relevant dropdown next time the page loads. Nothing needs rebuilding and nothing else needs editing.

10Questions this model cannot answer

Being clear about this is more useful than any feature.

• "What is the carbon stock of my paddock?" Only a measurement answers that. The model predicts change given a starting point.
• "Can I claim these credits?" No. This is not an approved accounting methodology, and it is not calibrated to any site. Carbon claims need measurement against a recognised protocol.
• "How much carbon will this hillside lose?" Erosion is not modelled, and on steep country it can dominate.
• "What are the greenhouse gas emissions of this farm?" Nitrous oxide is not modelled, and in a grazed system it is a large part of the answer. The model covers carbon only.
• "Will adding fresh carbon accelerate the loss of old carbon?" Priming is real and is not represented, because there is no agreed way to parameterise it.
• "How much nitrogen will leach if I do this?" Not this model. Nitrogen enters as a supply figure and acts on the microbial terms and on the pH; it is not a pool, so there is no mineralisation, immobilisation, leaching or denitrification to report, and no nitrous oxide.
• "Should I lime this block?" The model will show you what liming does to the soil carbon, which is usually to lose some of it, and that is one input to the decision rather than the decision. Lime is applied for production, for aluminium toxicity and for nutrient availability, none of which this model represents. Ask KiwiFert that question.
• "Is a 0.4% per year increase achievable here?" The model can test the proposition, but the honest answer usually comes back as an uncertainty band that includes zero — which is itself the finding.

11Frequently asked

Why does my soil lose carbon as soon as the run starts, when I have not changed anything?

Because the carbon concentration you entered is above what this model's parameters say that soil can hold under that management. See section 4. Either your soil genuinely is not in equilibrium, or the model's parameters are wrong for your site — and the second possibility is why the Parameters tab exists.

Why is the compost doing so little?

Check the topsoil saturation. If the mineral surfaces are nearly full, most of the compost carbon ends up in the particulate pool and decomposes within a decade or two. Retention of 15 to 30% of applied carbon after fifty years is typical, and matches field trials better than most people expect.

Why does biochar behave so differently from compost?

Because about 80% of biochar carbon is pyrogenic and enters the inert pool, where it is effectively permanent. It bypasses the saturation limit entirely. That is also why it is a very different proposition agronomically: it adds carbon without feeding the soil biology.

Why is soil respiration lower than what I measured with a chamber?

The chart shows heterotrophic respiration only. A chamber measures that plus root respiration, which is typically a similar magnitude again.

Why does my wetland scenario emit so much methane?

Because it should. A saturated soil produces methane, and with the water table at the surface there is no aerobic layer for methanotrophs to consume it in. Rewetting a drained peat stops a large carbon dioxide loss and starts a methane emission; the model shows both so you can weigh them.

Can I run this offline?

Yes. There are no external requests at all, so the whole site works with no network. The two tabs that reach next door to KiwiMap and KiwiFert need a local server rather than a network — double-click Open KiwiScience.command — and both say so plainly when they cannot reach their neighbour, while everything else keeps working.

Why does my carbon go up when I stop liming?

Because acid soils hold their organic matter. Nitrogen fertiliser acidifies; without lime against it the topsoil pH falls, and pH multiplies every decay constant in the model. Some of the carbon a run like that reports as retained is retained only because the soil is becoming too acid for the microorganisms — which is a real mechanism and a poor way to farm. The results tab flags it when it happens, and the honest comparison is against a run with enough lime to hold the pH.

Why does the model lose carbon when I add nitrogen, on one block and not another?

Nitrogen does three things at once, and they pull in different directions. It speeds the decay of nitrogen-poor residue, it slows the oxidation of humified mineral-associated carbon, and it raises microbial carbon use efficiency; on top of that it grows more plant, and it acidifies. Which way the total goes depends on the substrate, on how close the soil is to carbon saturation, and on whether it is being limed. That is not an evasion — it is why the fertiliser regime has to be in the model rather than reasoned about afterwards.

The rotation KiwiFert gave me has the wrong plants in it.

Quite possibly. KiwiFert names 51 plant types and 175 rotation phases; this model has 25 plants, and the two are matched by keyword. The fertiliser numbers are exact — they come from KiwiFert's own calculation — but the rotation is a first guess. Fix it on the Plants & grazing tab, which is what that tab is for.

How long can I run it for?

Technically up to 500 years. Meaningfully, about 50: beyond that the compounded uncertainty in the soil, the production and the rate constants together is so wide that the projection stops carrying information.

Where do the New Zealand values come from?

NIWA climate normals, the New Zealand Soil Classification and National Soils Database summaries, published agronomic data from DairyNZ, Beef+Lamb NZ, FAR and Plant & Food Research, and the international soil carbon literature for the process parameters. Each library file names its sources in the header, and the Parameter library page shows the values themselves.

Found something that behaves oddly, or have better New Zealand values for one of the libraries? Those files are meant to be edited — that is why they are plain arrays with a comment above every field.

↑ Back to top