Overview

LASER (Lightweight Agent Spatial modeling for ERadication) is a framework for building agent-based infectious disease models with an emphasis on spatial modeling and efficient computation at scale.

laser-generic builds on top of laser-core, offering a set of ready-to-use, generic disease model components (e.g., SI, SIS, SIR dynamics, births, deaths, vaccination).

• Free software: MIT license

Getting Started and Documentation

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.

Installation

We recommend using uv for faster, more reliable installs:

uv pip install laser-generic

Alternatively, you can use regular pip:

pip install laser-generic

To install the latest in-development version:

pip install https://github.com/laser-core/laser-generic/archive/main.zip

Using laser-generic

laser-generic can be used in your code after importing it into your project:

import laser.generic as lg

print(lg.__version__)

Development

1. clone the laser-generic repository with

git clone https://github.com/laser-base/laser-generic.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-generic directoryh with

cd laser-generic

5. create a virtual environment for development with

uv venv .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.generic 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.generic.

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.generic until the package is rebuilt and reinstalled. However this process mirrors using laser.generic 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-generic 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.

Executed tutorial notebooks

Read the rendered notebooks on the docs site: laser.idmod.org/laser-generic/tutorials/.

That's the freshly-executed, browsable, hosted-by-GitHub-Pages view — no download, no local Jupyter setup. Every tutorial notebook has its own page. The docs site is auto-rebuilt on every push to main by the MkDocs Deploy workflow, which downloads the latest successful executed_nbs artifact from Execute Notebooks and overlays those CI-executed notebook outputs onto the docs/ tree before mkdocs build.

Notebook execution (~25 min on a cache miss) is expensive, so Execute Notebooks only runs when its declared execution inputs change — notebooks, library source, Python dependencies, or the CI harness that runs them (executor script, Makefile execution defaults, workflow file). See the workflow's paths filter for the exact list. Pushes that don't touch any of those reuse the most recently produced artifact and the site rebuild finishes in ~2 min. The executed_nbs artifact also carries a manifest.json recording provenance (commit SHA, source hash, Python version) for downstream traceability, and is separately consumed by Build Combined Doc to sync the RAG corpus into laser-mcp.

If you need the raw .ipynb files (with outputs) that were executed against a specific commit — e.g. to reproduce a doc-quality regression, or to compare corpora across time — see docs/tutorials/notebooks/README.md for the artifact-download procedure. For regular browsing, use the docs site.