PureEdgeSim documentation

This folder is the long-form manual for PureEdgeSim, written for new researchers, PhD students, and engineers who need to understand, configure, extend, and trust the simulator. The guides explain both how to use the framework and why it behaves the way it does.

If you are looking for the shortest path to a running simulation, read Getting started. If you want to understand the internals before changing anything, read Architecture and Task lifecycle.

Reading paths

Path 0: I am still choosing a simulator

  1. How PureEdgeSim compares: the modeling coverage, runtime, code quality, and maintenance of PureEdgeSim against the 24 edge computing simulators of a peer-reviewed comparison, including the cases where another tool is the better fit.

Path 1: I want to run an experiment this week

  1. Getting started: install, build, run an example, read the output.
  2. Configuration: change the scenario, workload, devices, network, and algorithms.
  3. Output and metrics: understand the CSV columns and the charts.
  4. Research guide: design a defensible experiment and report it.
  5. If your workload was measured rather than assumed, replay it: Example 25 feeds a recorded production trace of 8819 LLM inference requests to the simulator and compares it with random arrivals at the same means.
  6. If your claim is about fault tolerance, say what fails: Example 26 crashes the device that carries the orchestration halfway through a pure edge run, and each of its four mechanisms is switched off from the command line to measure what it is worth.

Path 2: I want to implement a new offloading algorithm

  1. Getting started.
  2. Task lifecycle: where decisions happen in the event flow.
  3. Writing orchestrators: a complete, buildable custom orchestrator.
  4. API reference: the classes and methods you will call.
  5. Example 26 puts three of the extension points together for one scenario: an orchestrator that learns its placements, devices that defend their real-time traffic, and a simulation manager that injects the crash.

Path 3: I want to change how the simulated system works

  1. Architecture: modules, dependencies, and event processing.
  2. Simulation models: computing, energy, mobility, and network models.
  3. Customizing models: replace each default model without modifying the codebase.
  4. Contributing: tests, conventions, and the Javadoc build.

Documentation map

Document What it answers
How PureEdgeSim compares How does PureEdgeSim stack up against the other edge computing simulators, and when should I pick one of them instead?
Getting started How do I install, build, and run PureEdgeSim? What does a first simulation look like?
Architecture How is the simulator organized? How does the discrete-event engine work? How are scenarios initialized?
Configuration What does every parameter in every configuration file mean, and what are its units?
Task lifecycle What happens to a task from generation to result, and where can it fail?
Simulation models How are applications, task graphs, computing nodes, energy, mobility, and network transfers modeled?
Writing orchestrators How do I implement and plug in my own orchestration algorithm?
Customizing models How do I replace the mobility, energy, network, task generation, topology, or simulation manager?
Output and metrics How do I read the CSV, the console report, and the charts?
Research guide How do I design, run, and report a credible simulation study?
FAQ Why did my task fail? Why is the simulation slow? Why is the chart empty?
Contributing How do I run the tests, check coverage, and build the Javadoc?
API reference Which package and class should I use for a given job?

The one-paragraph mental model

PureEdgeSim is a discrete-event simulator. You describe a scenario in five configuration files: simulation parameters, applications, cloud data centers, edge data centers, and edge devices. A scenario is one combination of orchestration architecture, orchestration algorithm, and number of edge devices. The framework generates a list of tasks, feeds them to an event engine, and lets a workload orchestrator decide where each task executes. The task then travels through the network, waits for computing resources, executes, and sends its results back. Every event updates the simulator clock. When the simulation ends, the framework aggregates delays, failures, CPU use, network traffic, and energy consumption into a CSV row, a console report, and optional charts. Each of these terms is explained in the guides above.

Other sources of information

Conventions used in this manual