Status

Getting Started

We recommend using the LASER documentation to familiarize yourself with the LASER disease modeling framework. However, the instructions below may be sufficient for those who want to jump right in.

Standalone Installation

laser-core can be installed standalone with pip:

python3 -m pip install laser-core

or with uv (recommended):

uv pip install laser-core

However, it may be more instructive to install one of the disease packages built on laser-core to understand what laser-core provides and what is expected to be in a disease model. See laser-generic.

Using laser-core

laser-core can be used in your code after importing it in your project (note that while the Python package is laser-core, one imports laser.core):

import laser.core as lc

print(lc.__version__)

Documentation

Documentation can be found here.

Development

1. clone the laser-core repository with

git clone https://github.com/laser-base/laser-core.git

2. install uv in your system [Python], i.e. before creating and activating a virtual environment

3. install tox as a tool in uv with the tox-uv plugin with

uv tool install tox --with tox-uv

4. change to the laser-core directory with

cd laser-core

5. create a virtual environment for development with

uv venv

6. activate the virtual environment with

Mac or Linux:

source .venv/bin/activate

Windows:

.venv\bin\Activate

Building Code in Development

Option 1: build "live" code - Python scripts using laser.core will import the code directly from the repository clone. Edits to the source code will take effect upon restarting the Python environment and importing laser.core.

with pip:

pip install -e ".[dev]"

with uv:

uv pip install -e ".[dev]"

Option 2: build an installable package - this package must be installed into an environment to be used and changes to the source code on disk will not be picked up by consumers of laser.core until the package is rebuilt and reinstalled. However this process mirrors using laser.core as a dependency better than the "live code" option above.

Option 2A: build with pip

• install the build package: python3 -m pip install build
• build the laser-core Python packge: python3 -m build
• find the wheel file, .whl, in the dist directory: ls -l dist

Option 2B: build with uv

• uv build
• find the wheel file, .whl, in the dist directory: ls -l dist

Running Tests

Now you can run tests in the tests directory or run the entire check+docs+test suite with tox. Running tox will run several consistency checks, build documentation, run tests against the supported versions of Python, and create a code coverage report based on the test suite. Note that the first run of tox may take a few minutes (~5). Subsequent runs should be quicker depending on the speed of your machine and the test suite (~2 minutes). You can use tox to run tests against a single version of Python with, for example, tox -e py312.

Problem Space for Spatial Disease Modeling

The problem is inherently an issue of heterogeneity. Spatial decomposition is the easiest consideration, but not sufficient - a model of N "independent" but identical communities is generally not useful.

Spatial connectivity and the associated latencies in transmission address one dimension of heterogeneity: how "close" is a given community to a potential source of imported contagion (exogenous to the model "world", locally endogenous, e.g., an adjacent community, endogenous but at a remove - rare transmission or multi-stop chain of transmission).

Community size in a spatial model is also a consideration - what is the configuration and connectivity of sub-CCS nodes to nodes at or above CCS for the given disease?

We need configurable characteristics of the individual communities which can vary, along with their interconnectedness, to capture additional heterogeneity.

What is the modeling of the individual communities? "Light-Agent" seems to limit us to an ABM, but we should consider cohorts of epidemiologically similar populations (polio >5, HIV <15, TB latents, etc.) as well as stochastic compartmental models (XLA - eXtremely Light Agents).

• Are the individual communities well-mixed or should we also provide for explicit networks at the local level?

Technology

• Python
• high performance computing:
  • NumPy
  • NUMBA
  • CuPy
  • PyCUDA
  • mlx
• native code
  • C++ (somewhat awkward interop with Python, but potentially accessible from other technologies, e.g., R)
  • Rust (PyO3 is quite nice, but requires getting up to speed on Rust 😳)
• compute requirements:
  • laptop 2010+? (might inform SIMD capabilities)
  • GPU (CUDA) enabled machine laptop/desktop/cloud
  • single core/multi-core
  • largest scenarios?
• visualization
  • cross-platform
  • real-time
• existing file formats for input data
• existing file formats for output data (GeoTIFF? - works with ArcGIS?)

Other

• community builder tool for given total population and community size distribution
• network builder given a set of communities (gravity, radiation, other algorithms in existing libraries/packages)
• independent populations w/in a community, e.g., mosquitoes or dogs along with humans
• independent or co-transmission, i.e. multiple "diseases"
• models need to be connected with real-world scenarios, not [just] hypothetical explorations

Notes

• "light" : How light is "light"?
• "agent" : Cohorts? Stochastic compartmental?
• "spatial" : How good are the individual community models? Good enough for non-spatial questions?
• dynamic properties (e.g. GPU flu simulation)
• ¿state machines?

Superficial simplicity isn’t the goal of design. Some things are, by nature, complex. In such cases, you should aim for clarity rather than “simplicity.” Users will be better served if you strive to make complex systems more understandable and learnable than simply simple.