Skip to content

Commit bf7b346

Browse files
bwbushbwbush
authored
Instructions for re-running experiments
1 parent d280dbf commit bf7b346

File tree

1 file changed

+109
-0
lines changed

1 file changed

+109
-0
lines changed

‎analysis/sims/ReadMe.md

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Instructions for re-reunning simulation studies
2+
3+
These instructions are valid for the folders `2025w25/` and onwards.
4+
5+
6+
## Recipe
7+
8+
### Running the simulation
9+
10+
1. Navigate to the folder for the study, for example `2025w31c/`.
11+
2. Copy or link the Rust simulator `sim-cli` executable to that folder.
12+
- If you want to reproduce the study, check out the git commit listed in the `sim-cli.hash` file.
13+
- Otherwise, run `cargo build --release` in the [sim-rs](../../sim-rs/) folder.
14+
3. Copy of link the Haskell `leios-trace-processor` executable to that folder.
15+
- *Cabal:* compile using `cabal build all`.
16+
- *Nix:* compile using `nix build #leios-trace-processor`.
17+
4. You can execute individual scenarios by executing the `run.sh` script in the relevant folder.
18+
- *Nix:* run `./run.sh`, which will automatically fetch the package dependencies.
19+
- *Without Nix:* run `bash run.sh`, but make sure you have the dependent tools already installled, which are listed in the first lines of `run.sh`.
20+
5. The results folder will contain results:
21+
- `sim.log.gz`: the simulation log file, but with a few of the minor message types discarded.
22+
- `lifecycle.csv.gz`: transaction lifecycle results.
23+
- `resoruces.csv.gz`: resource usage results.
24+
- `receipts.csv.gz`: message diffusion results.
25+
- `cpus.csv.gz`: CPU usage results.
26+
- `sizes.csv.gz`: BLock size results.
27+
6. You can also run several simulations at once using the `parallel` command-line tool.
28+
29+
30+
### Combining the results
31+
32+
7. Execute the `combine-results.sh` script to bundle the results from multiple runs into the `results/` folder.
33+
- *Nix:* run `./combine-results.sh`.
34+
- *Without nix:* run `bash combine-results.sh` after installing the required dependencies.
35+
36+
37+
### Plot the results in Jupyter
38+
39+
8. Start a Jupter notebook server using the command `nix run #../sims/`.
40+
9. In the web browser, navigate to the relevant experiment folder and open any `.ipynb` files of interest.
41+
42+
43+
## Data dictionary
44+
45+
46+
### Lifecycle analysis
47+
48+
| Field | Units | Type | Description
49+
|-------------|-------|------------------|----------------------------------------------------------------------------------------|
50+
| /scenario/ | - | input | Multiple columns defining the scearion. |
51+
| Kind | - | output | The kind of item: `IB`, `EB`, `RB`, or `VT`. |
52+
| Item | - | output | The identifier for the item. |
53+
| Size [B] | B | output | The size of the item. |
54+
| References | - | output | The number of times the TX, IB, or EB is referenced by an IB, EB, or EB, respectively. |
55+
| Created [s] | s | output | When the item was created. |
56+
| To IB [s] | s | output | When the item was first included in an IB. |
57+
| To EB [s] | s | output | When the item was first referenced by an EB. |
58+
| To RB [s] | s | output | When the item was first referenced by an RB. |
59+
| In RB [s] | s | output | When the transaction was first included in an RB. |
60+
61+
62+
### Resource usage
63+
64+
| Field | Units | Type | Description |
65+
|---------------------------|------------|----------|-----------------------------------------------------------------------------------------------|
66+
| /scenario/ | - | input | Multiple columns defining the scearion. |
67+
| Node | - | output | The unique identifier for the node that performed the task. |
68+
| Egress [B] | B | output | The number of bytes leaving the node during the simulation. |
69+
| Disk [B] | B | output | The number of bytes stored to disk during the simulation. |
70+
| Total CPU [s] | s | output | The total CPU consumed during the simulation. |
71+
| Maximum CPU [s/s] | %/100 | output | The one-second average peak CPU fraction consumed during the simulation. |
72+
73+
74+
### Receipt of messages
75+
76+
| Field | Units | Type | Description |
77+
|---------------------------|-------|----------|-----------------------------------------------------------------------------------------------|
78+
| /scenario/ | - | input | Multiple columns defining the scearion. |
79+
| Kind | - | output | The kind of item: `IB`, `EB`, `RB`, or `VT`. |
80+
| Item | - | output | The unique identifier for the item. |
81+
| Producer | - | output | The unique identifier for the node that generated the item. |
82+
| Generated [s] | s | output | When the item was generated. |
83+
| Size [B] | B | output | The size of the item. |
84+
| Recipient | - | output | The unique identifier for the node that received the item. |
85+
| Received [s] | s | output | The time when the item was received. |
86+
| Elapsed [s] | s | output | The time elapsed between when the item was originally sent by the producer and then received. |
87+
88+
89+
### CPU usage
90+
91+
| Field | Units | Type | Description |
92+
|---------------------------|-------|----------|-----------------------------------------------------------------------------------------------|
93+
| /scenario/ | - | input | Multiple columns defining the scearion. |
94+
| Slot | s | output | The slot number when the task *started*. |
95+
| Node | - | output | The unique identifier for the node that performed the task. |
96+
| Task | - | output | The abbreviation for the task that was performed. |
97+
| Duration [s] | s | output | The number of seconds of vCPU usage for the task. |
98+
99+
100+
### Block size
101+
102+
| Field | Units | Type | Description |
103+
|---------------------------|-------|----------|-----------------------------------------------------------------------------------------------|
104+
| /scenario/ | - | input | Multiple columns defining the scearion. |
105+
| Kind | - | output | The kind of block: `IB`, `EB`, or `RB`. |
106+
| Item | - | output | The unique identifier for the block. |
107+
| Generated [s] | s | output | When the block was generated. |
108+
| Transactions | - | output | Number of transactions directly referenced by the block. |
109+
| Endorses | - | output | The unique identifier for the item that the block endorses. |

0 commit comments

Comments
 (0)