Merge pull request #19 from DARPA-ASKEM/reorg

Preliminary help reorganization and updates

docs/models/configure-model.md → docs/config-and-intervention/configure-model.md

@@ -1,13 +1,21 @@
 ---
-title: "Configure a model"
+title: "Create and validate a model configuration"
 ---
 
-# Configure a model
+# Configure and validate a model
 
-Before you can simulate a model, you need to configure it to set the initial values and parameters for the condition you want to test.
+Before you can simulate a model, you need to configure it to set the initial values and parameters for the condition you want to test. You can use the Configure model operator to:
+
+- Select from previously saved configurations used in the current project.
+- Automatically extract a configuration from an optional document or dataset.
+- Manually enter values and account for uncertainty in any downstream simulations.
 
 ![Model configurations table showing the initial conditions and parameters for a default configuration](../img/models/configurations.png)
 
+## Create a model configuration
+
+### Configure model operator
+
 The Configure model operator takes a model as an input and outputs a model configuration. You can manually enter the variable and parameter values for the output configuration or automatically extract them from an optional document or dataset (such as a contact matrix or initial populations) input.
 
 ![](../img/models/model-configure-operator.png)
@@ -30,47 +38,52 @@ The Configure model operator takes a model as an input and outputs a model confi
 
 </div>
 
-??? list "To configure a model"
+???+ list "To configure a model"
 
     1. Add the model to a workflow graph.
     2. (Optional) Add a document or dataset from which you want to extract configuration values.
-    2. Right-click anywhere on the workflow graph and select **Work with model** > **Configure model**.
-    3. Connect the Model, Document, and Dataset operator outputs to the corresponding inputs on the Configure model operator. 
+    2. Right-click anywhere on the workflow graph and select **Config & Intervention** > **Configure model**.
+    3. Connect the Model and any Document and Dataset operator outputs to the corresponding inputs on the Configure model operator. 
     4. On the Configure model operator, click **Open**.
     5. Choose or edit the model configuration:
 
         === "Edit or create a model configuration"
         
-            1. In the Context section, enter a name for the new configuration.
-            2. Scroll down to the Initial variable values and Parameters sections.
-            3. Edit any of the variable or parameter values and, if needed, describe the source that informed your changes.
+            1. Scroll down to the Initials and Parameters sections and edit any of the values. If needed, describe the source that informed your changes.
                 + To change the type, use the dropdown list to select one of the following options: 
                     - **Constant**: Enter a single value and (optionally) increase/decrease it by a certain percent.
-                    - **Distribution**: Enter a minimum and maximum value.
-                    - **Time varying**: Enter a comma-separated list of values at different time steps in the format *timestep:value* (e.g., *0:25, 1:26, 2:27*).
-                + To edit matrix values, click :fontawesome-solid-table-cells-large:{ aria-hidden="true" } **Matrix** or click :fontawesome-solid-greater-than:{ alt="Expand" title="Expand" } at the beginning of the row.    
-            4. Repeat step c for each initial condition or parameter you want to change.
+                    - **Uniform**: Enter a minimum and maximum value.
+                + To edit matrix values, click :fontawesome-solid-greater-than:{ alt="Expand" title="Expand" } at the beginning of the row and then click :fontawesome-solid-table-cells-large:{ aria-hidden="true" } **Open matrix**.    
+            2. Repeat for each initial condition or parameter you want to change.
+            3. To save the configuration for re-use, click **Save** to update the selected configuration or **Save as** to create a new configuration.
 
         === "Extract configurations from inputs"
 
             ???+ tip
 
                 Extractions work best when the parameters in the inputs have descriptions and concepts.
 
-            1. Click :fontawesome-solid-arrow-right-from-bracket:{ aria-hidden="true"} **Extract configurations from inputs** to attempt to extract variable and parameter values from any attached documents or datasets.
+            1. Click **Extract from inputs** to attempt to extract variable and parameter values from any attached documents or datasets.
             2. Edit any of the variable or parameter values as needed.
 
         === "Choose an existing model configuration"
         
