From ad86cd0495608ac3f8c61b925583e17f91425d8c Mon Sep 17 00:00:00 2001
From: gusto <bacv@users.noreply.github.com>
Date: Tue, 15 Aug 2023 22:44:08 +0300
Subject: [PATCH] Create README.md

---
 README.md | 77 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e92f85a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,77 @@
+# Nomos Node Simulations
+
+This repository contains a suite of scripts and configurations for running and analyzing simulations of nomos nodes.
+
+## Prerequisites
+
+### 1. Nomos Node Simulation App
+Before running simulations, ensure the `nomos-node/simulations` application is accessible from the `$PATH`:
+- Clone the project:
+```bash
+git clone git@github.com:logos-co/nomos-node.git
+```
+- Build the project using Crago:
+```bash
+crago build -p simulations --release
+```
+- Add the resulting release directory to `$PATH`:
+```bash
+export PATH=$PATH:<path to nomos-node>/target/release
+```
+
+### 2. Python Dependencies
+The data conversion and normalization processes make use of the Pandas Python package:
+```bash
+pip install pandas
+```
+
+## Network Overlays
+
+The simulation application supports two distinct network topologies to link nodes:
+
+- **Tree Overlay**: Constructs a full binary tree overlay, mirroring the connections between actual Nomos nodes.
+- **Branch Overlay**: Produces a single full-length branch of the binary tree overlay. This overlay offers a simulation of a more extensive network (though with fewer nodes) and is intended to approximate the latencies of a complete binary tree. More details can be found on [Notion](https://www.notion.so/Carnot-Simulation-Mechanism-c025dbab6b374c139004aae45831cf78).
+
+## Test Cases
+
+The primary objective of the simulation app is to replicate a large-scale real-world network environment while running the Carnot consensus engine.
+
+### Committee Sizes
+The simulation configuration can specify varying numbers of committees and nodes within them. To obtain these values, as recommended in the Carnot spec, refer to the `committee_sizes.py` script available at [nomos-specs](https://github.com/logos-co/nomos-specs/blob/master/carnot/committee_sizes.py)
+
+### Sample Test Cases
+This repository includes a set of sample test cases under `scripts/test_cases.csv`. The `committee_sizes.py` script from nomos-specs was used to generate these test cases.
+
+## Configuration
+
+The simulation application operates with JSON configuration files. The `scripts` directory offers helper scripts for creating a range of config variations:
+
+### `build_config.py`
+Generates a single configuration based on the template JSON file located at `scripts/config_builder/template.json`.
+
+Usage:
+```bash
+python build_config.py <tree/branch> <number of committees> <total nodes> <config name> <optional max_view to simulate> <optional network variation defined in config_builder/network>
+```
+
+### `build_cases.py`
+Produces multiple config variations as defined in the provided test cases CSV file (see `test_cases.csv` for a reference).
+
+Usage:
+```bash
+python build_cases.py test_cases.csv
+```
+
+## Running the Simulation
+
+### Standalone Mode
+Assuming the `simulations` binary is in your `$PATH`, run the simulation with your chosen config file:
+```bash
+simulations --input-settings <config_file.json> --stream type naive
+```
+
+### Batch Mode with Multiple Configurations
+To execute a series of simulations using different configuration files, utilize the `run_configs.py` script:
+```bash
+python run_configs.py <configs_dir>
+```