UbiCompSim

---

📖 Table of Contents

• Introduction
• Key Features
• Installation
• Quick Start
• Tutorial Series
• Project Structure
• API Overview
• Roadmap
• Contributing
• License

---

📝 Introduction

With the rapid development of IoT, edge computing, and mobile computing, Ubiquitous Computing has become a research hotspot in both academia and industry. UbiCompSim is a ubiquitous computing simulation environment based on Python + SimPy + NetworkX, designed to provide researchers and developers with a highly cohesive, loosely coupled modular simulation framework. It enables simulation and analysis of task offloading, resource scheduling, mobility management, and dynamic topology problems in ubiquitous computing scenarios. UbiCompSim adopts a layered and plugin-oriented design philosophy, ensuring that researchers and developers can easily replace routing algorithms, add new node types, or introduce new scheduling strategies.

---

✨ Key Features

Feature	Description
🕐 Discrete Event Simulation	Built on SimPy, providing precise time progression and event scheduling mechanisms
🌐 Dynamic Topology Management	Based on NetworkX for dynamic graph computation, supporting link establishment and disconnection due to node mobility
🧩 Heterogeneous Node System	Supports cloud centers, edge servers, RSUs, UAVs, mobile terminals, and other node types
📊 Fine-grained Monitoring	Built-in Monitor module that automatically collects task latency, success rate, node utilization, and other metrics
📈 Visualization Output	One-click generation of CSV data files and statistical charts (latency decomposition, success rate, target distribution, etc.)
🎯 Flexible Scheduling Strategies	Supports nearest, min_load, min_latency, and other offloading strategies, easily extensible
📚 Progressive Tutorials	9 tutorials from basic to advanced, helping you get started quickly

---

📦 Installation

Requirements

• Python 3.8+
• networkx
• pandas
• matplotlib

Install Dependencies

# Clone the repository
git clone https://github.com/NexusMindLab/UbiCompSimDraft.git
cd UbiCompSimDraft

# Install dependencies
pip install simpy networkx pandas matplotlib

Optional Dependencies

# For Deep Reinforcement Learning extensions
pip install torch gym

# For SUMO trajectory import
pip install sumolib

---

🚀 Quick Start

Minimal Example

Create the simplest simulation environment, running for 10 seconds of simulation time:

from core.env import SimulationEnv

def clock_printer(env):
    while True:
        print(f"[Sim Time] {env.current_time:.1f}s")
        yield env.timeout(1.0)

env = SimulationEnv()
env.process(clock_printer(env))
env.run(until=10.0)

Task Offloading Example

Create terminals and edge servers, run task generation and processing:

from core.env import SimulationEnv
from entities.nodes import ComputeNode, UserTerminal
from tasks.task_generator import TaskGenerator

env = SimulationEnv()

# Create edge server (4 cores, 10000 cycles/s)
edge = ComputeNode(node_id="Edge_1", env=env, cpu_freq=10000.0, num_cpus=4)

# Create user terminal
terminal = UserTerminal(node_id="Terminal_1", env=env)
terminal.offload_target = edge

# Create task generator (Poisson process, 1 task/s)
task_gen = TaskGenerator(terminal=terminal, arrival_rate=1.0)
terminal.task_generator = task_gen

# Start and run
terminal.start()
env.run(until=20.0)

print(f"Completed: {len(terminal.completed_tasks)}")

---

📚 Tutorial Series

We provide 9 tutorials from basic to advanced to help you master all features of UbiCompSim:

Tutorial	Name	Learning Objectives
01	Hello Sim	Understand simulation environment creation, SimPy clock
02	Task Flow	Master Task, ComputeNode, TaskGenerator
03	Static Topology	Understand DynamicGraph, transmission delay calculation
04	Mobility	Master RandomWaypoint mobility model
05	Dynamic Topology	Understand dynamic edge establishment and disconnection
06	Heterogeneous Nodes	Master Cloud/Edge/RSU/UAV heterogeneous nodes
07	Offloading Strategy	Understand offload controller and scheduling strategy comparison
08	Metrics & Visualization	Master Monitor, CSV export, chart generation
09	Full Demo	Complete demo integrating all features

---

📁 Project Structure

