CASMIM — Cellular Automata with Social Mirror Identities Model

A Python 3 implementation of the CASMIM model for simulating SARS transmission dynamics and evaluating public health policy interventions on a small-world epidemiological network.

Overview

In the early 2000s, SARS outbreaks in cities such as Singapore, Taipei, and Toronto demonstrated how daily-contact social networks and long-distance movement could rapidly amplify disease spread. CASMIM addresses this by combining cellular automata with a "social mirror identity" mechanism: each person owns multiple agents (mirrors) scattered across a 500 × 500 torus lattice, representing the different social spheres (home, workplace, hospital, etc.) that a single individual participates in daily.

The model integrates:

• Cellular Automata on a 2D torus lattice (500 × 500) for spatial agent interactions
• Social Mirror Identities to represent daily-contact social networks and long-distance movement
• SEIR+D compartmental model (Susceptible → Exposed → Infective → Recovered → Immune → Susceptible, with Death branch)
• 8 public health policies (mask wearing, temperature screening, hospitalization, home quarantine, contact reduction, visit restriction, vaccination, medical policy)
• Contact tracing via BFS-based algorithms with level-1 and level-2 quarantine
• Super-spreader modeling and age-stratified mortality

The model was originally developed in Borland C++ Builder (2003-2005) and has been ported to Python 3 with a PySide6 (Qt) GUI.

Features

• Interactive lattice visualization — 500 × 500 macro lattice and 100 × 100 micro lattice with click-to-navigate
• Real-time SEIR+D display — Color-coded agents (sky-blue = susceptible/exposed/immune, red = infective, silver = recovered, black = died)
• 6 chart types — Accumulation, incidence, notification, infection, accumulative quarantine, daily quarantine
• 8 configurable policies — Each policy can be toggled on/off during simulation with adjustable effect and coverage rates
• Dynamic policy activation — Policies can be enabled or disabled mid-simulation to study intervention timing
• Super-spreader modeling — Configurable probability for super-spreader designation
• Excel output — Simulation statistics exported via openpyxl with 4 output sheets (cumulative counts, daily deltas, action log, running averages)
• Numba JIT acceleration — Core simulation loop compiled to native code via Numba @njit, achieving ~8x speedup over pure Python; fallback to Python path via CASMIM_NO_NUMBA=1
• NumPy-accelerated — Structure-of-Arrays (SoA) data layout with vectorized operations for population-level computations

Installation

git clone https://github.com/canslab1/CASMIM.git
cd CASMIM
pip install -r requirements.txt

Dependencies

Usage

python main.py

This launches the GUI application with:

• Left panel: Disease parameters (Disease tab), population parameters (World tab), policy controls (Policy tab) with checkboxes and effect/coverage sliders
• Center panel: Macro tab (500 × 500 lattice) with real-time color-coded agent states; click to navigate the Micro tab (100 × 100 magnified view)
• Right panel: 6 pyqtgraph chart widgets displaying accumulation, incidence, notification, infection, and quarantine statistics
• Bottom panel: 9-panel status bar showing coordinates, agent state, identity, current day, and mortality summary

Controls

Environment Variables

Disease Parameters

Policy Parameters

Algorithm Overview

CASMIM simulates epidemic dynamics through a daily step cycle:

1. Population initialization — 100,000 individuals are created with age-stratified demographics (young/prime/old). Each person is assigned multiple "social mirror" agents distributed across the 500 × 500 torus lattice using a Gaussian quota distribution, representing their presence in different social spheres.

2. Daily traversal — Each day, all individuals are traversed in a randomly chosen direction (forward or reverse) to eliminate ordering bias. For each person, the engine executes:

3. State transition — The SEIR+D state machine advances:

4. Susceptible: Agents interact with Moore-neighborhood neighbors; transmission occurs with probability transmission_prob (modified by mask and medical policies).
5. Exposed: Counter increments; transitions to Infective after exposed_period days.
6. Infective: May be detected (with probability detect_rate) and isolated/quarantined. Transmission to neighbors continues. After infective_period days, transitions to Recovered or Died (age-stratified mortality).
7. Recovered: After recovered_period days, transitions to Immune.

8. Immune: After immune_period days, returns to Susceptible (unless permanently immunized by vaccine).

9. Contact tracing — When an infective individual is detected, BFS-based contact tracing identifies level-1 (direct contacts) and optionally level-2 (contacts of contacts) neighbors for home quarantine.

