Simpocalypse Manual

To get started with the simulation right away:

1. Open the Simpocalypse application.
2. Click on one of the green circles in the grid on the right-hand side of the window to infect somebody.
3. Click the "Run" button!

For more information on how to create your own disease, read on!

Introduction

The Simpocalypse user interface is broken down into three regions: parameter controls, real-time charts and graphs, and the population grid. Below is an explanation of each of the parameter controls. Once the simulation is running, each of these explanations is available within the application by clicking on the question mark buttons you'll see next to most controls.

Parameter Controls

Parameter controls are found in the upper left-hand corner of the window, and are used to change the conditions that apply to the initial population, the properties of the disease, and any societal measures that are being taken to suppress the disease.

We'll talk about the parameter controls first. There are three sets of parameter controls, the "Simple" set, with only a few sliders, the "Complete" one, which gives you control over all of the parameters that affect the initial conditions and the disease, and the "Societal Controls" set, which lets you control the measures taken to suppress the disease, like face masks and quarantines. The rest of this manual will discuss the "Complete" and "Societal Controls" sets, both because the Simple set has more descriptive labels (because there's more room) and because every control in the "Simple" set is also in the "Complete" set. Regardless of which set of controls you're looking at, you can name your disease, save it, load a new disease, or save or load the entire simulation with the controls on the top-left edge of the window.

Saving and Loading

Saving a disease, with the "Save disease..." button, lets you keep a copy of all of your disease parameters, so you can open them later with (of course) the "Open disease..." button. The disease files Simpocalypse saves are just text files, so you can even change them with a text editor like Notepad or TextEdit if you want. You can also save or load the entire simulation, with the "Save sim..." and "Load sim..." buttons. This will save both the disease parameters (the same ones that would go in a disease file) and all of the current simulation's history in a SQLite database file. You can open these files back up in Simpocalypse to look at your simulation's history again, or you can analyze the data with external tools, like SQLiteBrowser, the SQLite command-line shell, or any other program that can understand SQLite databases.

Complete

Many of the parameters in the "Complete" tab represent the odds of something happening, that is, probabilities. There are two modes you can display these in: either as probabilities, which usually range between zero and one, or as percentages, which usually range between zero and 100. A percentage chance is just a probability multiplied by 100, so the parameters still mean the same thing in the simulation, whether you choose to display them as probabilities or percentage chances. The parameters themselves:

Initial Population:

This slider can be used to adjust the population numbers, from 1 to 2,500 people in the downloadable versions and 1 to 400 people in the online version.

Average Health:

The "Average health" slider represents the overall average health of the population. For example, the United States of America has above-average health in comparison to the rest of the world, due to its highly sophisticated and accessible health care system. Unfortunately, many people in the United States have unhealthy eating and exercise habits, so the overall health in this country is not as high as it should be. Some other developed countries tend to have better diets and healthier people. In contrast, most developing countries have poor overall health, mainly due to poor nutrition and inaccessible health care.

In Simpocalypse, health affects the chances that somebody will develop symptoms once infected with a disease (look at the "Symptom Rate" slider for more information about this process). Overall health can determine how effective your generalized immune response is in fighting off a pathogen, and it can even help avoid some kinds of symptoms altogether. The SARS-CoV-2 coronavirus, for example, seems to be strongly affected by the patient's overall health: people who are young and healthy get serious symptoms far less often than older people, or people with serious health problems like heart disease.

Birth Rate

The "Birth rate" slider controls the birth rate of the population: the rate at which new people are added to the simulation.

Death Rate

The "Death rate" slider controls how quickly the people in the simulation will die of natural causes.

Infectivity

The "Infectivity" slider controls how contagious the disease is. Specifically, infectivity is the chance that, if an uninfected person spends a day next to an infected one, that the uninfected person will get the disease as an asymptomatic carrier.

Recovery Chance

The "Recovery chance" slider controls how likely people are to recover from the disease. Technically, it controls the chance each day that a sick person will recover. If you set this at 0.25 (or 25%), most people will recover after eight days. If you set this to zero, nobody will ever recover from the disease. (Many real pathogens, like HIV, Mycobacterium tuberculosis, and the viruses that cause cold sores, never really go away, so there are real-life diseases that would match a 0% recovery chance in Simpocalypse.) If you set this to 1 (or 100%), nobody will ever be infected longer than one day.

Lethality