UbiCompSim/
│
├── core/                   # Core engine module
│   ├── __init__.py
│   └── env.py              # SimulationEnv - Simulation environment wrapper
│
├── entities/               # Entity module
│   ├── __init__.py
│   └── nodes.py            # BaseNode, ComputeNode, CloudCenter, RSU, UAV, UserTerminal
│
├── topology/               # Topology and network module
│   ├── __init__.py
│   └── graph.py            # DynamicGraph - Dynamic graph based on NetworkX
│
├── mobility/               # Mobility model module
│   ├── __init__.py
│   └── rwp.py              # RandomWaypoint - Random Waypoint mobility model
│
├── tasks/                  # Task and workload module
│   ├── __init__.py
│   ├── task.py             # Task - Task data class
│   └── task_generator.py   # TaskGenerator - Poisson process task generator
│
├── orchestration/          # Scheduling and routing strategy module
│   ├── __init__.py
│   └── controller.py       # OffloadController - Offloading decision controller
│
├── metrics/                # Data collection and monitoring module
│   ├── __init__.py
│   └── monitor.py          # Monitor - Metrics collection and visualization
│
├── examples/               # Tutorial examples
│   ├── README.md
│   ├── tutorial_01_hello_sim.py
│   ├── tutorial_02_task_flow.py
│   ├── ...
│   └── tutorial_09_full_demo.py
│
├── results/                # Simulation results output directory
│
├── main.py                 # Main entry script
├── config.yaml             # Global parameter configuration (TODO)
└── README.md               # This file

---

🔌 API Overview

Core Classes

Class	Module	Description
SimulationEnv	core.env	Wraps SimPy environment, provides global clock and event coordination
BaseNode	entities.nodes	Abstract base class for nodes, defines common interfaces
ComputeNode	entities.nodes	Compute node with CPU resource queuing system
CloudCenter	entities.nodes	Cloud center node with high computing power and high latency
RSU	entities.nodes	Roadside unit, fixed-position edge computing
UAV	entities.nodes	UAV node, mobile edge computing with battery decay
UserTerminal	entities.nodes	User terminal that generates tasks and receives results
DynamicGraph	topology.graph	Dynamic topology graph managing node connections and bandwidth
RandomWaypoint	mobility.rwp	Random Waypoint mobility model
Task	tasks.task	Task data class
TaskGenerator	tasks.task_generator	Poisson process task generator
OffloadController	orchestration.controller	Offloading decision controller
Monitor	metrics.monitor	Data collection and visualization monitor

Common Methods

# Simulation environment
env = SimulationEnv()
env.run(until=100.0)          # Run simulation
env.timeout(1.0)              # Create timeout event
env.process(generator)        # Start process

# Nodes
node = ComputeNode(node_id="Edge_1", env=env, cpu_freq=10000.0, num_cpus=4)
node.compute(task)            # Process task
node.get_load_ratio()         # Get load ratio

# Topology
topology = DynamicGraph(comm_radius=300.0, base_bandwidth=100.0)
topology.add_node(node_id, x=0, y=0)
topology.update_edges()       # Update edge connections
topology.get_distance(a, b)   # Get distance between nodes
topology.get_transmission_delay(a, b, data_size)  # Calculate transmission delay

# Mobility
mobility = RandomWaypoint(area_width=500, area_height=500, min_speed=5, max_speed=15)
x, y, is_moving = mobility.step(dt)

# Monitoring
monitor = Monitor(output_dir="results")
monitor.record_task_completion(task)
monitor.export_csv()
monitor.generate_charts()
monitor.print_summary()

---

🗺️ Roadmap

Phase	Status	Description
Phase 1: Static Closed-Loop MVP	✅ Done	Core skeleton and basic task flow
Phase 2: Static Topology & Network Transmission	✅ Done	NetworkX graph computation and transmission delay
Phase 3: Node Mobility & Dynamic Topology	✅ Done	RandomWaypoint and dynamic edge management
Phase 4: Heterogeneous Computing & Dynamic Scheduling	✅ Done	Multi-node types and offloading strategies
Phase 5: Data Collection & Visualization	✅ Done	Monitor module and chart generation
Phase 6: Configuration System	🚧 Planned	YAML configuration file driving simulation parameters
Phase 7: Advanced Mobility Models	🚧 Planned	Gauss-Markov, SUMO trajectory import
Phase 8: DRL Integration	🚧 Planned	PyTorch deep reinforcement learning scheduling strategies
Phase 9: Multi-hop Routing	🚧 Planned	AODV, DSR and other routing protocols
Phase 10: Energy Model	🚧 Planned	Node energy modeling and green scheduling

---

📄 Note

• Over 95% of the code in this project was generated using vibe coding techniques, and then reviewed and verified by humans.

• This project is licensed under the MIT License. See the LICENSE file for details.

• If you find this project helpful, please give us a ⭐ Star! Your support is our motivation for continuous improvement.

---

📚 Citation

If you use UbiCompSim in your research, please cite the following BibTeX entry:

@article{zhang2022osttd,
  title={OSTTD: Offloading of Splittable Tasks with Topological Dependence in Multi-Tier Computing Networks},
  author={Zhang, Rui and Chu, Xuesen and Ma, Ruhui and Zhang, Meng and Lin, Liwei and Gao, Honghao and Guan, Haibing},
  journal={IEEE Journal on Selected Areas in Communications},
  year={2022},
  publisher={IEEE}
}

_{Built with ❤️ by the NexusMindLab}