added description, examples and instructions in the README

README.md

-Scripts and data to decompose an input workload into user sessions.
\ No newline at end of file
+# swf2sessions
+Python script to read a workload trace in the [Standard Workload Format](https://www.cs.huji.ac.il/labs/parallel/workload/swf.html) (SWF), decompose it into user sessions and store the results in the Session Annotated Batsim JSON format (SABjson).
+
+## What is a session?
+The idea behind this decomposition is to keep the *logic* of user submissions rather than the exact submission times. For example, in the image below, the workload has been split into 4 sessions following the "Arrival" delimitation approach:
+
+![diagram](example_4_sessions.png)
+
+- Job1 and job2 belong to the same session because their inter-arrival time is lower than a threshold value (here: 60 minutes). 
+- Job3, however, started a new session. 
+- Session4 *depends on* sessions 2 and 3 because its first job was submitted after the terminaison of all jobs in sessions 2 and 3. 
+- Session3 *depends on* session1, but not on session2.
+
+
+
+## Usage
+You need python3 installed on your machine. 
+
+To run the session decomposition on the workload `workloads/example.swf` illustrated above, with "Arrival" delimitation approach and a threshold of 60 minutes:
+
+```terminal
+python3 swf2sessions.py -at 60 workloads/example.swf out/
+```
+
+For more documentation, see: `python3 swf2sessions.py -h`
+
+## Tests
+Some integration tests have been written for this script, and are stored in the `test/` folder. To run them on your machine, you need to install pytest and launch it at the root of the project:
+
+```terminal
+pip3 install pytest
+pytest
+```
\ No newline at end of file