nexussim 0.1.0

A framework for agent-based modeling of dynamic spatial processes.

NexusSim

NexusSim is a flexible and powerful Python framework for agent-based modeling of dynamic spatial processes. Designed for modularity and scientific reproducibility, it allows users to simulate complex emergent phenomena on customizable landscapes - from disease epidemics and invasive species to wildlife spread and information diffusion.

The framework is built on a decoupled, file-based architecture: the simulation engine produces a series of GeoTIFF raster files, which are then consumed by a comprehensive analysis toolbox to generate plots, animations, and statistics.

Key Features

* Agent-Centric Simulation: Models complex behaviors by         focusing on individual agent states and interactions (nexussim.core).

* Raster-Based I/O: Works seamlessley with standard geospatial data formats for defining landscapes and initial conditions.
* Comprehensive Analysis Suite: A rich set of tools (nexussim.analysis) to generate epidemic curves, animations, persistence "hotspot" maps, and calculate the rate of spread.
* Reproducibility First: The file-based output creates a permanent, reproducible record of every simulation run.
* Scalable: By not holding the entire simulation history in memory, NexusSim can hanlde longer and larger simulations.

Installation

NexusSim is available on PyPI. Install it using pip:

pip install nexussim

To install the latest development version directly from GitHub:

pip install git+https://github.com/mrmarcelino/nexussim.git

Quickstart: From Simulation to Analysis

This example demonstrates the complete NexusSim workflow. It will:

1. Create dummy input rasters for a landscape and initial infections.
2. Run a 50-step simulation, saving the output to a results/ directory.
3. Use the analysis module to generate an epidemic curve plot and an animated GIF from the results.

import os import shutil import numpy as np import rasterio import matplotlib.pyplot as plt import matplotlib.image as mpimg

nexussim/

|- init.py

|- core.py

|- analysis.py

from nexussim.core import DiseaseModel import nexussim.analysis as nxs_analysis

Helper function to create dummy input data

def create_dummy_raster(path, width, height, data, crs='EPSG:3857'): """ Creates a simple GeoTIFF file for demonstration purposes. """ profile ={ 'driver': 'GTiff', 'dtype': 'float32', 'width': width, 'height': height, 'count': 1, 'crs': crs, 'transform': rasterio.transform.from_origin(0, height, 1, 1), 'nodata': -9999 } with rasterio.open(path, 'w', **profile) as dst: dst.write(data.astype(profile['dtype']), 1)

1. Setup Environment and Input Data

print("--- Setting up simulation environment ---")

Create directories for inputs, simulation outputs, and analysis outputs

os.makedirs('inputs', exist_ok=True) os.makedirs('sim_results', exist_ok=True) os.makedirs('analysis_outputs', exist_ok=True)

Define file paths

cost_path = 'inputs/cost.tif' initial_infection_path = 'inputs/initial_infection.tif' width, height = 100, 100

Create a uniform cost surface (all areas are equally passable)

cost_data = np.ones((height, width)) create_dummy_raster(cost_path, width, height, cost_data)

Create an initial infection raster with a small cluster of infected cells

initial_infection_data = np.zeros((height, width)) initial_infection_data[45:55, 45:55] = 1 create_dummy_raster(initial_infection_path, width, height, initial_infection_data) print(" > Dummy input rasters created.")

2. Run the Simulation

print("\n--- Running the NexusSim simulation ---") model_params = { 'cost_threshold': 1.0, # Agents can move anywhere 'spread_probability': 0.6, 'infection_duration': 5, 'recovery_time_min': 10, 'recovery_time_max': 20 }

Initialize the model

model = DiseaseModel(cost_path, initial_infection_path, model_params)

Run the simulation, which saves raster files to 'sim_results/'

model.run_simulation(time_steps=50, output_dir='sim_results')

3. Analyze the Results

print("\n--- Analyzing simulation results ---")

First, get the list of generated files

tif_files = nxs_analysis.get_simulation_files('sim_results')

if tif_files:

Generate and save an epidemic curve plot

curve_plot_path = 'analysis_outputs/epidemic_curve.png' nxs_analysis.generate_epidemic_curve(tif_files, curve_plot_path)

Create and save an animation

animation_path = 'analysis_outputs/animation.gif' nxs_analysis.create_animation(tif_files, animation_path, duration=0.1) print(" > Analysis complete. Outputs are in 'analysis_outputs'.")

4. Display one of the generated plots

print("\n--- Displaying generated epidemic curve ---") img = mpimg.imread(curve_plot_path) plt.figure(figsize=(10, 6)) plt.imshow(img) plt.axis('off') # Hide axes as the image already has them plt.show() else: print("Analysis skipped: No simulation files were found.")

The NexusSim Workflow

NexusSim is intentionally designed to separate the simulation from the analysis. This provides several key advantages for scientific modeling:

1. Reproducibility: The output rasters serve as a permanent, shareable record of the simulation.
2. Flexibility: You can run multiple analyses on a single simulation output without having to re-run the entire model.
3. Extensibility: It's easy to write your own custom analysis functions that operate on the standardized GeoTIFF outputs.

The standard workflow looks like this: [Input Rasters] → nexussim.core.DiseaseModel → [Output Rasters] → nexussim.analysis → [Plots, GIFs, & Stats]

Core Components

* nexussim.core: Contains the Agent and DiseaseModel classes. This is the heart of the simulation engine responsible for running the model and saving the state at each time step.
* nexussim.analysis: A toolbox of standalone functions that take a list of raster file paths as input and produce high-level outputs like plots, statistics, or animations.

Contributing

Contributions are welcome! If you have ideas for new features, analysis tools, or improvements, please open an issue or submit a pull request.

License

This project is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA 4.0) - see the LICENSE.md file for details.