The "Lethality" slider controls how deadly the virus is; specifically, it determines the chance that a person with symptoms will die each day the infection continues. If you set this much higher than a few percent, the disease will be very deadly. 0.25 (or 25%) might not sound like very much, for example, but usually very few patients will survive a disease with a lethality of 0.25 in Simpocalypse, unless the recovery chance is quite high. If you set this to zero, nobody will ever die of the disease. (That might not be a very realistic disease: people with very rare immune disorders, or with AIDS, can die of things like the common cold.) If you set it to 1 (or 100%), everybody will die immediately upon developing symptoms. (This might be a reasonable way to model something like rabies.)

Symptom Rate

The "Symptom rate" slider controls how long the incubation period is. When people are first infected, they will be asymptomatic carriers. This means they won't have any chance of dying, yet, but they can still spread the disease to others. They might recover before they ever get symptoms, or they might develop symptoms. This slider controls the chance each day that an asymptomatic carrier will develop symptoms.

Convalescent Immunity

The "Convalescent immunity" ("Conv. imm") slider controls how much immunity people get after they recover from the disease. This represents the way people's specific immune responses work in real life: the body produces antibodies targeted at the virus, bacterium, or other pathogen that caused the disease, so that if it ever attacks again, it can be wiped out quickly, before it has a chance to cause trouble. This doesn't always work, though, and some diseases are easier to fight off than others. In Simpocalypse, immunity works by changing the chances that someone can be infected. If the disease has an infectivity of 1, and someone has 0.4 immunity, the probability of infection will only be 0.6. If immunity is ever greater than infectivity, this will prevent infection entirely until the person's immunity decays.

Immune Decay Chance

The "Immune decay chance" ("Imm. dec. ch.") slider controls the chance each day that a person with immunity will lose some of it. In real life, some diseases cause permanent immunity (chickenpox works this way), but others require repeated exposure to maintain immunity. (This is why you need "booster shots" every few years for some vaccines, but you only need to be given others once or twice when you're little.) In real life, this often works more by the pathogen mutating to escape existing immune defenses (like the flu, or the different rhinoviruses and coronaviruses that cause the common cold) than by your immunity to the old pathogen actually decaying, but that doesn't matter for our simulation: either way, the patient is less immune to the disease. If you set this to zero, nobody's immunity will ever decay.

Immune Decay Amount

The "Immune decay amount" ("Imm. dec. amt.") slider controls how much immunity will decrease each time someone loses immunity because of the decay rate.

Bodies Last

The "Bodies last" slider controls how long it takes before a dead body will be removed from the board. Unfortunately, many diseases can still be passed on after the patient dies. This slider is significant mainly due to cultural reasons. For example, in many West African cultures, dead bodies are handled much more than in other places during burial ceremonies. This sometimes causes problems, because if somebody dies of an infectious disease, the disease could spread to healthy people who participate in the burial ceremony. Outbreaks of Ebola, such as the 2014 West African epidemic, have been made worse in this way. The simulated people in Simpocalypse aren't smart enough to conduct burial ceremonies or funerals or anything, but moving this slider farther to the right is a decent simulation of this kind of problem. It also can be seen as controlling how long the pathogen is still contagious after the patient dies.

Societal Controls

The "Societal Measures" tab contains parameters that change how people behave. These are meant to be used to model interventions to suppress the disease. The controls for vaccinations are here as well.

Movement Rules

You can use the special "Movement rules" group to change the way people move. There are two modes you can put the simulation in. The first, "Crowding", tries to simulate how people normally behave, and will cause the people in the simulation to congregate in groups. Unfortunately, this means they'll spend a lot of time next to each other, spreading the disease.

One of the oldest methods of controlling epidemics is to limit contact between people, hoping that this will stop infected people from passing the disease on to others. This is what the "Social distancing" mode tries to simulate. When this is selected, people will try their best not to stand next to other people.

Finally, there is a "Level" slider to control how hard people try to obey the movement rules. Positioning it farther to the right will make the crowds more tightly-packed, or make people follow social distancing rules more carefully. Positioning it farther to the left will make people move around more randomly, mostly ignoring others.

Vaccines

The "Vaccine" group allows you to configure vaccination campaigns in the simulation. You can configure the vaccine with its sliders, and give the vaccine to the people in the simulation at any time by clicking on the "Vaccinate now!" button.

The "Vacc. rate" slider allows you to set the percentage of healthy people in the simulation who will get vaccinated. If it is positioned all the way to the left, nobody will be vaccinated when you click on the "Vaccinate now!" button, and if it is positioned all the way to the right, everyone who isn't already infected will be vaccinated. Infected people never get vaccinated, because their immune systems are already busy fighting off the real disease. Most vaccines work by trying to trick the immune system into preparing to fight off the disease by "fighting off" the vaccine, which is engineered to "look" like the real disease to the immune system. If it's already fighting off the real disease, the vaccine usually can't help, and might even cause trouble by making the immune system overreact, or distracting it from the actual infection. (Some diseases, like the 1918 "Spanish flu" or COVID-19, are thought to kill many of their victims by causing the immune system to overreact and damage the patient's tissue!)

