docs on new release

Author: CamDavidsonPilon

developer-guide/20-User interface/05-api-reference.md

@@ -19,11 +19,9 @@ sidebar_class_name: sidebar-item--updated
 ```
   {
     "error": "Human-readable error message",
-    "error_info": {
-      "cause": "Human-readable cause (defaults to error if not set)",
-      "remediation": "Suggested fix or next step",
-      "status": integer,
-    }
+    "cause": "Human-readable cause (defaults to error if not set)",
+    "remediation": "Suggested fix or next step",
+    "status": integer,
   }
 
 ```
@@ -34,7 +32,6 @@ Use `/api/workers/...` for worker-only targets (experiment-scoped jobs/logs) and
 
 -----
 
-
 ## Get Automation Descriptors
 
 Get Automation Descriptors endpoint.
@@ -57,6 +54,21 @@ Get Automation Descriptors endpoint.
 
 _No response body example inferred._
 
+## Get Bioreactor Variable Descriptors
+
+Get Bioreactor Variable Descriptors endpoint.
+
+### Endpoint
+`GET /api/bioreactor/descriptors`
+
+### Response
+
+#### Success
+
+**Status:** `200 OK`
+
+_No response body example inferred._
+
 ## Get Chart Descriptors
 
 Get Chart Descriptors endpoint.
@@ -425,7 +437,8 @@ Create Experiment endpoint.
   "description": "<value>",
   "experiment": "<value>",
   "mediaUsed": "<value>",
-  "organismUsed": "<value>"
+  "organismUsed": "<value>",
+  "tags": "<value>"
 }
 ```
 
@@ -436,9 +449,7 @@ Create Experiment endpoint.
 **Status:** `201 Created`
 
 ```json
-{
-  "status": "success"
-}
+"<created_experiment>"
 ```
 
 ## Delete Experiment
@@ -508,7 +519,8 @@ Update Experiment endpoint.
 #### Request Body
 ```json
 {
-  "description": "<value>"
+  "description": "<value>",
+  "tags": "<value>"
 }
 ```
 
@@ -519,9 +531,7 @@ Update Experiment endpoint.
 **Status:** `200 OK`
 
 ```json
-{
-  "status": "success"
-}
+"<updated_experiment>"
 ```
 
 ## Get Recent Experiment Profile Runs
@@ -1215,6 +1225,15 @@ Update App endpoint.
 ### Endpoint
 `POST /api/system/update_next_version`
 
+### Request
+
+#### Request Body
+```json
+{
+  "units": "<value>"
+}
+```
+
 ### Response
 
 #### Success
@@ -1576,7 +1595,9 @@ Kills specified job on unit
 
 ```json
 {
-  "status": "success"
+  "unit": "<unit>",
+  "task_id": "<task_id>",
+  "result_url_path": "/unit_api/task_results/<task_id>"
 }
 ```
 
@@ -1604,7 +1625,9 @@ Kills specified job on unit
 
 ```json
 {
-  "status": "success"
+  "unit": "<unit>",
+  "task_id": "<task_id>",
+  "result_url_path": "/unit_api/task_results/<task_id>"
 }
 ```
 
@@ -2746,6 +2769,42 @@ Get Experiment Assignment For Worker endpoint.
 "<result>"
 ```
 
+## Update Bioreactor On Unit
+
+Update Bioreactor On Unit endpoint.
+
+### Endpoint
+`PATCH /api/workers/{pioreactor_unit}/experiments/{experiment}/bioreactor`
+
+### Request
+
+#### Path Parameters
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| pioreactor_unit | string | Yes | Unit name or `$broadcast` where supported. |
+| experiment | string | Yes | Experiment identifier. |
+
+#### Request Body
+```json
+{
+  "values": "<value>"
+}
+```
+
+### Response
+
+#### Success
+
+**Status:** `202 Accepted`
+
+```json
+{
+  "unit": "<unit>",
+  "task_id": "<task_id>",
+  "result_url_path": "/unit_api/task_results/<task_id>"
+}
+```
+
 ## Get Logs For Unit And Experiment
 
 Shows event logs from specific unit and experiment, uses pagination.
@@ -3272,7 +3331,9 @@ Kills specified job on unit
 
 ```json
 {
-  "status": "success"
+  "unit": "<unit>",
+  "task_id": "<task_id>",
+  "result_url_path": "/unit_api/task_results/<task_id>"
 }
 ```
 
@@ -3300,7 +3361,9 @@ Kills specified job on unit
 
 ```json
 {
-  "status": "success"
+  "unit": "<unit>",
+  "task_id": "<task_id>",
+  "result_url_path": "/unit_api/task_results/<task_id>"
 }
 ```
 

