Documentation.md

@@ -29,8 +29,54 @@ An example fitness function shell script can be shown [here](https://git.opendfk
 
 ### Programmatic use
 
-TODO: implement a 'Runner'-Class
+You can use GenIe as java library to optimize parameters programmatically. For this, you have the possibility to start the optimization with a method call. Per default, the settings inside the specified config file are used, even including the exec cost function call. Further, you can also set the cost function and adjust the config file settings by code.
 
+**Start optimization, settings+fitness function exec call from config file:**
+```java
+CandidateVectorWithMetadata bestVector = 
+  new GenIe().optimizeParams("geneticOptimization.conf");
+```
+
+**Start optimization, implement cost function instead of exec call. Settings from config file still:**
+```java
+CandidateVectorWithMetadata bestVector = 
+  new GenIe().setFitnessCalculator(new FitnessCalculator()
+    {
+      @Override
+      public double calculateFitness(CandidateVectorWithMetadata candidate, List<? extends CandidateVectorWithMetadata> population) throws Exception
+      {
+        int iSum = candidate.getCandidateVector().stream().mapToInt(Integer::valueOf).sum();
+        
+        if (iSum == 23)
+            return 0.9d;
+        
+        return 0d;
+      }
+    }).optimizeParams("geneticOptimization.conf");
+```
+
+**Start optimization, settings are set programmatically:**
+```java
+// create on your own or with a config file
+GeneticRunConfig geneticConfig = GeneticRunConfig.createFromFile("path2configFile");
+
+//...make your adjustments to the object optionally
+
+genIe.optimizeParams(geneticConfig)
+```
+
+**Dedicated methods for parameter values and independent parameters:**
+```java
+genIe.setParamNames2DiscreteValSpaces(LinkedHashMap<String, List<String>> paramNames2DiscreteValSpaces)
+genIe.setIndependentParamNames(List<String> independentParamNames)
+```
+
+**Gods:**
+
+During the genetic call so called ['gods'](https://git.opendfki.de/reuschling/genie/-/blob/main/src/main/java/de/dfki/sds/genie/genetic/GeneticParamOptimizerGod.java) are proofing generated vector candidates and whole populations, being able to have the last word. Gods are able to modify candidate vectors before they will be evaluated, e.g. for validation or normalization purposes. Subclass from [GeneticParamOptimizerGod](https://git.opendfki.de/reuschling/genie/-/blob/main/src/main/java/de/dfki/sds/genie/genetic/GeneticParamOptimizerGod.java) and overwrite the methods you need.
+```java
+genIe.addEvolutionGod(GeneticParamOptimizerGod evolutionGod)
+```
 
 ### Entropy analysis