The HIV Workflow (hiv_workflow) is a set of scripts and libraries utilizing idmtools, idmtools-calibra, and emodpy-hiv for calibration and running of EMOD.


Documentation is available at


Software prerequisites

  • This guide assumes Python 3.7.X (3.7.7 or higher) (64-bit) is installed ( in Windows or Linux and assumes it is custom-installed into C:Python37 in Windows or /c/Python37 in Linux. (Download the exe or tgz to install.)

  • This guide further assumes a Linux-like command terminal is being used for Windows (e.g. git bash in Windows), not the built-in Windows cmd.

Installation steps

  1. Create and activate a clean virtual environment.

    If you have Python installed to a different directory, please update the Python interpreter path below to match your installation of Python.

    1. Create the virtual environment:

      /c/Python37/python -m venv ~/environments/hiv_workflow
    2. Activate the virtual environment:

      • Bash in Windows:

        source ~/environments/hiv_workflow/Scripts/activate
      • In Linux:

        source ~/environments/hiv_workflow/bin/activate
    3. Ensure pip is up-to-date (the default version has major issues):

      python -m pip install pip --upgrade
  2. Obtain and install hiv_workflow:

    git clone
    cd hiv_workflow
    python -m pip install --upgrade pip
    pip install . -r requirements.txt
  3. Verify the installation:

    cd examples/rakai-optimtool
    python -m hiv_workflow.scripts.available_parameters -m baseline

Sample workflow

The examples/rakai-optimtool/ file contains example commands that highlight a simple but typical workflow linking the scripts contained in hiv_workflow. These commands are expected to be run with your working directory being examples/rakai-optimtool (the root of the example project).

Known issues

  • If running pip install results on this error: ‘ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE’

    • Try running adding --no-cache-dir as part of your pip install command. i.e. pip install -e . -r requirements.txt --no-cache-dir

    • Issue 26

  • If running pip install results on dependencies issues:

    • Try updating pip: python -m pip install --upgrade pip

  • If when running one of the demo samples you get a “hiv_workflow not found” or even “Python not found”:

    • Try activating your virtual environment as shown above