Update README.md

README.md

@@ -8,8 +8,76 @@ algorithm involves::
 3) For each selected window, generate 3^N-1 neighbor windows
 4) Sample new windows, then go to 1) or stop if no new windows can be found
 
-For more details about the algorithm: See
+For more details about the algorithm, see
 
-Self-Learning Adaptive Umbrella Sampling Method for the Determination of Free Energy Landscapes in Multiple Dimensions (Wojtas-Niziurski†, Meng, Roux, Bernèche, 2013)
+Self-Learning Adaptive Umbrella Sampling Method for the Determination of Free Energy Landscapes in Multiple Dimensions (Wojtas-Niziurski, Meng, Roux, Bernèche, 2013)
 [(https://doi.org/10.1021/ct300978b)](https://doi.org/10.1021/ct300978b)
 
+## Usage
+
+Implement the UmbrellaRunner class according to your needs: 
+
+```python
+from adaptiveumbrella.runner import UmbrellaRunner
+
+class MyUmbrellaRunner(UmbrellaRunner):
+  pass
+```
+
+within the class we need to define two methods. First we have to define how the simulation windows should be sampled:
+
+```python
+  def simulate_frames(self, lambdas, frames):
+    """ Run simulations for all passed lambda steps. `lambdas` is a dictionary where each key
+    is a tuple of coordinates in the phase space and each value are the lambda values of the root
+    from which this frame should be created. `frames` is an identical dict, but with indeces of the pmf
+    numpy array defining the phase space """
+    pass
+```
+
+then, we have to implement a method that updates the pmf:
+```python
+  def simulate_frames(self, lambdas, frames):
+    """ Run simulations for all passed lambda steps. `lambdas` is a dictionary where each key
+    is a tuple of coordinates in the phase space and each value are the lambda values of the root
+    from which this frame should be created. `frames` is an identical dict, but with indeces of the pmf
+    numpy array defining the phase space """
+    pass
+    
+```python
+  def calculate_new_pmf(self):
+  """ This is called after `simulate_frames` and should calculate the new PMF. return value must be a numpy
+  array of similar dimensions then the lambda states.
+  pass
+```
+
+Finally, we can instantiate the class, pass the configuration variables and start the simulations:
+
+```python
+runner = MyUmbrellaRunner()
+
+# 2 dimensional phase space ranging from -3 to 3 in both dimensions
+# lambda spacing is 0.2 in x and y
+runner.cvs = np.array([
+    (-3, 3, 0.2),
+    (-3, 3, 0.2),
+])
+# initial lambda coordinates
+runner.cvs_init = (1.4, -1.4)
+
+# initial energy for finding new frames
+runner.E_min = 10
+
+# max. energy before sampling stops
+runner.E_max = 100
+
+# energy change between steps
+runner.E_incr = 10
+
+# max. number of iterations before stopping
+runner.max_iterations = 100
+
+# let's go
+runner.run()
+```
+