The "Vacc. effectiveness" slider controls how much immunity, on average, someone who gets the vaccine will gain. Not everybody will get the same amount.

Quarantine

The "Quarantine rules" group controls whether and how people are put into quarantine. There are two quarantine modes available, and two slider controls. The "Symptomatic patients" mode quarantines people only when they have a symptomatic infection, and the "Everybody" mode allows anyone to enter quarantine. (This can be used to simulate harsh "lockdowns" or shelter-in-place orders.)

The "Observance" slider controls the probability that someone's who's supposed to be quarantined really will be. When the simulation is in "Symptomatic patients" mode, Observance is the probability that a symptomatic person will be quarantined every day. When the simulation is in "Everybody" mode, Observance is the probability that someone who's not quarantined will be quarantined every day, and also the probability that someone who's already quarantined has of staying quarantined. (Therefore, in "Everybody" mode, this will also be roughly the proportion of people who are quarantined at any given time.)

The "Efficacy" slider controls how well quarantines work at preventing infection. In real life, no quarantine is ever perfect. People still have to eat, or be taken care of in the hospital, so there's almost always a small chance of infection despite the quarantine. Worse still, in real life, people might not observe a "self-quarantine" very carefully. This is the probability that the quarantine will prevent someone who comes into contact with the quarantined person from transmitting the disease.

Masks

The "Mask rules" group allows you to decide whether people wear masks, and how well they work at stopping the disease from spreading. These settings only apply when the disease is transmitted by respiratory droplets. Just like for quarantines, you can pick whether to put masks on everybody, or only sick people.

"Prevalence" is the probability each day that someone who's not wearing a mask will start, and the probability each day that someone who's already wearing a mask will stay masked. Therefore, this will also be the rough proportion of the population that's masked at any given time.

"Containment" controls how well masks work for keeping an infected mask-wearer's germs from infecting other people. This is subtracted from the disease's Infectivity before the mask-wearer tries to infect anyone, just like immunity, so a Containment value of 1 means the mask is totally effective at keeping the mask-wearer's germs in, and 0 means it can't stop germs from getting out at all.

"Exclusion", on the other hand, controls how well masks work for keeping other people's germs from infecting a healthy mask wearer; it's subtracted from Infectivity before someone tries to infect the mask-wearer, just like Containment and immunity. Wearing a mask with Exclusion set to 1 prevents infection entirely, and wearing one with Exclusion set to 0 doesn't keep other people's germs out at all.

Statistics

The statistics view in the lower left of the window is divided into four tabs: the "History Graph", the "History Table", the "People" table, and the "Parameter Changes" table. Below all three tables, you'll find buttons both to save the data inside them either as a CSV (Comma-Separated Values) file, which can be opened with most spreadsheet programs, and to save the whole simulation a SQLite database file, just like the "Save sim..." button on the top of the window does.

The History Graph

The graph only represents totals: the total population, the number of healthy people and infected people, the cumulative death total, and the average immunity level. (It's easy to see how fast these things change on a graph, because that controls how steep the slopes are.) The scale for the first four lines is on the left-hand side, and the scale for the blue immunity line is on the right-hand side. (Days are along the bottom.) You can click and drag inside the graph (while the simulation isn't running) to travel backwards and forwards in time, to see how your simulation has progressed. Below the graph, you'll find a button to save an exact copy of the current graph display in EPS (Encapsulated PostScript) format. macOS has built-in support for viewing Encapsulated PostScript files, and many PDF-viewing applications for Linux understand it, but Windows users will probably need to install a drawing program that supports Encapsulated PostScript to view saved graphs. Scribus and Inkscape are two free and open-source programs that work well for this, and many of Adobe's products support EPS files.

The History Table

Each row of the History table represents one day of the simulation, and records, from left to right, the number of days since it started, the number of people alive in the simulation, the number of healthy people, the number of infected people (including asymptomatic carriers), the number of total deaths since the simulation began, the number of births, the number of people who recovered from the disease, the number of people who were infected, the number of people who died, and the average level of immunity (a 1.0 or higher is total immunity).

The People Table

The People table shows extra details about the people in the simulation. Each row represents one person, and shows, from left to right, that person's unique ID number, the person's X and Y coordinates on the grid (the origin, (0, 0), is at the upper-left corner), whether the person's alive, whether the person's infected, the person's current immunity, and the person's overall health.