developer-guide/20-User interface/06-unit-api-reference.md

@@ -17,15 +17,12 @@ sidebar_class_name: sidebar-item--updated
 ```
   {
     "error": "Human-readable error message",
-    "error_info": {
-      "cause": "Human-readable cause (defaults to error if not set)",
-      "remediation": "Suggested fix or next step",
-      "status": integer,
-    }
+    "cause": "Human-readable cause (defaults to error if not set)",
+    "remediation": "Suggested fix or next step",
+    "status": integer,
   }
 
 ```
-
 ## Get All Active Calibrations
 
 Get All Active Calibrations endpoint.
@@ -166,6 +163,65 @@ Set Active Estimator endpoint.
 }
 ```
 
+## Get Bioreactor Values
+
+Get Bioreactor Values endpoint.
+
+### Endpoint
+`GET /unit_api/bioreactor/experiments/{experiment}`
+
+### Request
+
+#### Path Parameters
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| experiment | string | Yes | Experiment identifier. |
+
+### Response
+
+#### Success
+
+**Status:** `200 OK`
+
+```json
+{
+  "values": "<value>"
+}
+```
+
+## Update Bioreactor Values
+
+Update Bioreactor Values endpoint.
+
+### Endpoint
+`PATCH /unit_api/bioreactor/experiments/{experiment}`
+
+### Request
+
+#### Path Parameters
+| Name | Type | Required | Description |
+| ---- | ---- | -------- | ----------- |
+| experiment | string | Yes | Experiment identifier. |
+
+#### Request Body
+```json
+{
+  "values": "<value>"
+}
+```
+
+### Response
+
+#### Success
+
+**Status:** `200 OK`
+
+```json
+{
+  "status": "success"
+}
+```
+
 ## Get Calibration Protocols
 
 Get Calibration Protocols endpoint.

static/img/user-guide/02-experiment-basics/04-set-up-an-experiment/start-new-experiment-dropdown-framed.png

@@ -10,13 +10,21 @@ import Admonition from '@theme/Admonition';
 
 ### Creating an experiment
 
-1. To create a new experiment, click on the drop-down menu on the top of the left-hand bar. Click the "New experiment" button.
+To create your first experiment, open the experiment selector in the top-left corner of the UI and choose **Start a new experiment**. This appears as the first item in the dropdown above your other experiments.
 
-![](/img/user-guide/02-experiment-basics/04-set-up-an-experiment/start_new_experiment.png)
+![](/img/user-guide/02-experiment-basics/04-set-up-an-experiment/start-new-experiment-dropdown-framed.png)
 
-2. On the next screen, enter your new experiment name. This name should be unique from prior experiment names. Enter optional metadata about your experiment; you can modify the description later, if necessary. Click "Save" when done.
+On **Start a new experiment**:
 
-![](/img/user-guide/02-experiment-basics/04-set-up-an-experiment/create_new_experiment_page.png)
+1. Enter a unique experiment name.
+2. Optionally add a description. This can be edited later.
+3. Optionally add tags. Press `Enter` or type a comma after each tag to save it.
+4. If you want to reuse setup details from a previous run, click **Populate with previous experiment**.
+5. Click **Save**.
+
+Tags are useful for grouping related experiments across time. For example, you might tag experiments by strain, media, operator, protocol, or project name.
+
+After saving, you can come back to the experiment later from **Experiments**. Tags make it easier to find related runs when your list grows.
 
 
 ### Assigning Pioreactors to your experiment

static/img/user-guide/02-experiment-basics/07-experiments-page/experiments-page-overview-framed.png

@@ -0,0 +1,28 @@
+---
+title: The Experiments page
+slug: /experiments-page
+hide_table_of_contents: true
+---
+
+Use **Experiments** to find active and previous runs, jump back into an experiment, and start a new one when needed.
+
+![](/img/user-guide/02-experiment-basics/07-experiments-page/experiments-page-overview-framed.png)
+
+At the top of **Experiments**, you can:
+
+1. Click **New experiment** to open [**Start a new experiment**](/user-guide/set-up-an-experiment).
+2. Search by experiment name or description.
+3. Filter the table by status with **all**, **active**, and **inactive**.
+4. Filter by tags to show only experiments that match a tag or set of tags.
+
+Each row shows the experiment name, description, tags, creation time, and whether the experiment is currently active.
+
+Click an experiment name to open that experiment. Use **More actions** for experiment-specific actions available in the UI.
+
+## Using tags
+
+Tags help group related work across many runs. You might use tags for strain names, media recipes, operators, projects, or protocols.
+
+![](/img/user-guide/02-experiment-basics/07-experiments-page/experiments-page-tags-open-framed.png)
+
+Open **Filter by tags** and select one or more tags to narrow the list. This is useful when your cluster has many past experiments and you want to quickly find a subset without searching by the full experiment name.

static/img/user-guide/02-experiment-basics/07-experiments-page/experiments-page-tags-open-framed.png

@@ -7,6 +7,8 @@ hide_table_of_contents: true
 
 When pairing the Pioreactor with dosing pumps, there are new capabilities and experiments you can run. The Pioreactor is pre-programmed with the following dosing automations. In the below automations, values highlighted `like so` are configurable.
 
+Before starting a dosing automation from the UI, review the `Current volume` and `Max working volume` fields in the automation dialog. `Current volume` should match the liquid currently in the vial, and `Max working volume` should match the volume set by the height of your waste / efflux tube.
+
 ## Available dosing automations
 
 
@@ -47,9 +49,22 @@ The chemostat automation is the second simplest dosing automation. Every `durati
     * one labelled "media"
 
 
