Update docs

README.md

@@ -7,6 +7,9 @@
 ![os](https://img.shields.io/badge/OS-win%7Cmac%7Clinux-9cf)
 ![python](https://img.shields.io/badge/Python-3.10+-darkgreen)
 
+> **Note:** EOS is currently in the alpha development stage. Much additional functionality and enhancements are planned.
+> It currently has a core feature set to use for research. Please report any issues, make feature requests, or contribute to development!
+
 The Experiment Orchestration System (EOS) is a comprehensive software framework and runtime for laboratory automation, designed
 to serve as the foundation for one or more automated or self-driving labs (SDLs).
 

docs/index.rst

@@ -1,6 +1,12 @@
 The Experiment Orchestration System (EOS)
 =========================================
 
+.. note::
+
+    EOS is currently in the alpha development stage.
+    Much additional functionality and enhancements are planned. It currently has a core feature set to use for research.
+    Please report any issues, make feature requests, or contribute to development!
+
 The Experiment Orchestration System (EOS) is a comprehensive software framework and runtime for laboratory automation, designed
 to serve as the foundation for one or more automated or self-driving labs (SDLs).
 

docs/user-guide/campaigns.rst

@@ -1,12 +1,13 @@
 Campaigns
 =========
-A campaign in EOS is an experiment that is executed multiple times in sequence. The parameters of the experiments usually
-differ. A campaign has some goals, such as to optimize some objectives by searching for optimal parameters.
+A campaign in EOS is an experiment that is executed multiple times in sequence.
+The parameters of the experiments usually differ.
+A campaign has some goals, such as to optimize some objectives by searching for optimal parameters.
 Campaigns are the highest-level execution unit in EOS, and can be used to implement autonomous (self-driving) labs.
 
-The DMTA loop is a common paradigm in autonomous experimentation and EOS campaigns can be used to implement it. EOS has
-built-in support for running campaigns of an experiment. In addition, EOS has a built-in Bayesian optimizer that can
-be used to optimize parameters.
+The DMTA loop is a common paradigm in autonomous experimentation and EOS campaigns can be used to implement it.
+EOS has built-in support for running campaigns of an experiment.
+In addition, EOS has a built-in Bayesian optimizer that can be used to optimize parameters.
 
 .. figure:: ../_static/img/dmta-loop.png
    :alt: The DMTA Loop
@@ -18,8 +19,8 @@ Both the "analyze" and "design" phases of the DMTA loop can be automated by opti
 This is natively supported by EOS through a built-in Bayesian optimizer that integrates with the campaign execution module.
 It is also possible to customize the optimization to incorporate custom algorithms such as reinforcement learning.
 
-Let's look at the color mixing experiment to see how a campaign with optimization can be set up. There are six dynamic
-parameters, which are the inputs of the optimization problem:
+Let's look at the color mixing experiment to see how a campaign with optimization can be set up.
+There are six dynamic parameters, which are the inputs of the optimization problem:
 
 .. code-block:: yaml
 
@@ -103,24 +104,28 @@ This setup is also summarized in the `optimizer.py` file adjacent to `experiment
 
         return constructor_args, BayesianSequentialOptimizer
 
-The `eos_create_campaign_optimizer` function is used to create the optimizer for the campaign. We can
-see that the inputs are composed of all the dynamic parameters in the experiment and the output is the "loss" output parameter
-from the "score_color" task. The objective of the optimizer (and the campaign) is to minimize this loss.
+The `eos_create_campaign_optimizer` function is used to create the optimizer for the campaign.
+We can see that the inputs are composed of all the dynamic parameters in the experiment and the output is the "loss"
+output parameter from the "score_color" task.
+The objective of the optimizer (and the campaign) is to minimize this loss.
 
 More about optimizers can be found in the Optimizers section.
 
 Automation Setup (Make and Test Phases)
 ---------------------------------------
-Execution of the automation is managed by EOS. The tasks and devices must be implemented by the user. Careful setup of
-the experiment is required to ensure that a campaign can be executed autonomously.
+Execution of the automation is managed by EOS.
+The tasks and devices must be implemented by the user.
+Careful setup of the experiment is required to ensure that a campaign can be executed autonomously.
 
 Some guidelines:
 
 * Each experiment should be standalone and should not depend on previous experiments.
 * Each experiment should leave the laboratory in a state that allows the next experiment to be executed.
-* Dependencies between tasks should be minimized. A task should have a dependency on another task only if it is necessary.
-* Tasks should depend on any devices that they may be interacting with, even if they are not operating them. For example,
-  if a robot transfer task takes a container from device A to device B, then the robot arm and both devices A and B should be required
-  devices for the task.
-* Branches and loops are not supported. If these are needed, they should be encapsulated inside large tasks that may use
-  many devices and may represent several steps in the experiment.
+* Dependencies between tasks should be minimized.
+  A task should have a dependency on another task only if it is necessary.
+* Tasks should depend on any devices that they may be interacting with, even if they are not operating them.
+  For example, if a robot transfer task takes a container from device A to device B, then the robot arm and both devices
+  A and B should be required devices for the task.
+* Branches and loops are not supported.
+  If these are needed, they should be encapsulated inside large tasks that may use many devices and may represent
+  several steps in the experiment.

docs/user-guide/configuration.rst

@@ -5,7 +5,7 @@ After installation, you need to configure external services such as MongoDB and
 
 1. Configure External Services
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-We provide a Docker Compose file that can run all external services for you.
+We provide a Docker Compose file that can run the external services.
 
 Copy the example environment file:
 

docs/user-guide/devices.rst

@@ -1,24 +1,28 @@
 Devices
 =======
-In EOS, a device is an abstraction for a physical or virtual apparatus. A device is used by one or more tasks to
-run some operations. Each device in EOS is managed by a dedicated process which is created the moment
-a laboratory definition is loaded. This process is usually implemented as a server and tasks call various functions
-from it. For example, there could be a device called "magnetic mixer", which communicates with a physical magnetic mixer via
+In EOS, a device is an abstraction for a physical or virtual apparatus.
+A device is used by one or more tasks to run some processes.
+Each device in EOS is managed by a dedicated process which is created when a laboratory definition is loaded.
+This process is usually implemented as a server and tasks call various functions from it.
+For example, there could be a device called "magnetic mixer", which communicates with a physical magnetic mixer via
 serial and provides functions such as `start`, `stop`, `set_time` and `set_speed`.
 
 .. figure:: ../_static/img/tasks-devices.png
    :alt: EOS Tasks and Devices
    :align: center
 
-In the figure above, we illustrate an example of devices and a task that uses these devices. The task in this example is
-Gas Chromatography (GC) sampling, which is implemented with a GC and a mobile manipulation robot for automating the
-sample injection with a syringe. Both the GC and the robot are physical devices, and each has a device implementation
-in EOS, which runs as a persistent process. Then, the GC Sampling task uses both of the EOS devices to automate the
-sample injection process.
+In the figure above, we illustrate an example of devices and a task that uses these devices.
+The task in this example is Gas Chromatography (GC) sampling, which is implemented with a GC and a mobile manipulation
+robot for automating the sample injection with a syringe.
+Both the GC and the robot are physical devices, and each has a device implementation in EOS, which runs as a persistent
+process.
+Then, the GC Sampling task uses both of the EOS devices to automate the sample injection process.
 
-Most often, an EOS device will represent a physical device in the lab. But this need not always be the case. A device
-in EOS can be used to represent anything that needs persistent state throughout one or more experiments. This could
-be an AI module that records inputs given to it. Remember that a device in EOS is a persistent process.
+Most often, an EOS device will represent a physical device in the lab.
+But this need not always be the case. A device in EOS can be used to represent anything that needs persistent state
+throughout one or more experiments.
+This could be an AI module that records inputs given to it.
+Remember that a device in EOS is a persistent process.
 
 Device Implementation
 ---------------------
@@ -100,8 +104,9 @@ There are functions required in every device implementation:
 
    * Should return any data needed to determine the state of the device (e.g., status and feedback)
 
-The magnetic mixer device also has the function `mix` for implementing the mixing operation. This function will be called
-by a task to mix the contents of a container. The `mix` function:
+The magnetic mixer device also has the function `mix` for implementing the mixing operation.
+This function will be called by a task to mix the contents of a container.
+The `mix` function:
 
 * Sends a command to lower-level driver with a specified mixing time and speed to operate the magnetic mixer
 * Updates container metadata with mixing details

docs/user-guide/experiments.rst

@@ -1,21 +1,24 @@
 Experiments
 ===========
-Experiments are a set of tasks that are executed in a specific order. Experiments are represented as directed
-acyclic graphs (DAGs) where nodes are tasks and edges are dependencies between tasks. Tasks part of an experiment can
-pass parameters and containers to each other using EOS' reference system. Task parameters may be fully defined, with
-values provided for all task parameters or they may be left undefined by denoting them as dynamic parameters. Experiments with
-dynamic parameters can be used to run campaigns of experiments, where an optimizer generates the values for the
-dynamic parameters across repeated experiments to optimize some objectives.
+Experiments are a set of tasks that are executed in a specific order.
+Experiments are represented as directed acyclic graphs (DAGs) where nodes are tasks and edges are dependencies between tasks.
+Tasks part of an experiment can pass parameters and containers to each other using EOS' reference system.
+Task parameters may be fully defined, with values provided for all task parameters or they may be left undefined by
+denoting them as dynamic parameters.
+Experiments with dynamic parameters can be used to run campaigns of experiments, where an optimizer generates the values
+for the dynamic parameters across repeated experiments to optimize some objectives.
 
 .. figure:: ../_static/img/experiment-graph.png
    :alt: Example experiment graph
    :align: center
 
-Above is an example of a possible experiment that could be implemented with EOS. There is a series of tasks, each
-requiring one or more devices. In addition to the task precedence dependencies with edges shown in the graph, there can
-also be dependencies in the form of parameters and containers passed between tasks. For example, the task "Mix Solutions"
-may take as input parameters the volumes of the solutions to mix, and these values may be output from the "Dispense Solutions"
-task. Tasks can reference input/output parameters and containers from other tasks.
+Above is an example of a possible experiment that could be implemented with EOS.
+There is a series of tasks, each requiring one or more devices.
+In addition to the task precedence dependencies with edges shown in the graph, there can also be dependencies in the
+form of parameters and containers passed between tasks.
+For example, the task "Mix Solutions" may take as input parameters the volumes of the solutions to mix, and these values
+may be output from the "Dispense Solutions" task.
+Tasks can reference input/output parameters and containers from other tasks.
 
 Experiment Implementation
 -------------------------
@@ -25,7 +28,8 @@ Experiment Implementation
 
 YAML File (experiment.yml)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
-Defines the experiment. Specifies the experiment type, labs, container initialization (optional), and tasks
+Defines the experiment.
+Specifies the experiment type, labs, container initialization (optional), and tasks
 
 Below is an example experiment YAML file for an experiment to optimize parameters to synthesize a specific color:
 
@@ -182,8 +186,10 @@ Let's dissect this file:
     labs:
       - color_lab
 
-Every experiment has a type. The type is used to essentially identify the class of experiment. When an experiment is running
-then there are instances of the experiment with different IDs. Each experiment also requires one or more labs.
+Every experiment has a type.
+The type is used to essentially identify the class of experiment.
+When an experiment is running then there are instances of the experiment with different IDs.
+Each experiment also requires one or more labs.
 
 Now let's look at the first task in the experiment:
 
@@ -207,12 +213,14 @@ Now let's look at the first task in the experiment:
         target_location: color_dispenser
       dependencies: []
 
-The first task is named `retrieve_container` and is of type `Retrieve Container`. This task uses the robot arm to get
-a random container from storage. The task requires two devices, the robot arm and the container storage. There are five
-containers passed to it, "c_a" through "c_e". There is also a parameter `target_location` that is set to `color_dispenser`.
+The first task is named `retrieve_container` and is of type `Retrieve Container`.
+This task uses the robot arm to get a random container from storage.
+The task requires two devices, the robot arm and the container storage.
+There are five containers passed to it, "c_a" through "c_e".
+There is also a parameter `target_location` that is set to `color_dispenser`.
 This task has no dependencies as it is the first task in the experiment and is essentially a container feeder.
-There are five containers in storage, and one of them is chosen at random for the experiment. All five containers in our
-"color lab" are passed to this task, as any one of them could be chosen.
+There are five containers in storage, and one of them is chosen at random for the experiment.
+All five containers in our "color lab" are passed to this task, as any one of them could be chosen.
 
 Let's look at the next task:
 
@@ -233,12 +241,14 @@ Let's look at the next task:
       black_volume: eos_dynamic
     dependencies: [retrieve_container]
 
-This task takes the container from the `retrieve_container` task and dispenses colors into it. The task has an
-input container called "beaker" which references the output container named "beaker" from the `retrieve_container` task.
+This task takes the container from the `retrieve_container` task and dispenses colors into it.
+The task has an input container called "beaker" which references the output container named "beaker" from the
+`retrieve_container` task.
 If we look at the `task.yml` file of the task `Retrieve Container` we would see that a container named "beaker" is
-defined in `output_containers`. There are also four parameters, the CMYK volumes to dispense. All these parameters are
-set to `eos_dynamic`, which is a special keyword in EOS for defining dynamic parameters, instructing the system that
-these parameters must be specified either by the user or an optimizer before an experiment is run.
+defined in `output_containers`.
+There are also four parameters, the CMYK volumes to dispense.
+All these parameters are set to `eos_dynamic`, which is a special keyword in EOS for defining dynamic parameters,
+instructing the system that these parameters must be specified either by the user or an optimizer before an experiment is run.
 
 Optimizer File (optimizer.py)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/user-guide/index.rst

@@ -7,6 +7,7 @@ User Guide
    installation
    configuration
    running
+   infrastructure_setup
 
 .. toctree::
     :caption: Concepts
@@ -19,6 +20,11 @@ User Guide
     campaigns
     optimizers
 
+.. toctree::
+    :caption: Interfaces
+
+    rest_api
+
 .. toctree::
     :caption: Advanced
 

docs/user-guide/infrastructure_setup.rst

@@ -0,0 +1,23 @@
+Infrastructure Setup
+====================
+It is critical to setup the computational and network infrastructure appropriately to ensure that EOS can access required
+laboratory devices and computers as well as to ensure security.
+
+EOS requires access to other laboratory computers that are needed to interface with laboratory apparatuses.
+EOS knows what these computers are from a :doc:`laboratory YAML file <laboratories>`.
+
+The following are important points for setting up the computational and network infrastructure for EOS:
+
+#. EOS should be set up in an isolated or secured (appropriately firewalled) LAN to prevent unauthorized access.
+#. All laboratory computers that EOS will control should be in the same LAN.
+#. All laboratory computers should have a static IP address so that EOS can identify them.
+#. EOS must have full bi-directional network access to the laboratory computers.
+   All ports should be accessible.
+   This will likely require firewall reconfiguration.
+#. Power management settings may need to be altered to prevent computers from hibernating if automation will be running
+   for a long time.
+
+.. figure:: ../_static/img/lab-lan.png
+   :alt: Example LAN setup for EOS
+   :scale: 75%
+   :align: center

docs/user-guide/installation.rst

@@ -1,15 +1,15 @@
 Installation
 ============
 
-EOS should be installed on a capable computer in the laboratory. We recommend a central
-computer that is easily accessible.
+EOS should be installed on a capable computer in the laboratory.
+We recommend a central computer that is easily accessible.
 
 .. note::
     If EOS will be connecting to other computers to run automation, then you must ensure that the computer where EOS
     is installed has bi-directional network access to the other computers.
 
     We strongly recommend that the laboratory has its own isolated network for security and performance reasons.
-    See our infrastructure setup guide for more information.
+    See :doc:`infrastructure setup <infrastructure_setup>` for more information.
 
 EOS also requires a MongoDB database, a MinIO object storage server, and (for now) Budibase for the web UI.
 We provide a Docker Compose file that can set up all of these services for you.