Updates to documentation

docs/source/state_system.rst

@@ -0,0 +1,31 @@
+.. only:: comment
+
+    © Crown-owned copyright 2023, Defence Science and Technology Laboratory UK
+
+Simulation State
+==============
+
+``SimComponent``s in the simulation have a method called ``describe_state`` which returns a dictionary of the state of the component. This is used to report pertinent data that could impact agent's actions or rewards. For instance, the name and health status of a node is reported, which can be used by a reward function to punish corrupted or compromised nodes and reward healthy nodes. Each ``SimComponent`` reports not only it's own attributes in the state but also that of its child components. I.e. a computer node will report the state of its ``FileSystem``, and the ``FileSystem`` will report the state of its files and folders. This happens by recursively calling childrens' own ``describe_state`` methods.
+
+The game layer calls ``describe_state`` on the trunk ``SimComponent`` (the top-level parent) and then pass the state to the agents once per simulation step. For this reason, all ``SimComponent``s must have a ``describe_state`` method, and they must all be linked to the trunk ``SimComponent``.
+
+This code snippet demonstrates how the state information is defined within the ``SimComponent`` class:
+
+.. code-block:: python
+
+    class Node(SimComponent):
+        operating_state: NodeOperatingState = NodeOperatingState.OFF
+        services: Dict[str, Service] = {}
+
+        def describe_state(self) -> Dict:
+            state = super().describe_state()
+            state["operating_state"] = self.operating_state.value
+            state["services"] = {uuid: svc.describe_state() for uuid, svc in self.services.items()}
+            return state
+
+    class Service(SimComponent):
+        health_state: ServiceHealthState = ServiceHealthState.GOOD
+        def describe_state(self) -> Dict:
+            state = super().describe_state()
+            state["health_state"] = self.health_state.value
+            return state