Metadata-Version: 2.4
Name: nexusim
Version: 0.1.0b2
Summary: JAX-accelerated multi-scale simulator for biological control and causal discovery
License-Expression: MIT
Keywords: biology,simulator,jax,causal-discovery,multi-scale
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastexcel>=0.16.0
Requires-Dist: hydra-core>=1.3.2
Requires-Dist: imageio>=2.37.2
Requires-Dist: jax>=0.6.2
Requires-Dist: marimo>=0.17.0
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: msgspec>=0.20.0
Requires-Dist: networkx>=3.4.2
Requires-Dist: numpy>=2.2.6
Requires-Dist: optax>=0.2.6
Requires-Dist: polars>=1.34.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: requests>=2.32.5
Requires-Dist: tiledb>=0.35.2
Requires-Dist: tqdm>=4.67.1
Dynamic: license-file

# Nexus

Nexus is a JAX-accelerated multi-scale simulator for biological control and causal discovery, capable of generating biologically-realistic data.

## Table of contents

- [Setup](#setup)
- [Code Structure](#code-structure)
- [Usage](#usage)
- [Visualization](#visualization)

## Setup

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager before running the setup

```bash
# Install using pip
pip install nexusim

# (OR)
# Clone repo and build the package in uv
## Clone repository and 
git clone https://github.com/AmoghSingh25/GeneProtSim.git

## Create venv and download packages
uv sync
```

## Code Structure

- `src/nexus/`
  - `simulator/` - Core simulation engine
    - `dynamics/` - Mathematical models for simulator dynamics
    - `noise_models/` - Noise processes, random seeds
    - `utils/` - Utility functions for simulator
    - `grn/` - Code and logs of the GRN simulator
    - `spatial/` -  Code, model definitions and logs of the Spatial Sim
    - `spatial_vec/` -  Code, model definitions and logs of the vectorized version of Spatial Sim
    - `run_sim.py` - Run the GRN and Spatial Sim
    - `run_linked_sim.py` - Run the GRN and Spatial Sim together, allowing diffusion between cells and fields
  - `causal/` - Causal discovery and inference modules
    - `identification/` - Algorithms for structure/parameter learning
    - `evaluation/` - Evaluation scripts
  - `experiments/` - Scripts for running experiments
  - `dashboard/` - Plotting, analysis, dashboards
    - `web/` - Next.JS website for visualization of simulator outputs
    - `retrieve_logger_api.py` - Flask API to serve data to the website
  - `tests/` - Unit & integration tests
- `configs/` - Config files for runs
- `notebooks/` - Exploratory analyses and demos
- `docs/` - Documentation
  - `config_desc.md` - Configuration parameters and their description
  - `intervention_api.md` - Working of intervention API and its configuration
  - `simulator.md` - Working of the GRN simulator
  - `spatial_simulator.md` - Working of the spatial simulator
- `examples/` - Examples scripts
  - `marimo_example.py` - Marimo notebook containing example scripts
  - `ipynb_example.py` - IPYNB notebook containing example scripts
- `pyproject.toml` - For package/dependency management
- `README.md`

## Usage

A short code snippet for using the simulator is given below.
```py
from nexus.simulator.grn.grnSim import GRNSim
from nexus.simulator.spatial.spatialSim import SpatialSim
from hydra import initialize_config_dir, compose

 def get_config(config_name="test_config"): # Get config from Hydra config file
    conf_path = os.path.join(os.getcwd(), "configs")
    with initialize_config_dir(version_base=None, config_dir=conf_path):
        cfg = compose(config_name=config_name)
    return cfg

cfg = get_config()

sim = GRNSim(cfg.grn)
sim.run_sim()

spatial_sim = SpatialSim(cfg.spatial)
spatial_sim.run_sim()
```

Examples for running the simulator are given in a [Marimo notebook](examples/marimo_example.py) and a [IPYNB notebook](examples/ipynb_example.ipynb). The simulator uses Hydra configs for the simulation parameters and the description of the config files are given in [Config Description](docs/config_desc.md).

## Intervention API

The simulator also supports interventions on the parameters that allows for generating interventional data for causal discovery and analysis. Guidance on using interventions is given in the [Intervention Doc](docs/intevention_api.md).

## Visualization

The visualization can be run by the running the two commands in seperate terminal windows.

```bash
## Runs the API for fetching the data from TileDB
uv run src/dashboard/retrieve_logger_api.py

## Runs the website to visualize the data
cd dashboard/web/
npm install # If the packages are not installed
npm run dev
```

After running these two commands, open the link `http://localhost:3000` and select a log file from the dropdown. This log file should be present inside the relative directory `logs/`.

Further instructions on using the dashboard is given in [README](dashboard/web/README.md)
