Basis parameters
Every assumption the engine makes is a parameter of the basis: the defaults below, changed in the Scenario & basis panel, in a province file's basis, or in an experiment's base and arms. The whole set is hashed into the basis hash printed on every export, so a result can always be traced to what it assumed.
A province file only needs the parameters it changes. The editor completes each name and shows its meaning, range and default on hover, from the same source as this page. A value outside the range a file may set is left out, with a warning in Problems, and the rest of the file is applied.
Where each default comes from is in Assumptions and provenance.
The run
| Parameter |
Meaning |
Default |
A file may set |
seed |
The province's seed: the same seed and basis give the same households, the same weather and the same history, on any machine. In a province file it is seed, beside the basis; an experiment chooses its own seeds. |
"agincourt-12" |
any text (a province file's seed) |
startDate |
The first day of the run (YYYY-MM-DD). |
"2026-01-04" |
a date, YYYY-MM-DD |
placeName |
The original village (Ebenezer): its name carries into the first city's institutions. |
"Ebenezer" |
a short text (60 characters at most) |
regionName |
The province the three cities, the centre and the airport make up: names the Mutual Bank, the burial society and the Hyperline. |
"Unity" |
a short text (60 characters at most) |
journalRetentionMonths |
Months of full journal kept in memory (older months keep their digests and ledger balances). |
36 |
not settable from a file |
Population and households
| Parameter |
Meaning |
Default |
A file may set |
households |
Households seeded in Ebenezer, the original village, at the start. Every other settlement seeds the count its layout gives it, so the default province starts with 100 households. |
12 |
1 to 16 |
meanHouseholdSize |
Mean household size (Poisson-ish, min 1). |
4.2 |
1.5 to 7 |
ageProfile |
The mix of household types at the start (families, couples, single parents, multigenerational, elderly, single): young, balanced or ageing. The low-income settlements always start young. |
"balanced" |
young, balanced, ageing |
maleShareAtBirth |
Share male at birth (SA ≈ 0.503). |
0.503 |
0.45 to 0.55 |
educationMix |
Adult education attainment mix at t0 (sums to 1). Ebenezer's households only: every other settlement takes its tier's value (see Settlement tiers below). |
none 0.03, primary 0.15, secondary 0.32, matric 0.3, tertiary 0.16, postgrad 0.04 |
six shares, normalised to sum to 1 |
homeschoolShare |
Share of school-age children homeschooled (household-level decision). |
0.15 |
0 to 1 |
tertiaryProgression |
Probability a matriculant goes on to tertiary study (leaves for the city). |
0.35 |
0 to 1 |
youthEmigrationHazard |
Annual emigration hazard for a 18-30 year old (study / work elsewhere). |
0.05 |
0 to 0.5 |
immigrationHazard |
Annual probability an empty house is re-let to an in-migrant household. |
0.25 |
0 to 1 |
retirementAge |
Retirement age. |
65 |
55 to 75 |
Mortality
| Parameter |
Meaning |
Default |
A file may set |
mortalityPreset |
The mortality table the province lives on and A/E is measured against (see the presets below). |
"sa-2024" |
sa-2024, agincourt-2005-07, agincourt-1994-97, developed-2020 |
mortalityImprovement |
Annual mortality improvement applied to the whole table (Lee–Carter-style drift). |
0.01 |
0 to 0.03 |
bereavementMultiplier |
Widowhood effect: relative mortality in the first year after losing a spouse. |
1.6 |
1 to 3 |
povertyMortalityMultiplier |
Extra mortality multiplier for households below the poverty line. |
1.15 |
1 to 2 |
Mortality presets
Each preset is a Heligman–Pollard law with its own parameters for men and women. The life expectancies, infant and under-five mortality are what each table implies before any improvement (a period life table on the preset, radix 100,000, a₀ = 0.1), computed by the engine's own functions.
mortalityPreset |
Table |
e₀ men / women |
e₆₅ men / women |
q₀ men / women (‰) |
Under-five, men / women (‰) |
sa-2024 |
South Africa 2024 (Stats SA calibrated) |
63.6 / 69.2 |
13.4 / 16.5 |
24.6 / 21.3 |
26.9 / 26.0 |
agincourt-2005-07 |
Rural SA, early ART era (Agincourt 2005-07) |
50.8 / 55.8 |
13.4 / 15.8 |
32.5 / 40.3 |
43.8 / 53.1 |
agincourt-1994-97 |
Rural SA, pre-HIV peak (Agincourt 1994-97) |
65.5 / 70.7 |
15.3 / 16.3 |
12.6 / 16.7 |
20.5 / 25.8 |
developed-2020 |
Developed country, illustrative (e0 ≈ 79/84) |
79.0 / 83.9 |
18.5 / 21.5 |
4.4 / 3.6 |
5.2 / 4.4 |
Their sources, and the parameters themselves:
| Preset |
Source |
Fitted to |
Men: A, B, C, D, E, F, G, H |
Women: A, B, C, D, E, F, G, H |
sa-2024 |
HP shape from Agincourt HDSS 2005-07 (Sharrow et al. 2013) re-calibrated to Stats SA P0302 2024: e0 M 63.6 / F 69.2, IMR 22.9‰ |
single-year q |
0.0122, 0.7754, 0.6774, 0.005906, 3.4, 38, 0.0001256, 1.0885 |
0.01561, 0.8563, 0.5009, 0.005869, 2.6, 40, 0.00001868, 1.1092 |
agincourt-2005-07 |
Sharrow et al. 2013, Demographic Research 29:39, Table 2 posterior medians |
n-year interval q (1q0, 4q1, 5qx), converted to single years |
0.0262, 0.7754, 0.2083, 0.1199, 3.7761, 42.261, 0.0009, 1.0827 |
0.0356, 0.8563, 0.2373, 0.0867, 2.5266, 40.6617, 0.0001, 1.1092 |
agincourt-1994-97 |
Sharrow et al. 2013, Demographic Research 29:39, Table 2 posterior medians |
n-year interval q (1q0, 4q1, 5qx), converted to single years |
0.0106, 0.7829, 0.0855, 0.0243, 5.2779, 45.2412, 0.001, 1.0798 |
0.0148, 0.7852, 0.1048, 0.0126, 14.5269, 31.1959, 0.0003, 1.0958 |
developed-2020 |
Illustrative HP parameters in the range reported for low-mortality populations; calibrated to e0 79.0 / 84.0, IMR 4‰ |
single-year q |
0.0003348, 0.03, 0.1108, 0.001029, 9, 22, 0.00001774, 1.107 |
0.0003268, 0.03, 0.1013, 0.000001, 9, 22, 0.000008405, 1.112 |
Health
| Parameter |
Meaning |
Default |
A file may set |
healthProfile |
The health setting: South African rural or urban, or a developed country. It sets the prevalence of chronic conditions at the start (HIV prevalence is a tenth higher in sa-rural); developed also lowers the infection rates, maternal mortality and the chance of finding work. |
"sa-rural" |
sa-rural, sa-urban, developed |
hivEnabled |
Extra: enable HIV dynamics in the health profile. |
true |
true or false |
careQuality |
Clinic care quality: reduction in case-fatality for treated illness. |
0.55 |
0 to 1 |
fluAttackRate |
Seasonal flu attack rate per person per year. |
0.12 |
0 to 0.5 |
Fertility, courtship and marriage
| Parameter |
Meaning |
Default |
A file may set |
fertilityShape |
The shape of the age-specific fertility schedule, scaled to the TFR (see the shapes below). |
"sa" |
sa, late |
tfr |
Target total fertility rate for the ASFR level. |
2.41 |
0.8 to 6 |
contraceptionShare |
0..1 share of couples deliberately spacing / limiting (scales the level). |
0 |
0 to 1 |
marriageAgeM |
Mean age at first marriage, men; the courtship hazard peaks a year before it. |
30 |
20 to 45 |
marriageAgeF |
Mean age at first marriage, women; the courtship hazard peaks a year before it. |
27 |
18 to 42 |
courtshipHazard |
Annual probability an eligible single starts a courtship (at the peak age). |
0.28 |
0 to 1 |
divorceHazard |
Annual divorce hazard for a married couple. |
0.006 |
0 to 0.1 |
Fertility shapes
Births per 1,000 women a year by age band, as the shapes are written. The engine scales the chosen shape so that its total fertility equals tfr (the default 2.41), then adjusts each woman's monthly chance for her partnership, parity, schooling and health.
| Band |
sa |
late |
| 15-19 |
60 |
10 |
| 20-24 |
120 |
45 |
| 25-29 |
118 |
90 |
| 30-34 |
88 |
105 |
| 35-39 |
50 |
60 |
| 40-44 |
15 |
13 |
| 45-49 |
3 |
1 |
| TFR as written |
2.27 |
1.62 |
Society, safety and getting about
| Parameter |
Meaning |
Default |
A file may set |
churchAttendance |
Share of residents at the Sunday service in a typical week, and the mean of each person's faith, in the church-going cities (Emmaus and Ithemba; Newhaven has no church). Households decide together, so realised attendance tracks it closely. |
0.95 |
0 to 1 |
intrudersPerYear |
Expected intruder / external incidents per year. |
6 |
0 to 60 |
disputeRate |
Expected disputes per 100 residents per year before personality effects. |
25 |
0 to 200 |
policeEffectiveness |
Police response speed multiplier (1 = normal). |
1 |
0 to 2 |
carOwnership |
Chance that a household with a driver has a car at the start, raised by 30% above R15,000 a month of income and cut by 40% below it. Ebenezer's households only: every other settlement takes its tier's value (see Settlement tiers below). |
0.6 |
0 to 1 |
roadAccidentPer1000Km |
Road accident hazard per 1,000 km driven (injury or worse). |
0.0035 |
0 to 0.05 |
trainMach |
The Hyperline's cruising speed in Mach. The trains are launched and caught electromagnetically within the platform's length, so a hop between stations takes about a second of simulated time at Mach 5. |
5 |
1 to 12 |
climate |
The climate normals the daily weather is drawn around (see the climates below). |
"highveld" |
highveld, western-cape, kzn-coast, temperate-north |
Climates
climate |
Normals |
highveld |
Highveld (Johannesburg) |
western-cape |
Western Cape (Stellenbosch) |
kzn-coast |
KZN coast (Durban) |
temperate-north |
Temperate north (generic) |
The burial society and cover
| Parameter |
Meaning |
Default |
A file may set |
funeralPremium |
Monthly funeral premium per covered household (ZAR), indexed by CPI. |
120 |
0 to 1,000 |
funeralBenefit |
The funeral benefit the society pays on the death of a covered member (ZAR), indexed by CPI. |
25,000 |
0 to 100,000 |
lifeCoverSum |
Life cover sum assured per adult policy (ZAR). |
100,000 |
0 to 2,000,000 |
lifeCoverPremium |
Monthly life premium per covered adult aged 18 to 64 (ZAR), indexed by CPI. |
120 |
0 to 2,000 |
funeralCoverShare |
Share of households with funeral cover at the start. Ebenezer's households only: every other settlement takes its tier's value (see Settlement tiers below). |
0.75 |
0 to 1 |
lifeCoverShare |
Share of households with life cover at the start. Ebenezer's households only: every other settlement takes its tier's value (see Settlement tiers below). |
0.35 |
0 to 1 |
medicalAidShare |
Chance that a household is on a medical scheme at the start, raised by 60% above R25,000 a month of income and cut by 40% below it. Ebenezer's households only: every other settlement takes its tier's value (see Settlement tiers below). |
0.3 |
0 to 1 |
schemeReserve |
Initial reserve of the community scheme (ZAR). |
200,000 |
0 to 5,000,000 |
Grants and poverty
| Parameter |
Meaning |
Default |
A file may set |
childGrant |
Child support grant (ZAR a month) for children under 18 in households with income per person below 2.5 poverty lines; indexed by CPI. |
580 |
0 to 3,000 |
oldAgeGrant |
Older persons grant (ZAR a month) for residents of 60 and over without income, R20 more from 75; indexed by CPI. |
2,400 |
0 to 6,000 |
povertyLine |
Household poverty line per member per month (ZAR). |
1,634 |
0 to 6,000 |
The economy, tax and the bank
| Parameter |
Meaning |
Default |
A file may set |
repoRate |
The Reserve Bank's repo rate at the start (6.75% in January 2026); the Monetary Policy Committee sets it from then on. |
0.0675 |
0.0025 to 0.3 |
inflationStart |
National CPI inflation at the start (4.3%). |
0.043 |
-0.02 to 0.3 |
inflationTarget |
The Reserve Bank's inflation target, which the committee's Taylor rule aims at. |
0.03 |
0 to 0.15 |
minimumWageHourly |
National minimum wage per hour (R30.23 from 1 March 2026). |
30.23 |
0 to 200 |
realWageGrowth |
Real wage growth added to CPI at the March wage round. |
0.005 |
-0.05 to 0.08 |
bracketIndexation |
Share of CPI inflation applied to tax brackets and rebates each March (1 = fully indexed, 0 = fiscal drag). |
1 |
0 to 1.5 |
titheRate |
Share of net earnings a fully committed household tithes. |
0.1 |
0 to 0.3 |
churchS18A |
Whether the church holds s18A approval (tithes deductible up to 10% of taxable income). |
false |
true or false |
bankFoundingCapital |
The Mutual Bank's founding share capital (ZAR); R10 million is the Mutual Banks Act's minimum. |
10,000,000 |
1,000,000 to 100,000,000 |
bankMemberShare |
Member shares each household subscribes in the Mutual Bank (ZAR). |
5,000 |
0 to 100,000 |
councilStipend |
Monthly council stipend per elected seat (ZAR, indexed with wages; PAYE withheld at the marginal rate). |
4,800 |
0 to 50,000 |
Settlement tiers
Each settlement belongs to a wealth tier, and its households start from the tier's profile: schooling, cars, cover, savings and work. Ebenezer's own households read the baseline parameters above instead (educationMix, carOwnership and the cover shares, whose defaults are the middle profile's values), and open with 0.5 to 6 months of income in savings, although its tier is affluent. How many households each settlement starts with is part of its layout, not its tier. A file may set the shares marked settable, tier by tier, under basis.tiers:
"basis": { "tiers": { "low-income": { "funeralCoverShare": 1 } } }
| Field |
Meaning |
ultra |
affluent |
comfortable |
middle |
working |
low-income |
carOwnership |
Chance that a household with a driver has a car at the start, scaled by income as carOwnership above. Settable. |
0.98 |
0.95 |
0.85 |
0.6 |
0.32 |
0.15 |
secondCarShare |
Share of a household's further adult drivers (beyond the first) who run a car of their own. Settable. |
0.85 |
0.55 |
0.3 |
0.12 |
0.04 |
0.01 |
funeralCoverShare |
Share of households with funeral cover at the start. Settable. |
0.9 |
0.85 |
0.8 |
0.75 |
0.7 |
0.65 |
lifeCoverShare |
Share of households with life cover at the start. Settable. |
0.9 |
0.75 |
0.55 |
0.35 |
0.2 |
0.12 |
medicalAidShare |
Chance of a medical scheme at the start, scaled by income as medicalAidShare above. Settable. |
0.97 |
0.85 |
0.6 |
0.3 |
0.1 |
0.04 |
unemployment |
Share of working-age adults without formal work at t0 (drives the fallback job mix). Settable. |
0.03 |
0.08 |
0.12 |
0.3 |
0.35 |
0.42 |
savingsMonths |
Opening savings in months of household income, [lo, hi] uniform. |
12 to 48 |
4 to 18 |
2 to 10 |
0.5 to 6 |
0.3 to 4 |
0.2 to 2.5 |
Schooling at the start, by tier (shares of adults):
| Tier |
none |
primary |
secondary |
matric |
tertiary |
postgrad |
ultra |
0.002 |
0.008 |
0.05 |
0.2 |
0.45 |
0.29 |
affluent |
0.005 |
0.02 |
0.1 |
0.295 |
0.4 |
0.18 |
comfortable |
0.01 |
0.06 |
0.22 |
0.36 |
0.28 |
0.07 |
middle |
0.03 |
0.15 |
0.32 |
0.3 |
0.16 |
0.04 |
working |
0.05 |
0.2 |
0.4 |
0.26 |
0.08 |
0.01 |
low-income |
0.09 |
0.28 |
0.4 |
0.19 |
0.035 |
0.005 |
Two inputs are not set through basis, because they are not single numbers:
- A mortality table to live on instead of the preset: a province file's
mortality (a CSV in the workspace, or a table inline), an experiment's baseMortality or an arm's mortality. See Mortality tables.
- Timed shocks:
shocks (at most 12), each a mortality, repo or oil shock over a span of months. See Province files.
Both are hashed into the basis like any parameter when they are present, and absent otherwise, so a default province's basis hash does not depend on them.