GitHub release (latest by date including pre-releases) GitHub

Health-GPS microsimulation is part of the STOP project, and supports researchers and policy makers in the analysis of the health and economic impacts of alternative measures to tackle chronic diseases and obesity in children. The model reproduces the characteristics of a population and simulates key individual event histories associated with key components of relevant behaviours, such as physical activity, and diseases such as diabetes or cancer.

Health-GPS has now been adapted to run for projects such as FINCH, JACARDI and JA PreventNCD. It can run for multiple projects using the inputs available at HealthGPS-examples for each of the projects. Example: to run for STOP, use the HLM_France folder; for India the KevinHall_India folder; for FINCH the KevinHall_FINCH folder.

The Health GPS microsimulation is being developed in collaboration between the Centre for Health Economics & Policy Innovation (CHEPI), Imperial College London; and INRAE, France; as part of the STOP project. The software architecture uses a modular design approach to provide the building blocks of the Health GPS application, which is implemented using object-oriented principles in Modern C++ programming language targeting the C++20 standard.

Documentation

Full docs live under [documentation/](documentation/README.md). Start there for indexes by audience.

Need	Document
Documentation home	documentation/README.md
Site-style intro (diagrams)	documentation/index.md
First run / binaries	Quick Start
Config, outputs, HPC	User Guide
JSON schemas (diagrams)	Configuration schemas
Models and module I/O	Models overview · Simulation models reference
Build from source / CMake	Developer Guide
Architecture	Software Architecture
Data model / Datastore	Data Model
Windows MSVC / Ninja (`cstdint`, `MSVCRTD.lib`)	MSVC troubleshooting
GitHub Pages deploy failed	Docs deploy troubleshooting
FINCH / income / predictors	FINCH guide
Feb 2026 integrated changes	Update report
Threading / HPC sizing	Performance guide
Feature plans	technical/README.md
Doxygen API (GitHub Pages)	API

Published website: https://imperialchepi.github.io/healthgps/. It is rebuilt from documentation/ by the docs workflow on release or manual dispatch, not on every push. Until that workflow runs against the current tree, the live site may lag the repo (older flat page layout).

February 2026 updates

The HealthGPS Update Report – 20th Feb 2026 summarises integrated changes (demographics, socioeconomic/income, static and dynamic risk factors, analysis/output, disease/PIF, policy, config/schema), parallelisation notes, and a developer file map. Snippets below are taken from that report.

Supported use cases: India, ADB, and FINCH on a shared codebase; backward compatibility with older India-style configs is retained alongside newer schema options.

Module pipeline (simplified):

flowchart LR
    DEMO[Demographic Module] --> SES[Socioeconomic Module]
    SES --> RF[Risk Factor Module]
    RF --> DIS[Disease Module]
    DIS --> IO[Read/write to files]

Host application, run loop, module order, and output:

flowchart TB
    subgraph host [Host Application]
        MAIN["main (program.cpp)"]
        CLI[Parse CLI options]
        CFG[Load config JSON]
        DATA[Load datatable / DataManager]
        REPO[Repository + register risk factor definitions]
        FACTORY[Module factory]
        MODEL_INPUT[Create ModelInput]
        BUS[Create EventBus]
        WRITERS[Result + optional ID-tracking writers]
        MONITOR[EventMonitor]
        RUNNER[Runner]
        CHAN[SyncChannel]
        CREATE_BASE[Create baseline Simulation]
        CREATE_POL[Create intervention Simulation if configured]
        RUN[Runner.run: baseline and optionally intervention]
        STOP[EventMonitor.stop]
        EXIT[Exit]
        MAIN --> CLI --> CFG --> DATA --> REPO --> FACTORY
        FACTORY --> MODEL_INPUT
        MODEL_INPUT --> BUS --> WRITERS --> MONITOR
        MONITOR --> RUNNER --> CHAN --> CREATE_BASE --> CREATE_POL --> RUN --> STOP --> EXIT
    end
 
    subgraph runLoop [Per-trial run loop]
        SETUP[Setup run: seed]
        SIM_ADD[Add Simulation to ADEVS Simulator]
        INIT[Simulation.init: initialise_population]
        TICK[Simulation.update: update_population]
        FINI[Simulation.fini: cleanup]
        SETUP --> SIM_ADD --> INIT --> TICK
        TICK --> TICK
        TICK --> FINI
    end
 
    subgraph initPop [initialise_population order]
        D_INIT[Demographic]
        SES_INIT[SES]
        RF_INIT[Risk factor: static then dynamic]
        DIS_INIT[Disease]
        A_INIT[Analysis]
        STATS[Print initial population statistics]
        D_INIT --> SES_INIT --> RF_INIT --> DIS_INIT --> A_INIT --> STATS
    end
 
    subgraph updatePop [update_population order]
        D_UPD[Demographic update]
        MIG[Net immigration]
        SES_UPD[SES update]
        RF_UPD[Risk factor update]
        DIS_UPD[Disease update]
        A_UPD[Analysis update: publish results]
        D_UPD --> MIG --> SES_UPD --> RF_UPD --> DIS_UPD --> A_UPD
    end
 
    subgraph output [Output]
        PUB[Analysis publishes ResultEventMessage and optionally IndividualTrackingEventMessage]
        DISPATCH[EventMonitor dispatch threads]
        JSON_CSV[ResultFileWriter: JSON + main CSV + income CSVs]
        TRACK[IndividualIDTrackingWriter: tracking CSV]
        PUB --> DISPATCH --> JSON_CSV
        PUB --> DISPATCH --> TRACK
    end
 
    RUN --> runLoop
    INIT --> initPop
    TICK --> updatePop
    A_UPD --> PUB

