Model initialisation

MtM ABM description

The steps in model initialisation are shown in the flow chart below. Although almost all code between these two initialisation pathways is shared, they are executed in separate sequences to ensure that random seed initialisation works correctly in the random geography case. The steps coloured pink and blue below run differently depending on whether initialisation is random or from GIS files.

flowchart TB
  A((START))
  B[Read land uses and<br>interventions from files]
  C{Geography<br>from GIS<br>files?}
  D[Read LUC<br>from <span style='font-family:monospace;'>luc.asc</span>]
  E[Read farms<br>from <span style='font-family:monospace;'>parcels.shp</span>]
  F[Initialise farmers<br>one per farm]
  G[Read land use from<br><span style='font-family:monospace;'>landuse.asc</span> and assign<br>to farms]
  H[Setup farmer networks]
  I[Partition farms by<br>LUC into holdings]
  J[Setup LUC<br>on land]
  K[Partition land<br>into farms]
  L[Initialise farmers<br>one per farm]
  M[Partition farms by<br>LUC into holdings]
  N[Setup farmer networks]
  O[Partition farms by<br>LUC into holdings]
  P[Initialise market<br>settings from files]
  Q[Run one<br>'burn-in' cycle]
  R[Store settings<br>for rapid reset]
  S((END))
  A --> B
  B --> C
  C -->|Yes| D
  D --> E
  E --> F
  F --> G
  G --> H
  H --> I
  I --> P
  C -->|No| J
  J --> K
  K --> L
  L --> M
  M --> N
  N --> O
  O --> P
  P --> Q
  Q --> R
  R --> S
  classDef pink fill:#fcc
  classDef blue fill:#cdf
  class D,E,G pink
  class J,K,M blue

An important detail is that initialisation completes with a ‘burn-in’ run of a single cycle of the model. This means in the GIS initialisation case that the starting state of the model will not necessarily match exactly the data contained in the initialisation files (because some farms might change landuse during burn-in), but will reflect one tick of model evolution. Using a random seed, this step is guaranteed to be the same every time so that repeatability is still attained. A single ‘burn-in’ step is needed to generate plausible prior year income and costs which the model requires to run.

It is important to note that there are tricky sequencing issues in the setup which make the associated code rather ‘fragile’ with some apparently unproblematic changes likely to break the model! (These are noted in code comments.)

Update History

Date	Changes
2025-02-19	Initial post.
2025-08-05	Made differences between random and GIS initialisation clearer.
2025-10-17	Some blocks with overflow labels fixed.