-A turbidostat ("turbidity-static") tries to keep the turbidity (the optical density, or OD), constant over time. This is usually accomplished by taking frequent measurements of the turbidity (every 15 seconds), and performing a set media/waste pump cycle if the optical density (or normalized optical density) exceeds a `target OD` (or `target nOD`). The amount exchanged is the `volume` parameter (mL). For very fast growing cultures, we recommend a `volume` between 1.0 ml and 2.0 ml.
+A turbidostat ("turbidity-static") tries to keep the biomass constant over time. This is usually accomplished by taking frequent measurements (every 15 seconds), and performing a set media / waste pump cycle if the selected `biomass signal` exceeds the `target biomass`. The amount exchanged each time is the `exchange volume` parameter (mL). For very fast growing cultures, we recommend an `exchange volume` between 1.0 mL and 2.0 mL.
+
+This automation will always move the full `exchange volume`, even if it's not enough for the measured biomass to drop below the `target biomass`. If that happens, the automation will trigger again after the next check.
+
+The current turbidostat fields in the UI are:
+
+ - `exchange volume`: how much media and waste to move in each dilution cycle, in mL.
+ - `target biomass`: the biomass threshold that triggers a dilution cycle.
+ - `biomass signal`: which biomass estimate to monitor. `auto` will prefer `od_fused` when an active OD fused estimator is available, then `od` when an active OD calibration is available for the resolved signal channel, and otherwise falls back to `normalized_od`.
+
+When `biomass signal` is set to:
 
-This automation will always dose the `volume` parameter, even if it's not enough for the OD to drop below the `target OD`. If that happens, then `OD > target OD`, and so the automation will trigger after the next check (30 seconds).
+ - `normalized_od`: the automation compares against normalized OD.
+ - `od_fused`: the automation compares against the fused OD estimator.
+ - `od`: the automation compares against calibrated OD from the resolved OD channel.
+ - `auto`: the automation chooses the most specific available signal automatically.
 
 ### PID Morbidostat
 
@@ -96,13 +111,13 @@ To further avoid overflow, we limit how much liquid is added in a single pump cy
 ###  Volume parameters
 
 
- - **Initial volume**: this is how much liquid is initially in the vial
+ - **Current volume**: this is how much liquid is currently in the vial when you start the automation.
  - **Max working volume**: the efflux tube's position determines the maximum volume your liquid volume will reach.
 
 
 ###  Configuration parameters
 
-You can edit these parameters in your config.ini files.
+You can edit these parameters in your config.ini files. For dosing runs started from the UI, `Current volume` and `Max working volume` can also be adjusted directly in the automation dialog before starting.
 
 
 #### Section `[dosing_automation.config]`
@@ -114,6 +129,6 @@ You can edit these parameters in your config.ini files.
 
 #### Section `[bioreactor]`
 
- - `max_volume_ml`: determined by the volume that just touches the outflow tube. I.e. if you where to keep running the waste pump, what would the stable volume be.
- - `initial_volume_ml`: the initial volume of liquid in the vial. This is used to calculate the volume of liquid in the vial at any given time.
- - `initial_alt_media_fraction`: the initial fraction of the alternative media in the vial. This is used to calculate the volume of alternative media in the vial at any given time.
+ - `max_working_volume_ml`: determined by the volume that just touches the outflow tube. I.e. if you were to keep running the waste pump, what would the stable volume be.
+ - `initial_volume_ml`: the initial volume of liquid in the vial. In the UI this is surfaced as `Current volume`, and is used to calculate the volume of liquid in the vial at any given time.
+ - `initial_alt_media_fraction`: the initial fraction of the alternative media in the vial. This is used to calculate the volume of alternative media in the vial at any given time.