From 30a82265c96941dfaf5c05b0c9d35cf05d9bf310 Mon Sep 17 00:00:00 2001
From: Youngjoon Lee <5462944+youngjoon-lee@users.noreply.github.com>
Date: Wed, 15 May 2024 19:41:48 +0900
Subject: [PATCH] add time concept in readme

---
 mixnet/v2/sim/README.md   | 22 ++++++++++++++++++++--
 mixnet/v2/sim/config.yaml |  1 +
 2 files changed, 21 insertions(+), 2 deletions(-)

diff --git a/mixnet/v2/sim/README.md b/mixnet/v2/sim/README.md
index 15be182..f8cbadc 100644
--- a/mixnet/v2/sim/README.md
+++ b/mixnet/v2/sim/README.md
@@ -1,10 +1,11 @@
 # Mixnet v2 Simulation
 
-* [How to run](#how-to-run)
+* [How to Run](#how-to-run)
+  + [Time in simulation](#time-in-simulation)
 * [Mixnet Functionalities](#mixnet-functionalities)
 * [Adversary Models](#adversary-models)
 
-## How to run
+## How to Run
 
 First, make sure that all dependencies specified in the `requirements.txt` in the project root.
 Then, configure parameters in the [`config.yaml`](./config.yaml), and run the following command:
@@ -13,6 +14,23 @@ python main.py --config ./config.yaml
 ```
 The simulation runs during a specified duration, prints the results to the console, and show some plots.
 
+### Time in simulation
+
+The simulation has been implemented based on [SimPy](https://simpy.readthedocs.io/en/latest/) which is discrete-event simulation framework.
+All events are processed sequentially by a single thread.
+However, multiple parallel events, which should be processed at the same time, can be also simulated by scheduling them at the same "time".
+
+The simulation has the virtual time concept, which doesn't have the same scale as the real time.
+If the event A is scheduled to happen at time 10, and the event B is scheduled to happen at time 11,
+the simulation guarantees that the event B happens only after the event A happens.
+But, it doesn't mean that the event B happens exactly 1 second after the event A. It will be much shorter.
+
+If two events are scheduled at the same time (e.g. 10), the simulation processes the one that is scheduled first and the other one next (FIFO).
+But, it is guarantees that those two event are processed before the events scheduled at time 11+.
+
+Using this virtual time, complex distributed systems can be simulated in a simple way without worrying about the real-time synchronization.
+For more details, please see the [Time and Scheduling](https://simpy.readthedocs.io/en/latest/topical_guides/time_and_scheduling.html#what-is-time) section in the SimPy documentation.
+
 ## Mixnet Functionalities
 - Modified Sphinx
     - [x] Without encryption
diff --git a/mixnet/v2/sim/config.yaml b/mixnet/v2/sim/config.yaml
index fef3b6b..6dea132 100644
--- a/mixnet/v2/sim/config.yaml
+++ b/mixnet/v2/sim/config.yaml
@@ -1,3 +1,4 @@
+# The simulation uses a virtual time. Please see README for more details.
 running_time: 30
 num_nodes: 100
 num_mix_layers: 3