Pandemic Surrogate Model F.A.Q.
We are trying to make an agent model for pandemics as easy to wield as a simple one (like CIR). You can help.
Is there an executable for windows (or other OS)?
Not yet. By all means write one using the source code. That would help bring a lot more people into the fold.

However docker is a good option, as per the instructions.

How do I run it without plots?
This script.
How do I run it many times
This script runs six copies, without plots.
I ran too many copies, how do I kill them all?
pkill -f pandemic

(If only that worked in the real world)

Why do you need my help?
Here's an example simulation.

The movie is sped up 30x. Now imagine spending hours on every point in this cube. Now imagine if the cube was actually a hypercube with ten dimensions. You get the idea.

Is the code open source?
See Github
Why not use a model like CIR applied to a population, that is faster to compute?
You may be interested in this working paper showing how a simplified version of this simulation approximately satisfies a compartmental model. But that doesn't include commuting.

We are trying to add something to the discussion by providing a model that eschews the notion of a single representative person who lives everywhere at once. There are dynamics at play in our model, such as exhaustion of regular acquaintances, that may shed light on some key questions left unanswered by other modeling approaches.

See this article for a longer answer.

What is the model?
People follow regime switching Ornstein-Uhlenbeck processes on the plane. See the article.
Is there a simple way to visualize the model?
Here's an example with only fifty people.

How are results stored and retrieved?
Each run uses a different choice of parameters. For example the social distance, the fraction of people who commute and the rate of testing might be varied.
  1. When the simulation ends, it makes a call to the API to store the results and parameters used.
  2. When storing, the parameters are converted from three-dimensional vectors into a string that encodes this information using a space filling curve. See this explanation of how the database key is created.
Can I see the results?
Yes anyone can retrieve simulation results
  1. At URLs like
  2. Using the Python pandemic package and examples of surrogate use
  3. Using the API directly.
How do I read the database key?
A key above reads "day 0008" and ... well the rest is harder to see because the key traces out a space filling curve in the free parameters. You'll want to use the inversion functions in pandemic/
Why use wacky z-curves as database keys?
Yeah maybe its a little whacky. But one advantage is O(1) retrieval when looking for simulations with similar parameters.
What kind of metrics are stored?
Population statistics like this refering to STATE_DESCRIPTIONS here. We will likely append to this list.
What are the model parameters?
Also at pandemic/ on Github.
Why not rewrite it in C++ or Julia?
It might help, although the bottlenecks may be set membership and geohashing, both of which are already in C++. We welcome optimization pull requests.
Can I use the results as part of my own calibration?
You bet. We'll make this easier over time, with different ways to index the data.
Is there a simpler way to download community simulation results, like CSV or pandas?
Good idea. We may script something up.
What if the script doesn't work?
You can use the Python pandemic package directly. Just pip install and
Are you publishing projections?
If there is no code here then the answer is not yet. But you can use the database or the code in any way you wish, such as calibrating to historical metrics from actual cities.
Why not store simulations keyed by metrics?
Not a bad idea. So much to do, so little time.
How do I reproduce the simulations in the article?
See scripts on Github.
How is this licensed?
Apache, MIT and BSD permissable open source licenses.