10. Super-spreader effect — Super-spreaders interact with all 8 Moore-neighborhood cells instead of a randomly selected single neighbor, dramatically increasing their transmission reach.

Implementation Notes

• Numba JIT compilation: The core simulation loop (change_society) and all subroutines (13 functions total) are compiled to native code via @nb.njit(cache=True), yielding ~8x speedup. BFS contact tracing uses pre-allocated arrays with head/tail pointers instead of Python deque.
• AoS → SoA conversion: The original C++ Array-of-Structures (society.people[i].state) is converted to Structure-of-Arrays (people_state[i]) using NumPy for cache-friendly vectorized operations.
• Contact tracing: Changed from recursive DFS (C++) to iterative BFS (Python/Numba) to avoid stack overflow on large populations.
• Policy vectorization: All policy applications (except vaccination) use np.random.random(N) < available for O(1) per-person Bernoulli trials instead of scalar loops.
• Incremental rendering: A dirty-set mechanism (dirty_pids) tracks only agents whose state changed each day, avoiding full-lattice repaints.
• Chart rendering: Migrated from VCL TChart (C++) to pyqtgraph (Python) for real-time chart updates.

Project Structure

CASMIM/
├── main.py                      # Entry point
├── requirements.txt             # Python dependencies
├── pyproject.toml               # Package metadata (PEP 621)
├── CITATION.cff                 # Citation metadata
├── CHANGELOG.md                 # Version history
├── CONTRIBUTING.md              # Contribution guidelines
├── LICENSE                      # MIT License
├── index.html                   # GitHub Pages landing page
├── 404.html                     # Custom 404 error page
├── sitemap.xml                  # XML sitemap for search engines
├── robots.txt                   # Crawler directives
├── llms.txt                     # AI-readable project summary
└── sars_sim/
    ├── __init__.py
    ├── models.py                # Data structures (StateEnum, SimulationParams, SimulationData)
    ├── world.py                 # Lattice management, population initialization, agent distribution
    ├── engine.py                # Core SEIR+D simulation engine, transmission and state transition logic
    ├── engine_numba.py          # Numba JIT-compiled kernels (13 @njit functions, ~8x speedup)
    ├── policies.py              # 8 public health policy implementations (vectorized)
    ├── statistics.py            # Statistics tracking, Excel output (4 sheets)
    └── gui/
        ├── __init__.py
        ├── main_window.py       # Main application window (PySide6)
        ├── lattice_view.py      # Macro/micro lattice visualization (QImage ARGB32)
        ├── charts.py            # 6 pyqtgraph chart widgets
        ├── controls.py          # Parameter, disease, and policy control panels
        └── status_bar.py        # 9-panel status bar

Authors

• Chung-Yuan Huang (黃崇源) — Department of Computer Science and Information Engineering, Chang Gung University, Taiwan (gscott@mail.cgu.edu.tw)
• Chuen-Tsai Sun — Department of Computer Science, National Yang Ming Chiao Tung University, Taiwan
• Ji-Lung Hsieh — Graduate Institute of Journalism, National Taiwan University, Taiwan
• Yi-Ming Arthur Chen — Department of Information Management, National Central University, Taiwan
• Holin Lin — Department of Sociology, National Taiwan University, Taiwan

Citation

If you use this software in your research, please cite:

Huang, C.-Y., Sun, C.-T., Hsieh, J.-L., Chen, Y.-M. A., & Lin, H. (2005). A Novel Small-World Model: Using Social Mirror Identities for Epidemic Simulations. SIMULATION, 81(10), 671-699. https://doi.org/10.1177/0037549705061519

See CITATION.cff for machine-readable citation metadata.

References

1. Huang, C.-Y., Sun, C.-T., Hsieh, J.-L., & Lin, H. (2004). Simulating SARS: Small-World Epidemiological Modeling and Public Health Policy Assessments. Journal of Artificial Societies and Social Simulation, 7(4), 2. http://jasss.soc.surrey.ac.uk/7/4/2.html

2. Huang, C.-Y., Sun, C.-T., Hsieh, J.-L., Chen, Y.-M. A., & Lin, H. (2005). A Novel Small-World Model: Using Social Mirror Identities for Epidemic Simulations. SIMULATION, 81(10), 671-699. https://doi.org/10.1177/0037549705061519

License

This project is licensed under the MIT License. See LICENSE for details.