-            1. Review the Suggested configurations section. Click a configuration name to review its values.
-            2. Click **Apply configuration values** to choose an existing configuration as the output for this operator.
-
-
-    6. Click :material-play-outline:{ aria-hidden="true" } **Run**.
+            - Review the Configurations on the left. Click a configuration name to select it and review its values.
+
+### Use the model configuration output
+
+With the configure model output, you can:
+
+- [Edit a model](../modeling/edit-model.md)
+- [Stratify a model](../modeling/stratify-model.md)
+- [Validate a model configuration](#validate-a-model-configuration)
+- [Simulate a model](../simulation/simulate-model.md)
+- [Calibrate a model configuration](../simulation/calibrate-model.md)
+- [Optimize an intervention policy](../modeling/edit-model.md)
 
 ## Validate a model configuration
 
-You can use the Validate a model configuration operator to check if a population remains constant and identify non-negativity. You can also add more constraints to check additional conditions.
+You can use the Validate configuration operator to check if a population remains constant and identify non-negativity. You can also add more constraints to check additional conditions.
 
 <figure markdown>
 ![](../img/models/model-configuration-validate-operator.png)
@@ -83,7 +96,8 @@ You can use the Validate a model configuration operator to check if a population
 
     ---
 
-    Model configuration
+    - Model configuration
+    - Dataset (optional)
 
 -   :material-arrow-expand-right:{ .lg .middle aria-hidden="true" } __Outputs__
 
@@ -93,31 +107,29 @@ You can use the Validate a model configuration operator to check if a population
 
 </div>
 
-??? list "To validate a model configuration"
+???+ list "To validate a model configuration"
 
-    1. [Configure the model](#configure-a-model).
+    1. [Configure the model](#create-a-model-configuration).
 
         ??? tip
 
             The input configuration should include some distribution on the parameters to allow for an exploration of the parameter space.
 
-    2. Right-click anywhere on the workflow graph and select **Work with model** > **Validate configuration**.
+    2. Right-click anywhere on the workflow graph and select **Config & Intervention** > **Validate configuration**.
     3. Connect the Configure model output to the Validate configuration input.
-    4. Click **Review checks**.
     5. Edit the validation parameters:
 
+        - **Parameters of interest**: stricter checks are performed on selected parameters.
         - **Start** and **End time** 
-        - **Number of steps**
+        - **Number of timepoints**
         - **Tolerance**: the lower the value, the more potential boxes will be split from each variable's range, introducing more sampling and more dynamics.
-        - **Parameters of interest**: stricter checks are performed on selected parameters.
 
         ??? tip
 
             Lowering the tolerance and checking parameters of interest can significantly increase the time it takes to run the Validate configuration operator.
 
-    6. Click **Add another constraint** to specify a new constraint against which to test model configurations. Edit the constraint parameters.
-        - **Name of constant**
-        - **Constraint type**
+    6. Click **Add new check** to specify a new constraint against which to test model configurations. Edit the constraint parameters.
+        - **Constraint type** and **name of constant**
         - **Target**
         - **Start** and **End time**
         - **Lower** and **Upper bound**:

docs/config-and-intervention/create-intervention-policy.md

@@ -0,0 +1,61 @@
+---
+title: Create and optimize an intervention policy
+---
+
+# Create and optimize an intervention policy
+
+## Create an intervention policy
+
+More info coming soon.
+
+## Optimize an intervention policy
+
+When you optimize an intervention policy, you specify a set of constraints to find the optimal combination of parameters that match your objective.
+
+<figure markdown>![](../img/models/model-optimize-operator.png)<figcaption markdown>How it works: [PyCIEMSS](https://github.com/ciemss/pyciemss/blob/main/pyciemss/interfaces.py#L747) :octicons-link-external-24:{ alt="External link" title="External link" }</figcaption></figure>
+
+<div class="grid cards" markdown>
+
+-   :material-arrow-collapse-right:{ .lg .middle aria-hidden="true" } __Inputs__
+
+    ---
+
+    - Model configuration
+    - Intervention policy
+
+-   :material-arrow-expand-right:{ .lg .middle aria-hidden="true" } __Outputs__
+
+    ---
+
+    Optimized model configuration
+
+</div>
+
+???+ list "To optimize an intervention policy"
+
+    1. [Configure the model](../config-and-intervention/configure-model.md).
+    2. Right-click anywhere on the workflow graph and select **Simulation** > **Optimize intervention policy**.
+    3. Connect the Configure model output to the Optimize input.
+    4. Click **Edit**.
+    5. Configure the optimization settings as needed:
+
+        - **Start** and **End time**: Specify the simulation time range.
+        - **Number of samples to simulate model**: Enter the number of stochastic samples to draw from the model.
+        - **Solver method**: Choose whether to solve ordinary differential equations using [dopri5](https://en.wikipedia.org/wiki/Dormand-Prince_method) or [euler](https://en.wikipedia.org/wiki/Euler_method).
+
+    6. Specify your intervention policies:
+
+        - **Parameter**: the parameter you want to optimize.
+        - **Initial guess**: your initial guess for the optimization.
+        - **Lower** and **Upper bound**: how much the parameter can vary.
+        - **Start time**: the start time of the model.
+        
+        To set additional interventions, click :octicons-plus-24:{ aria-hidden="true" } **Add more interventions**.
+
+    7. Add a constraint that limits the optimized configuration:
+        - Select the **target variables**.
+        - Set the **Acceptable risk of failure** and **Threshold**.
+    8. Click :material-play-outline:{ aria-hidden="true" } **Run**.
+    9. Save the the results:
+        - Enter a **Model config name** and click **Save as new model configuration**.
+        - Click :fontawesome-solid-floppy-disk:{ aria-hidden="true" } **Save as new dataset**. 

docs/config-and-intervention/index.md

@@ -0,0 +1,10 @@
+---
+title: Configuration and intervention
+---
+
+# Configuration and intervention
+
+More info coming soon.
+
+- [Configure a model](configure-model.md)
+- [Create and optimize an intervention policy](create-intervention-policy.md)