From 4cc3c6dea5c5536d47fcbaf8414d74de7b6fdc4b Mon Sep 17 00:00:00 2001
From: Fabian Mastenbroek <mail.fabianm@gmail.com>
Date: Fri, 9 Nov 2018 14:30:28 +0100
Subject: docs: Rewrite README for 2.x release

This change gives an overhaul to the README for the release of version
2.x of the simulator.
---
 README.md | 112 ++++++++++++++++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 95 insertions(+), 17 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index fa8a0ba9..54fa77cb 100644
--- a/README.md
+++ b/README.md
@@ -3,11 +3,8 @@
     <img src="misc/artwork/logo.png" width="100" alt="OpenDC">
   </a>
   <br>
-  OpenDC Simulator
+  odcsim
 </h1>
-<p align="center">
-Collaborative Datacenter Simulation and Exploration for Everybody
-</p>
 <p align="center">
 	<a href="https://travis-ci.org/atlarge-research/opendc-simulator">
 		<img src="https://travis-ci.org/atlarge-research/opendc-simulator.svg?branch=master" alt="Build Status">
@@ -17,22 +14,103 @@ Collaborative Datacenter Simulation and Exploration for Everybody
 	</a>
 </p>
 
-## Getting the source
-Download the source code by running the following code in your command prompt:
-```sh
-$ git clone https://github.com/atlarge-research/opendc-simulator.git
+## Introduction
+**odcsim** is a framework for discrete event simulation in Kotlin and Java, used
+by the [OpenDC](https://opendc.org) project.
+Simulations are defined in terms of a hierarchical grouping of actors
+and the interactions between these actors
+([Actor model](https://en.wikipedia.org/wiki/Actor_model)), using
+an API very similar to [Akka Typed](https://doc.akka.io/docs/akka/current/typed/index.html).
+
+## Documentation
+Check out the [Getting Started](#getting-started) section for a quick
+overview.
+The documentation is located in the [docs/](docs/) directory and is divided as follows:
+* [Main Concepts](docs/concepts.md)
+* [Building a Model](docs/build.md)
+* [Running a Model](docs/run.md)
+* [Pre-built Models](docs/models.md)
+* [API Reference](https://atlarge-research.github.io/opendc-simulator)
+* [Contributing Guide](CONTRIBUTING.md)
+
+## Getting Started
+
+### Installation
+Please add the required packages as dependency in your project.
+Releases are available in the [Maven Central Repository](https://search.maven.org/).
+
+The package `odcsim-core` is required to construct a simulation model.
+A `odcsim-engine-*` package is needed for running the simulation
+model.
+
+**Gradle**
+```groovy
+compile 'com.atlarge.odcsim:odcsim-core:2.0.0'
+compile 'com.atlarge.odcsim:odcsim-engine-omega:2.0.0'
 ```
-or simply [grab](https://github.com/atlarge-research/opendc-simulator/archive/master.zip) a copy of the source code as a Zip file.
 
-## Building
-For building the source code, we use Gradle. To run gradle, enter the following in your command prompt:
-```sh
-$ ./gradlew build
+**Maven**
+```xml
+<dependency>
+   <groupId>com.atlarge.odcsim</groupId>
+   <artifactId>odcsim-core</artifactId>
+   <version>2.0.0</version>
+</dependency>
+
+<dependency>
+   <groupId>com.atlarge.odcsim</groupId>
+   <artifactId>odcsim-engine-omega</artifactId>
+   <version>2.0.0</version>
+</dependency>  
 ```
-To test the source code, run the following code in your command prompt:
+
+### Construction of Simulation Model
+Let's construct a simple simulation model of a single car actor.
+The car will alternately drive and park for a while. When it starts
+driving (or parking), it will print the current simulation time.
+
+
+```kotlin
+import com.atlarge.odcsim.Behavior
+import com.atlarge.odcsim.coroutines.suspending
+import com.atlarge.odcsim.coroutines.dsl.timeout
+
+fun car(): Behavior<Nothing> = 
+    suspending { ctx ->
+        while (true) {
+            println("Start parking at ${ctx.time}")
+            val parkingDuration = 5.0
+            timeout(parkingDuration)
+             
+            println("Start driving at ${ctx.time}")
+            val tripDuration = 2.0
+            timeout(tripDuration)
+        }
+        
+        stopped()
+    }
 ```
-$ ./gradlew test
+
+### Running Simulation
+Running the constructed simulation model requires an implementation
+of the `ActorSystem` interface provided by one of the `odcsim-engine-*`
+packages. The [ServiceLoader](https://docs.oracle.com/javase/9/docs/api/java/util/ServiceLoader.html)
+class found in the JDK can be used to locate the `ActorSystem` implementation on the classpath.
+```kotlin
+import com.atlarge.odcsim.ActorSystemFactory
+import java.util.ServiceLoader
+
+val factory = ServiceLoader.load(ActorSystemFactory::class.java).first()
+val system = factory(car(), name = "car")
+system.run(until = 10.0)
+system.terminate()
 ```
 
-## License
-The code is released under the MIT license. See the `LICENSE.txt` file.
+## Contributing
+### Contributing Guide
+Read our [contributing guide](CONTRIBUTING.md) to learn about our
+development process, how  to propose bug fixes and improvements, and how
+to build and test your changes to the project.
+
+### License
+**odcsim** is [MIT licensed](https://github.com/atlarge-research/opendc-simulator/blob/master/LICENSE.txt).
-- 
cgit v1.2.3