Merge pull request #22 from Macr0Nerd/docs

Docs

README.md

@@ -35,34 +35,37 @@ This is a human-readable format that is easy to write.
 The schema has been provided below:
 
 ```toml
+simulation_id = "name of simulation"
 algorithms_directory = "/path/to/algorithms/"
 nodes = [ { node_id = "node_1", algorithm = { file = "foo.py", object = "Foo" } },
           { node_id = "node_2", algorithm = { file = "bar/baz.py", object = "Baz" } } ]
-rounds_data = "path/to/round.json"
-rounds_output = "path/to/round.json"
-simulation = { file = "foobar.py", object = "FooBar" }
-simulation_id = "name of simulation"
+simulation = { file = "foobar.py", object = "GenerationalFooBar" }
+generational_simulation = { file = "foobar.py", object = "FooBar" }
 simulation_arguments = { foo = "bar" }
-simulation_results = "path/to/results.json"
+simulation_data = "path/to/round.json"
+simulation_data_output = "path/to/round.json"
+simulation_results_output = "path/to/results.json"
 simulations_directory = "/path/to/simulations/"
 ```
 
 * algorithms_directory
   * A path to the directory containing the algorithms files
+* generational_simulation
+  * The simulation to run for each generation in a generational simulation as a [Dynamic Import](#dynamic-imports)
 * nodes
   * An array of tables that specify a node id and an algorithm, as defined in the [Dynamic Imports](#dynamic-imports)
 section
-* rounds_data
-  * Path to a JSON file containing previous round data
-* rounds_output
-  * Path to write the round data as a JSON
-* simulation:
-  * A [Dynamic Import](#dynamic-imports)
+* simulation
+  * The simulation to run as a [Dynamic Import](#dynamic-imports)
 * simulation_id
   * The name of the simulation
 * simulation_arguments
   * Arguments to pass into the simulation
-* simulation_results
+* simulation_data
+  * Path to a JSON file containing previous simulation data
+* simulation_data_output
+  * Path to write the simulation data as a JSON
+* simulation_results_output
   * Path to write the simulation results
 * simulations_directory
   * A path to the directory containing additional simulation files

docs/simulations.md

@@ -0,0 +1,47 @@
+# Simulations
+There are four included simulations in the project.
+These are:
+* BasicSimulation
+* StandardSimulation
+* MultiprocessingStandardSimulation
+* StandardGenerationalSimulation
+
+All of these accept the same arguments, with minor additional configuration options for the latter two.
+The parameters for configuring these simulations are:
+* rounds | int
+  * How many rounds should be run in each simulation
+* noise | bool
+  * If the simulation is noisy (decisions may randomly be flipped)
+* noise_per_mille | int
+  * How noisy the simulation is as a per mille representation
+    * i.e. 999 = 99.9%, 250 = 25.0%
+* round_mutations | bool
+  * If mutations are enabled at the end of every round
+* simulation_mutations | bool
+  * If mutations are enabled at the end of every simulation (only useful for generational simulations)
+* mutations_per_mille
+  * How frequent mutations should occur as a per mille representation
+    * i.e. 999 = 99.9%, 250 = 25.0%
+
+# StandardSimulation
+This takes each node and pits it against each other node in multiple 1:1 matches, as is standard for the prisoner's
+dilemma.
+
+## MultiprocessingStandardSimulation
+This runs the StandardSimulation on multiple processes so that it can run faster for larger simulations.
+It has one additional argument:
+* pool_size | int
+  * How many processes should be spawned
+  * Default is the number of CPU cores of the system
+
+# StandardGenerationalSimulation
+This runs multiple generations of simulations and applies a function after each round to make changes before the next.
+This function takes the processed results of the last generation and for each __algorithm__ calculates a change in the
+population size for each __algorithm__ based on the ratio of the difference of the algorithm points and the average
+points per algorithm to the average points per algorithm.
+
+    population_change = algorithm_population * ((algorithm_points - average_points)/average_points)
+
+This simulation accepts one additional argument:
+* generations | int
+  * The number of generations to run