pypmca Overview

The pypmca package is a general purpose framework that models connected populations using discrete-time difference equations. It was developed specifically to understand and characterize the CoViD-19 epidemic.

Populations and connectors

A model is built by connecting a set of population objects with connector objects. The connectors represent either a transfer that occurs immediately at the next time step or one which is delayed and distributed in time. Each population object retains a record of its size at each time step, and also maintains a list of future contributions, arising from delayed transfers from other populations. Calculations of population size are done either in terms of expectation values or simulated data, allowing the model to be used for both analysis and simulation.


Steady state solutions for these systems may develop. For viral epidemics these solutions are exponential growth or decline of population size. Systems perturbed by external influences, such as an instantaneous change to a growth parameter or a sudden change in the size of a group, may take time to relax to a new steady state solution. The relaxation time depends on the various time delay distributions in the system. To account for such perturbations, models can include transition objects.

In order to model both long term and short term behaviour correctly, realistic time delay distributions must be included. This is achieved in by using discrete-time difference equations, in contrast to the ordinary differential equations (ODEs) approach which form the foundation of the vast majority of epidemiological models. The ODE approach is limited by its capability to introduce realistic time delays and it offers no real benefit in modeling slowly evolving systems.


The object oriented design makes it possible to create or modify a connection network with little or no programming required, by using a suitable GUI. A separate package, ipypm provides a graphical user interface to that runs inside a jupyter notebook.

Heterogeneous systems

A single model describes a homogenous system. Heterogeneous systems can be modelled with an ensemble object, by combining several models, each representing a distinct group or category, along with a contact matrix the represents the engagement between the groups. Since an ensemble is a model object, tools that interact with a model can also be used to interact with an ensemble.


return to documentation home page