Merge pull request #18 from Macr0Nerd/simulation_documentation

Added simulation documentation

README.md

@@ -94,10 +94,17 @@ The function should return `True` for cooperation, and `False` for defection.
 
 If you want to add mutations, set the static mutation list *after* defining the class as to avoid circular imports.
 
-A template has been provided us `templates/algorithm_template` for ease of use.
+A template has been provided us `templates/algorithm_template.py` for ease of use.
 
 ## Simulations
-Coming soon, see `project_dilemma.interfaces.simulation` for more information.
+Simulations a more complicated to configure as compared to algorithms.
+You only need to override the `run_simulation` and `process_simulation` methods, but these are incredibly important.
+
+`run_simulation` returns a `project_dilemma.interfaces.base.SimulationRounds` object that will be used by
+`process_simulation` to get the results.
+
+For example, the provided standard simulations process the rounds data to calculate scores for each node
+A template can be found in `templates/simulation_template.py`
 
 ## License
 Copyright 2023 Gabriele Ron

src/project_dilemma/__init__.py

@@ -13,6 +13,6 @@
 See the License for the specific language governing permissions and
 limitations under the License.
 """
-__version__ = '1.0.0rc2'
+__version__ = '1.0.0rc3'
 
 __all__ = ['config', 'interfaces', 'object_loaders', 'simulations']

templates/simulation_template.py

@@ -0,0 +1,37 @@
+"""
+Copyright 2023 Gabriele Ron
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+from abc import abstractmethod
+from collections.abc import Sequence
+
+from project_dilemma.interfaces import Node, Simulation, SimulationRounds
+
+
+class SimulationTemplate(Simulation):
+    @abstractmethod
+    def __init__(self, nodes: Sequence[Node], simulation_id: str, simulation_rounds: SimulationRounds = None):
+        super().__init__(nodes=nodes, simulation_id=simulation_id, simulation_rounds=simulation_rounds)
+
+    def run_simulation(self) -> SimulationRounds:
+        """run the simulation
+
+        :return: simulation results
+        :rtype: RoundList
+        """
+        raise NotImplemented
+
+    def process_results(self):
+        """process simulation results"""
+        raise NotImplemented