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

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 state which can show the state of the object.\n",
+    "\n",
+    "An example of such an object is ``Computer``. 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 describe state for the computer also includes the describe state for all the components (i.e. Software) within it. 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_logs`` property.\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
+}