The Parameter Changes Table

The Parameter Changes table is only useful when you're travelling in time, by clicking in the graph or using the Day slider (we'll get to that a bit further down). If you change any simulation parameters while the simulation is running, Simpocalypse will remember them, so you can see exactly when you made those changes and how they affected the simulation. When you travel back in time to the exact day on which you made the changes, you can see exactly what you changed in this table.

The Simulation Grid

Most of the right-hand portion of the window is taken up by the simulation board itself, but there are also some controls to start and stop the simulation, change the board's size, and control how fast the simulation runs.

The Top Row

From left to right, along the top edge, you should see the "Run" button, to start the simulation, the "Pause" button, to temporarily stop it, the "Population" field, which shows how many people are alive in the simulation, the Infection Fatality Rate ("IFR") field, which shows the current case fatality rate (the number of deaths with the disease divided by the total number of cases), the "Reset" button, which clears everything away and starts the simulation over again, and the "Step" button, which runs just one day's worth of the simulation each time you click on it. You probably want to infect someone down on the grid, by clicking on one of the green circles, before starting the simulation.

Infection Fatality Rate

The Infection Fatality Rate field deserves some extra attention. In Simpocalypse, the IFR is calculated by counting the number of deaths the disease has caused and dividing it by the total number of infections that have happened during the simulation's whole history. This means that the same person can be infected multiple times, and this will count as multiple cases. In real life, it can be harder to calculate reliable Infection Fatality Rate numbers, because (unlike in Simpocalypse) the total number of people who have the disease can be hard to figure out. For example, at the time of writing, in May 2020, the "real" Infection Fatality Rate of COVID-19 (as it would be shown in Simpocalypse) is not known precisely. Estimates vary wildly, from as low as 0.1% to as high as 10%. (That's two whole orders of magnitude!) This is because it is believed that many infections go undetected. We often work with a number called "Case Fatality Rate" in real life, but this isn't the same thing because it only includes people who are conclusively diagnosed with the disease. The real IFR, like Simpocalypse calculates, would need to count everyone who is ever infected.

Time Travel

Next, just below the control row, you'll see the "Day" field, which shows how far the simulation has progressed, and the time travel slider beside it. Normally, while the simulation is running, this slider is positioned all the way to the right. If you pause the simulation and drag it around, though, or edit the "Day" field, you can go back in time to see how your epidemic has progressed, just like clicking inside the graph. If you restart the simulation while looking at a previous moment in time, the simulation will continue from that moment, and all subsequent history will be erased. This lets you see how small changes might have affected the original simulation.

The Board

The simulation grid itself shows you where all of your people are at any given time, and what state of health they're in. Healthy people with no immunity are shown as green circles. When you first start Simpocalypse, these are the only kind of people you'll have on your grid. You can infect someone by clicking on one of the green circles. There are two states of infection that are possible. Asymptomatic carriers, who can spread the disease but aren't suffering from serious symptoms (yet), are shown as green circles with purple rings around the outside. Sick people, who are experiencing serious symptoms and are possibly at risk of dying, are shown as purple circles. People who have some level of immunity to the disease are shown by "filling up" a green circle with blue, to show the level of immunity. A circle that's all the way blue represents someone who's completely immune to the disease, while a circle that's only half full represents someone with about 50% immunity (half the chance of catching the disease compared to someone with no immunity). Dead bodies are represented by dark grey circles, and the bodies of people who died with the disease are just as contagious as infected people who are still alive.

If you've turned the applicable settings on, some people might be quarantined or masked. Quarantined people will be locked inside black squares, and masked people will have white diamonds on top of them to represent the masks.

Resizing the Board

You might notice that there are sliders along the top and left sides of the simulation grid. These control how wide and how tall it is, respectively, by changing how big the squares on the grid are. If your computer is kind of slow, you might want to make the grid smaller, so it has an easier time keeping up with the simulation. If you have a very fast computer, you can make the grid even bigger, which should help make your data look a little smoother and more realistic.

Speed Control

Along the bottom edge of the grid, you'll see one more slider, called the "Time per cycle (ms)" slider. This controls how long it takes to run one day of the simulation in milliseconds. There are one thousand milliseconds in one second, so a time per cycle of 100 means there will be ten days of the simulation per second. You can drag this all the way down to one millisecond if you want, but unless your computer is very fast, it probably won't be able to process a whole day's worth of simulation in one millisecond, unless you make the grid very small, and the simulation will just get bogged down.