Merged PR 384: #2563: notebook explaining how to get simulation information from PrimAITE

## Summary
*Replace this text with an explanation of what the changes are and how you implemented them. Can this impact any other parts of the codebase that we should keep in mind?*

## Test process
*How have you tested this (if applicable)?*

## Checklist
- [X] PR is linked to a **work item**
- [X] **acceptance criteria** of linked ticket are met
- [X] performed **self-review** of the code
- [X] written **tests** for any new functionality added with this PR
- [ ] updated the **documentation** if this PR changes or adds functionality
- [ ] written/updated **design docs** if this PR implements new functionality
- [ ] updated the **change log**
- [X] ran **pre-commit** checks for code style
- [ ] attended to any **TO-DOs** left in the code

#2563: notebook explaining how to get simulation information from PrimAITE

Related work items: #2563

src/primaite/notebooks/Getting-Information-Out-Of-PrimAITE.ipynb

@@ -0,0 +1,168 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting information out of PrimAITE"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Imports\n",
+    "import yaml\n",
+    "from primaite import PRIMAITE_CONFIG\n",
+    "\n",
+    "from primaite.config.load import data_manipulation_config_path\n",
+    "from primaite.session.environment import PrimaiteGymEnv\n",
+    "from primaite.simulator.network.hardware.nodes.host.computer import Computer\n",
+    "from notebook.services.config import ConfigManager\n",
+    "\n",
+    "cm = ConfigManager().update('notebook', {'limit_output': 50})  # limit output lines to 50 - for neatness\n",
+    "\n",
+    "# create the env\n",
+    "with open(data_manipulation_config_path(), 'r') as f:\n",
+    "    cfg = yaml.safe_load(f)\n",
+    "\n",
+    "env = PrimaiteGymEnv(env_config=cfg)\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualising the Simulation Network"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The network can be visualised by running the code below."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "env.game.simulation.network.draw()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Getting the state of a simulation object\n",
+    "\n",
+    "The state of the simulation object is used to determine the observation space used by agents.\n",
+    "\n",
+    "Any object created using the ``SimComponent`` class has a ``describe_state`` method which can show the state of the object.\n",
+    "\n",
+    "An example of such an object is ``Computer`` which inherits from ``SimComponent``. In the default network configuration, ``client_1`` is a Computer object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client_1: Computer = env.game.simulation.network.get_node_by_hostname(\"client_1\")\n",
+    "client_1.describe_state()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### More specific describe_state\n",
+    "\n",
+    "As you can see, the output from the ``describe_state`` method for the ``Computer`` object includes the describe state for all its components. This can cause a large describe state output.\n",
+    "\n",
+    "As stated, the ``describe_state`` can be called on any object that inherits ``SimComponent``. This can allow you retrieve the state of a specific item."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "client_1.file_system.describe_state()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## System Logs\n",
+    "\n",
+    "Objects that inherit from the ``Node`` class will inherit the ``sys_log`` attribute.\n",
+    "\n",
+    "This is to simulate the idea that items such as Computer, Routers, Servers, etc. have a logging system used to diagnose problems."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# store config\n",
+    "# this is to prevent the notebook from breaking your local settings\n",
+    "was_enabled = PRIMAITE_CONFIG[\"developer_mode\"][\"enabled\"]\n",
+    "was_syslogs_enabled = PRIMAITE_CONFIG[\"developer_mode\"][\"output_sys_logs\"]\n",
+    "\n",
+    "# enable dev mode so that the default config outputs are overridden for this demo\n",
+    "PRIMAITE_CONFIG[\"developer_mode\"][\"enabled\"] = True\n",
+    "PRIMAITE_CONFIG[\"developer_mode\"][\"output_sys_logs\"] = True\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "# Remake the environment\n",
+    "env = PrimaiteGymEnv(env_config=cfg)\n",
+    "\n",
+    "# get the example computer\n",
+    "client_1: Computer = env.game.simulation.network.get_node_by_hostname(\"client_1\")\n",
+    "\n",
+    "# show sys logs on terminal\n",
+    "client_1.sys_log.show()\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "# restore config\n",
+    "PRIMAITE_CONFIG[\"developer_mode\"][\"enabled\"] = was_enabled\n",
+    "PRIMAITE_CONFIG[\"developer_mode\"][\"output_sys_logs\"] = was_syslogs_enabled"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "venv",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}