Tutorial

This page describes how to get from an empty machine to a set of results. Nothing here is fast: a full global run is a matter of days, not hours, and it is normal to run one continent or one country at a time.

Requirements

• A recent Windows machine. The model has been run with GeoDMS 18.1.2.
• A large amount of RAM, or a very large page file. A continental network with all its origins and destinations has to be held in memory during routing, and the largest continents are the reason China, India and the United States are cut into functional areas.
• Fast local disk with plenty of room. The OSM extracts alone are tens of gigabytes, and the stored networks and result grids add substantially to that.
• GeoDMS, installed under C:\Program Files\ObjectVision\GeoDMS<version>.

Getting the configuration

git clone https://github.com/ObjectVision/NetworkModel_World.git

The configuration is entered through cfg/main.dms.

Getting the data

The README of the repository lists download locations for the prepared settlement, region and population data. The OSM .pbf files come from Geofabrik and are available on request; they are already fully compressed and still take tens of gigabytes.

Place everything under %SourceDataDir%/NetworkModel_World, in the layout the configuration expects:

NetworkModel_World/
  Infrastructure/OSM/<date>/<region>-latest.osm.pbf
  population/GHS_WUP_POP_..._1000_V1_0.tif
  Settlements/<settlement set>/<set>_labelRC_DB.shp   (and SDUC, DUC, UC)
  Regions/Global_admin0.shp
  Regions/rus_dissolved.shp
  Regions/esp_dissolved_wgs84.shp
  Regions/FUAs/FUAs_OECD_4326.shp
  Regions/FUAs/country_outlines_from_gadm.shp
  Regions/fas_combined_20250428_54009.shp
  adhoc/built_s_wgs84_v1.tif

If your data live elsewhere, adjust NetworkModelWorld_DataDir in ConfigSettings/Overridable in main.dms rather than editing the individual storage names.

Then check ModelParameters: the population version, the OSM file date and the settlement set have to match the files you actually have. See Model parameters.

Step 1: prepare the unlinked data

These steps have to run once, in order. They are grouped in MakeUnlinkedData at the top of main.dms, and each writes a file that later steps read back.

GeoDmsRun.exe cfg\main.dms /MakeUnlinkedData/s1_Create_Countries

Then, in the same way, s2_Create_Sep_Units, s3_Create_LandCells, s4_Create_SettlementCentroids and s5_Create_OSM_Continents_fss.

Step 3 reads the full global population raster and step 5 reads every OSM .pbf file, so these two take by far the longest. They only have to be repeated when the population version or the OSM date changes.

Step 2: build the networks

Per continent, in this order:

GeoDmsRun.exe cfg\main.dms /NetworkSetup/Per_Continent/Europe/Store_Network1
GeoDmsRun.exe cfg\main.dms /NetworkSetup/Per_Continent/Europe/Store_Network2

batch/gen_continental_networks.cmd loops this over a list of continents. Expect this to be the most memory hungry part of the whole chain. See Network construction.

Step 3: settlement hierarchies

Per continent:

GeoDmsRun.exe cfg\main.dms /Analyses/Obtain_Settlement_Hierarchies/Europe/Store_Hierarchies

Every analysis after this reads the stored hierarchies, so this cannot be skipped.

Step 4: the analyses

From here on the work is per country, and the four analyses are independent of each other.

Catchments, see Catchments:

GeoDmsRun.exe cfg\main.dms /Analyses/Create_Centres_Catchments/m10_ex_fua/Europe/Country_Catchments/NLD/store_catchment

Functional rural areas, see Functional rural areas, which need the catchments of the same variant to exist first:

GeoDmsRun.exe cfg\main.dms /Analyses/Functional_Rural_Areas/Per_Continent/Europe/iterate_by_Memberstates/NLD/ResultsByVariant/button/runAll

Travel distance proxy, see Travel distance proxy:

GeoDmsRun.exe cfg\main.dms /Analyses/ComputeProxy/Per_Continent/Europe/country_proxy/NLD/Results_per_distdecay/Geurs_VanEck_2003_general/store1

followed by store2 for the flow grids.

Road lengths, see Road lengths, which run per continent rather than per country.

The batch scripts

batch/ holds four scripts that loop the calls above over country and continent lists:

Script	Purpose
gen_continental_networks.cmd	build the networks per continent
gen_catchments.cmd	catchments per country
gen_functional_areas.cmd	functional rural areas per country
compute_proxy.cmd	travel distance proxy per country

They all share the same shape: a pf, config and geodmsversion variable at the top, then a country list per continent, then a for loop per continent. Lines and whole loops are commented out with rem depending on what is being run at that moment, so read the top of a script before running it rather than assuming it does what its name says.

The paths in these scripts are hard coded to the machine they were last run on, so set config= has to be pointed at your own checkout.

Rather than editing the scripts in place, it is usually easier to copy one and edit the copy, since the country lists in the committed versions record which subset was requested for a particular delivery.

Resuming after a crash

A run over 240 countries will not finish in one go. Two things make resuming practical:

• every step writes its result to disk and reads it back, so a completed country is never recomputed;
• the travel proxy exposes an all_stored flag per zone that tests whether its output files already exist, and Analyses/collect_results skips countries whose result file is missing when it builds a mosaic.

In practice this means a failed batch can be restarted after trimming the country list to what is still missing.

Known limits

The comments in Analyses/computeproxy.dms record which countries did not complete on the machine used at the time: China, India and the United States failed on memory allocation and are now run through functional areas, and a number of smaller territories were missing from the country lists rather than from the model. If a country produces no output, check the batch list first before looking for a modelling problem.