Skip to content

ncsim Documentation

ncsim (Networked Compute Simulator) is a headless discrete-event simulator for evaluating task scheduling algorithms on heterogeneous networked systems. It models compute nodes, network links with WiFi interference, and DAG task graphs, producing detailed JSONL traces and JSON metrics for analysis.

Developed by the Autonomous Networks Research Group (ANRG) at the University of Southern California.

Key Features

  • Deterministic simulation -- same inputs plus the same seed produce identical results every time
  • HEFT / CPOP / Round Robin scheduling -- integrated with anrg-saga schedulers, plus manual task pinning
  • Multi-hop routing -- direct, widest-path (max-min bandwidth), and shortest-path (min-latency) algorithms
  • 802.11 WiFi PHY/MAC modeling -- log-distance path loss, SNR-based MCS rate adaptation for 802.11n/ac/ax
  • Interference models -- none, proximity, CSMA/CA clique-based, and CSMA/CA Bianchi (dynamic SINR)
  • Fair bandwidth sharing -- concurrent transfers on the same link share capacity proportionally
  • Web visualization UI -- interactive experiment builder, Gantt charts, animated replay, and network topology views
  • Structured output -- JSONL event traces and JSON summary metrics for automated analysis

Guide Roadmap

This documentation is organized into eight sections, each covering a different aspect of ncsim:

# Section What You Will Learn
1 Getting Started Install ncsim, its dependencies, and the optional visualization frontend
2 Core Concepts Understand the architecture, simulation model, scheduling, routing, and interference
3 Scenarios Write and customize YAML scenario files that define networks, DAGs, and configurations
4 CLI Usage Run simulations from the command line, interpret output files, and automate batch experiments
5 Visualization Set up and use the web UI to configure experiments and explore results interactively
6 Experiments Reproduce interference verification and routing comparison experiments
7 Tutorials Follow step-by-step walkthroughs from first simulation to advanced WiFi experiments
8 Reference Look up FAQs, troubleshooting tips, and the glossary

New to ncsim?

Start with the Installation guide, then follow the Quick Start to run your first simulation in under five minutes.

How It Works

At a high level, ncsim follows this pipeline:

graph LR
    A[Scenario YAML] --> B[Scenario Loader]
    B --> C[Scheduler<br/>HEFT / CPOP / RR]
    C --> D[Simulation Engine]
    D --> E[Trace JSONL]
    D --> F[Metrics JSON]
    F --> G[Viz UI / Analysis]
    E --> G
  1. You define a scenario in YAML: network topology, node capacities, link bandwidths, DAG task graphs, and configuration (scheduler, routing, interference model, seed).
  2. The scheduler (powered by anrg-saga) assigns tasks to nodes.
  3. The simulation engine executes the schedule as a discrete-event simulation, modeling compute time, data transfers, multi-hop routing, bandwidth sharing, and WiFi interference.
  4. The engine produces a JSONL trace (every event) and JSON metrics (summary statistics including makespan, utilization).
  5. You can analyze the output with the included analyze_trace.py script, feed it into the web visualization UI, or process it with your own tools.

Project Information
Repository github.com/ANRGUSC/ncsim
PyPI package anrg-ncsim
License MIT
Python 3.10+
Contributors Bhaskar Krishnamachari, Maya Gutierrez
Organization Autonomous Networks Research Group (ANRG), University of Southern California

Citation

If you use ncsim in your research, please cite it. See the CITATION.cff file in the repository for the recommended citation format.