PACKAGE_README.md

COSMOS: Simplified Odor Simulation Package

COSMOS (Configurable Odor Simulation Model over Scalable Spaces) is a Python package for realistic odor time series simulation. This package provides a dramatically simplified interface for real-time odor concentration prediction across different environments.

🚀 Simple Interface

Before (16+ lines of complex setup):

import sys
sys.path.append('COSMOS')
from cosmos_tracking import CosmosFast
import numpy as np
import pandas as pd

dirname = 'COSMOS/data/hws/'
hmap_data = np.load(str(dirname) + "hmap.npz")
fdf = pd.read_hdf(str(dirname) + 'whiff.h5')
fdf_nowhiff = pd.read_hdf(str(dirname) + 'nowhiff.h5')

predictor = CosmosFast(
    fitted_p_heatmap=hmap_data['fitted_heatmap'],
    xedges=hmap_data['xedges'],
    yedges=hmap_data['yedges'],
    fdf=fdf,
    fdf_nowhiff=fdf_nowhiff
)

After (2 lines total):

import cosmos
model = cosmos.predictor('desert-hws')

📦 Installation & Setup

Step 1: Install Package

git clone https://github.com/arunavanag591/COSMOS.git
cd COSMOS
pip install -e .

Step 2: Download Data

Required: Download data from Dryad

1. Extract the downloaded data
2. Place the data folder in the COSMOS directory
3. For Rigolli model: Download additional files from Zenodo
4. Place Rigolli files (coordinates.mat, crosswind_v.mat, etc.) in data/rigolli/

Your directory should look like:

COSMOS/
├── cosmos/          # Package code  
├── data/           # Downloaded from Dryad
│   ├── hws/
│   ├── lws/
│   ├── forest/
│   └── rigolli/    # Additional files from Zenodo
└── README.md

Step 3: Use the Simplified Interface

import cosmos

# Create predictor - handles all data loading automatically
model = cosmos.predictor('desert-hws')

# Simulate odor at position (x=1.0, y=0.5)
concentration = model.step_update(1.0, 0.5)
print(f"Odor concentration: {concentration}")

That's it! No manual data downloads, no path management, no complex imports.

Real-time Simulation Example

import cosmos
import numpy as np

# Initialize model
model = cosmos.predictor('desert-hws')

# Create a trajectory  
dt = 0.005
time = np.arange(0, 10, dt)
x_pos = np.sin(time * 2 * np.pi * 0.5) + 2
y_pos = np.sin(time * 2 * np.pi * 4)

# Simulate odor experience
odors = []
for x, y in zip(x_pos, y_pos):
    concentration = model.step_update(x, y, dt)
    odors.append(concentration)

print(f"Simulated {len(odors)} time steps")

Available Models

• 'desert-hws': Desert environment with high wind speeds (3.5-6 m/s)
• 'desert-lws': Desert environment with low wind speeds
• 'forest': Forest environment measurements
• 'rigolli': CFD-based simulation data

# List all available models
models = cosmos.list_available_models()
for model in models:
    print(f"{model['name']}: {model['description']}")

API Reference

cosmos.predictor(model_name)

Create a COSMOS predictor for real-time odor simulation.

Parameters:

• model_name (str): Name of pre-trained model ('desert-hws', 'desert-lws', 'forest', 'rigolli')

Returns:

• CosmosFast object with step_update(x, y, dt) method

predictor.step_update(x, y, dt=0.005)

Update odor concentration for current position.

Parameters:

• x (float): Current x position
• y (float): Current y position
• dt (float): Time step in seconds (default: 0.005)

Returns:

• float: Odor concentration at current position

Requirements

• Python ≥ 3.8
• numpy ≥ 1.20.0
• pandas ≥ 1.3.0
• scipy ≥ 1.7.0
• numba ≥ 0.56.0
• h5py ≥ 3.0.0

Installation from Source

git clone https://github.com/arunavanag591/COSMOS.git
cd COSMOS
pip install -e .

Citation

If you use COSMOS in your research, please cite:

@article{nag2025cosmos,
  title={COSMOS: A Data-Driven Probabilistic Time Series simulator for Chemical Plumes across Spatial Scales},
  author={Nag, Arunava and van Breugel, Floris},
  journal={arXiv preprint arXiv:2505.22436},
  year={2025}
}

License

This project is dedicated to the public domain under CC0 1.0 Universal.

Repository

Full source code and documentation: https://github.com/arunavanag591/COSMOS