Person initialisation sequence (overview):

flowchart TB
    A[Age] --> B[Gender]
    B --> C["Region (if available)"]
    C --> D["Ethnicity (if available)"]
    D --> E["Sector (if available)"]
    E --> F[Income]
    F --> G["Categorical: direct assignment (e.g. India)"]
    F --> H["Continuous: compute value, quartiles, assign categories (e.g. FINCH)"]
    G --> I[Risk Factors]
    H --> I
    I --> I1["Two-stage: Stage 1 logistic"]
    I1 --> I1b["Stage 2 Box-Cox"]
    I --> I2["Box-Cox only"]
    I1b --> RFA
    I2 --> RFA
    RFA["Risk factors assigned"] --> J[Physical Activity]
    J --> J1[Simple PA]
    J --> J2[Continuous PA]
    J1 --> PAD
    J2 --> PAD
    PAD["PA assigned"] --> K["Adjust to factors mean (if enabled)"]
    K --> L["Policies (if enabled)"]
    L --> M["Trends (if enabled)"]
    M --> N["UPF trends: multiplicative over time"]
    M --> O["Income trends: exponential decay"]
    N --> P[Trended Risk Factor Adjustment]
    O --> P
    P --> Q[Kevin Hall Model]
    Q --> R[Disease Model]

Project Status and Recent Progress

Last updated Significant progress has been made across the HealthGPS codebase. The following features and improvements are now completed:

Trended adjustment framework
Schema validation and dynamic schema handling
Risk factor configuration via external config files
Dynamic age caps and age limits
Income-based input and output files
Individual ID based tracking and output
Consistent data loading across modules
Log-transformed energy intake handling
FINCH-specific age cap implementation
Trended factor mean calculations

These updates improve robustness, extensibility, and consistency across both baseline and intervention workflows.

Detailed tables describing:

Where parallelisation is applied
Population Impact Fraction (PIF) handling
Income and individual ID tracking mechanisms

are in the full update report.

Relevant design documents (under documentation/technical/plans/):

Individual ID tracking
Consistent person IDs across scenarios
Income quintile factor means
Project requirements
Performance / parallelization notes

Project Specific Requirements

Health-GPS is driven by config flags (not hard-coded project names). Optional project_requirements in config.json controls demographics (region, ethnicity, gender2), income type and final category count (3 / 4 / 5), physical activity, trends, and two-stage logistic behaviour. See:

Project requirements plan
User Guide: project requirements
Schema: schemas/v1/config/project_requirements.json

FINCH: Age/Gender/Income-Based Model Validation

As part of the FINCH project, income-stratum and quintile-based calibration adjust model outputs to better reflect observed distributions by:

Age
Gender
Income quintiles (or any number of income categories the user specifies)

This enables income-stratified calibration and improves external validity when comparing model outputs against observed data.

See the modeller-facing FINCH guide and the income quintile factor means plan.

Quick Start

The Health GPS application provides a command line interface (CLI) and runs on Windows 10 (and newer) and Linux devices. All supported options are provided to the model via a configuration file (JSON format), including intervention scenarios and multiple runs. Users are encouraged to start exploring the model by changing the provided example configuration file and running the model again.

Prefer -c / --config for the config path (file, folder, or zip URL). Put the backend datastore in data.source inside the config. Optional flags include -T / --threads (TBB cap) and --dry-run. Deprecated: -f / --file and -s / --storage.

From a Git Bash-style shell, run the console app with a config file and optional thread count:

/c/healthgps/out/build/windows-release/src/HealthGPS.Console/HealthGPS.Console.exe \
  -c /c/healthgps-examples/KevinHall_India/config.json \
  -T 2

First argument path: built executable HealthGPS.Console.exe. -c: path to your JSON configuration (input / scenario). -T: number of threads TBB may use for parallel work (example: 2). If you omit -T, the model uses the maximum parallelism available on your machine (effectively up to the number of logical CPUs), subject to TBB defaults.

NOTE: If you specify the number of threads, a minimum of 2 threads is required.

Adjust the two paths to match where you built Health-GPS and where your config.json lives (e.g. PowerShell):

C:\healthgps\...\HealthGPS.Console.exe -c C:\healthgps-examples\...

For more information, see the documentation home, Quick Start, and the User Guide.

Development Tools

The Health GPS software is written in modern, standard ANSI C++, targeting the C++20 version and using the C++Standard Library. The project is fully managed by CMake and Microsoft Visual Studio, the code base is portable but requires a C++20 compatible compiler to build. The development toolset uses Ninja for build, vcpkg package manager for dependencies, googletest for unit testing and GitHub Actions for automated builds.

For more information, see the Developer Guide. On Windows, if CMake cannot find headers such as cstdint or linking fails on MSVCRTD.lib, see MSVC / Ninja troubleshooting.

License

The code in this repository is licensed under the BSD 3-Clause license.

Third-party components

Libraries

Name	License
Adevs	BSD 3-Clause
crossguid	MIT
cxxopts	MIT
eigen	MPL2
fmt	MIT
nlohmann-json	MIT
jsoncons	Boost
rapidcsv	BSD 3-Clause
oneAPI TBB	Apache 2.0
libzippp	MIT
openssl	Apache 2.0
PlatformFolders	MIT
curlpp	MIT

Tools and Frameworks

Name	License
vcpkg	MIT
googletest	BSD 3-Clause

Author: Mahima Ghosh