doc: added state illustration

docs/The State Mechanism.ipynb

@@ -16,6 +16,8 @@
     "- operate on `States` and \n",
     "- return `States`.\n",
     "\n",
+    "<img src=\"https://autoresearch.github.io/autora/img/state_logic.png\" width=\"75%\" alt=\"State Logic\">\n",
+    "\n",
     "The `autora.state` submodule provides classes and functions to help build these functions. "
    ]
   },
@@ -327,7 +329,9 @@
    "source": [
     "### Use the `autora.state.on_state` decorator\n",
     "\n",
-    "`autora.state.on_state` is a wrapper for functions which allows them to accept `State` objects as the first argument.\n",
+    "`autora.state.on_state` is a wrapper for functions which allows them to accept `State` objects as the first argument. This decorator enables AutoRA components to retrieve relevant data from the state and add new data to it. \n",
+    "\n",
+    "<img src=\"https://autoresearch.github.io/autora/img/state_wrapper.png\" width=\"75%\" alt=\"State Wrapper Overview\">\n",
     "\n",
     "The most concise way to use it is as a decorator on the function where it is defined. You can specify how the \n",
     "returned values should be mapped to fields on the `State` using the `@autora.state.on_state(output=...)` argument."

docs/cli/index.md

@@ -1,4 +1,4 @@
-# Command Line Interface
+# Workflows for HPCs via the Command Line Interface
 
 Different parts of AutoRA experiments can require very different computational resources. For instance:
 

docs/index.md

@@ -1,12 +1,12 @@
-# Core Functionality
+# States & Workflow Mechanics
 
-AutoRA includes core functionality for running AutoRA experiments organized into these submodules:
+AutoRA includes core functionality for defining empirical research workflows. This core functionality is organized into these submodules:
 
-- `autora.state`, which underpins the unified `State` interface for writing experimentalists, experiment runners and 
+- `autora.variable`, for representing experimental metadata describing the type and domain of variables
+- `autora.state`, which underpins the unified `State` interface for interacting with experimentalists, experiment runners and 
   theorists
 - `autora.serializer`, utilities for saving and loading `States`
 - `autora.workflow`, command line tools for running experimentalists, experiment runners and theorists
-- `autora.variable`, for representing experimental metadata describing the type and domain of variables
 - `autora.utils`, utilities and helper functions not linked to any specific core functionality  
 
 It also provides some basic experimentalists in the `autora.experimentalist` submodule. However, most