Merge pull request #48 from NREL/feat/parameterization

Support zip parameterization

Author: daniel-thom

docs/src/reference/parameterization.md

@@ -323,6 +323,84 @@ job "train_lr{lr:.4f}_bs{batch_size}" {
 }
 ```
 
+## Parameter Modes
+
+By default, when multiple parameters are specified, Torc generates the Cartesian product of all parameter values. You can change this behavior using `parameter_mode`.
+
+### Product Mode (Default)
+
+The default mode generates all possible combinations:
+
+```yaml
+jobs:
+  - name: job_{a}_{b}
+    command: echo {a} {b}
+    parameters:
+      a: "[1, 2, 3]"
+      b: "['x', 'y', 'z']"
+    # parameter_mode: product  # This is the default
+```
+
+This creates 3 × 3 = **9 jobs**: `job_1_x`, `job_1_y`, `job_1_z`, `job_2_x`, etc.
+
+### Zip Mode
+
+Use `parameter_mode: zip` to pair parameters element-wise (like Python's `zip()` function). All parameter lists must have the same length.
+
+```yaml
+jobs:
+  - name: train_{dataset}_{model}
+    command: python train.py --dataset={dataset} --model={model}
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'cnn', 'transformer']"
+    parameter_mode: zip
+```
+
+This creates **3 jobs** (not 9):
+- `train_cifar10_resnet`
+- `train_mnist_cnn`
+- `train_imagenet_transformer`
+
+**When to use zip mode:**
+- Pre-determined parameter pairings (dataset A always uses model X)
+- Corresponding input/output file pairs
+- Parallel arrays where position matters
+
+**Error handling:**
+If parameter lists have different lengths in zip mode, Torc will return an error:
+```
+All parameters must have the same number of values when using 'zip' mode.
+Parameter 'dataset' has 3 values, but 'model' has 2 values.
+```
+
+### KDL Syntax
+
+```kdl
+job "train_{dataset}_{model}" {
+    command "python train.py --dataset={dataset} --model={model}"
+    parameters {
+        dataset "['cifar10', 'mnist', 'imagenet']"
+        model "['resnet', 'cnn', 'transformer']"
+    }
+    parameter_mode "zip"
+}
+```
+
+### JSON5 Syntax
+
+```json5
+{
+  name: "train_{dataset}_{model}",
+  command: "python train.py --dataset={dataset} --model={model}",
+  parameters: {
+    dataset: "['cifar10', 'mnist', 'imagenet']",
+    model: "['resnet', 'cnn', 'transformer']"
+  },
+  parameter_mode: "zip"
+}
+```
+
 ## Best Practices
 
 1. **Use descriptive parameter names** - `lr` not `x`, `batch_size` not `b`
@@ -332,3 +410,4 @@ job "train_lr{lr:.4f}_bs{batch_size}" {
 5. **Consider parameter dependencies** - Some parameter combinations may be invalid
 6. **Prefer shared parameters for multi-job workflows** - Use `use_parameters` to avoid repeating definitions
 7. **Use selective inheritance** - Only inherit the parameters each job actually needs
+8. **Use zip mode for paired parameters** - When parameters have a 1:1 correspondence, use `parameter_mode: zip`

docs/src/tutorials/simple-params.md

@@ -254,6 +254,32 @@ Torc creates these relationships:
 
 Each chain is independent—`eval_2` doesn't wait for `train_1`.
 
+## Parameter Modes: Product vs Zip
+
+By default, multiple parameters create a **Cartesian product** (all combinations). For **paired parameters**, use `parameter_mode: zip`:
+
+```yaml
+jobs:
+  # Default (product): 3 × 3 = 9 jobs
+  - name: train_{dataset}_{model}
+    command: python train.py --dataset={dataset} --model={model}
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'vgg', 'transformer']"
+
+  # Zip mode: 3 paired jobs (cifar10+resnet, mnist+vgg, imagenet+transformer)
+  - name: paired_{dataset}_{model}
+    command: python train.py --dataset={dataset} --model={model}
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'vgg', 'transformer']"
+    parameter_mode: zip
+```
+
+Use zip mode when parameters have a 1:1 correspondence (e.g., input/output file pairs, pre-determined configurations).
+
+See [Parameterization Reference](../reference/parameterization.md#parameter-modes) for details.
+
 ## What You Learned
 
 In this tutorial, you learned:
@@ -263,6 +289,7 @@ In this tutorial, you learned:
 - ✅ Format specifiers (`{i:03d}`, `{lr:.4f}`) for consistent naming
 - ✅ How parameterized files create one-to-one dependencies
 - ✅ The efficiency of parameter-matched dependencies (each chain runs independently)
+- ✅ The difference between product (default) and zip parameter modes
 
 ## Next Steps
 

examples/json/zip_parameter_mode.json5

@@ -0,0 +1,56 @@
+{
+  // Zip Parameter Mode Example
+  // Demonstrates using parameter_mode: "zip" for paired parameter expansion
+  //
+  // When using Cartesian product (default): 3 datasets x 3 models = 9 jobs
+  // When using zip mode: 3 pairs = 3 jobs (dataset[i] paired with model[i])
+  //
+  // This is useful when you have pre-determined parameter combinations rather than
+  // wanting to test all possible combinations.
+
+  "name": "zip_parameter_example",
+  "description": "Example workflow demonstrating zip parameter mode for paired parameters",
+
+  "jobs": [
+    // Training jobs using zip mode - each dataset is paired with a specific model
+    // Instead of 3x3=9 combinations, we get exactly 3 jobs:
+    //   - cifar10 with resnet
+    //   - mnist with cnn
+    //   - imagenet with transformer
+    {
+      "name": "train_{dataset}_{model}",
+      "command": "python train.py --dataset={dataset} --model={model}",
+      "output_files": ["model_{dataset}_{model}"],
+      "parameters": {
+        "dataset": "['cifar10', 'mnist', 'imagenet']",
+        "model": "['resnet', 'cnn', 'transformer']"
+      },
+      "parameter_mode": "zip"
+    },
+    // Evaluation jobs also use zip mode to match the training jobs
+    {
+      "name": "evaluate_{dataset}_{model}",
+      "command": "python evaluate.py --model=/models/{dataset}_{model}.pt",
+      "depends_on": ["train_{dataset}_{model}"],
+      "input_files": ["model_{dataset}_{model}"],
+      "parameters": {
+        "dataset": "['cifar10', 'mnist', 'imagenet']",
+        "model": "['resnet', 'cnn', 'transformer']"
+      },
+      "parameter_mode": "zip"
+    }
+  ],
+
+  // File specifications also support zip mode
+  "files": [
+    {
+      "name": "model_{dataset}_{model}",
+      "path": "/models/{dataset}_{model}.pt",
+      "parameters": {
+        "dataset": "['cifar10', 'mnist', 'imagenet']",
+        "model": "['resnet', 'cnn', 'transformer']"
+      },
+      "parameter_mode": "zip"
+    }
+  ]
+}

examples/kdl/zip_parameter_mode.kdl

@@ -0,0 +1,48 @@
+// Zip Parameter Mode Example
+// Demonstrates using parameter_mode "zip" for paired parameter expansion
+//
+// When using Cartesian product (default): 3 datasets x 3 models = 9 jobs
+// When using zip mode: 3 pairs = 3 jobs (dataset[i] paired with model[i])
+//
+// This is useful when you have pre-determined parameter combinations rather than
+// wanting to test all possible combinations.
+
+name "zip_parameter_example"
+description "Example workflow demonstrating zip parameter mode for paired parameters"
+
+// Training jobs using zip mode - each dataset is paired with a specific model
+// Instead of 3x3=9 combinations, we get exactly 3 jobs:
+//   - cifar10 with resnet
+//   - mnist with cnn
+//   - imagenet with transformer
+job "train_{dataset}_{model}" {
+    command "python train.py --dataset={dataset} --model={model}"
+    output_files "model_{dataset}_{model}"
+    parameters {
+        dataset "['cifar10', 'mnist', 'imagenet']"
+        model "['resnet', 'cnn', 'transformer']"
+    }
+    parameter_mode "zip"
+}
+
+// Evaluation jobs also use zip mode to match the training jobs
+job "evaluate_{dataset}_{model}" {
+    command "python evaluate.py --model=/models/{dataset}_{model}.pt"
+    depends_on_job "train_{dataset}_{model}"
+    input_files "model_{dataset}_{model}"
+    parameters {
+        dataset "['cifar10', 'mnist', 'imagenet']"
+        model "['resnet', 'cnn', 'transformer']"
+    }
+    parameter_mode "zip"
+}
+
+// File specifications also support zip mode
+file "model_{dataset}_{model}" {
+    path "/models/{dataset}_{model}.pt"
+    parameters {
+        dataset "['cifar10', 'mnist', 'imagenet']"
+        model "['resnet', 'cnn', 'transformer']"
+    }
+    parameter_mode "zip"
+}

examples/yaml/diamond_workflow.yaml

@@ -39,19 +39,19 @@ jobs:
 # File definitions - representing the data files in the workflow
 files:
   - name: f1
-    path: /Users/dthom/repos/torc/f1.json
+    path: f1.json
 
   - name: f2
-    path: /Users/dthom/repos/torc/f2.json
+    path: f2.json
 
   - name: f3
-    path: /Users/dthom/repos/torc/f3.json
+    path: f3.json
 
   - name: f4
-    path: /Users/dthom/repos/torc/f4.json
+    path: f4.json
 
   - name: f5
-    path: /Users/dthom/repos/torc/f5.json
+    path: f5.json
 
   - name: f6
-    path: /Users/dthom/repos/torc/f6.json
+    path: f6.json

examples/yaml/zip_parameter_mode.yaml

@@ -0,0 +1,83 @@
+# Zip Parameter Mode Example
+# Demonstrates using parameter_mode: zip for paired parameter expansion
+#
+# When using Cartesian product (default): 3 datasets × 3 models = 9 jobs
+# When using zip mode: 3 pairs = 3 jobs (dataset[i] paired with model[i])
+#
+# This is useful when you have pre-determined parameter combinations rather than
+# wanting to test all possible combinations.
+
+name: zip_parameter_example
+description: Example workflow demonstrating zip parameter mode for paired parameters
+
+jobs:
+  # Setup job - runs once before all training jobs
+  - name: setup_environment
+    command: |
+      echo "Setting up training environment"
+      mkdir -p /models /results
+
+  # Training jobs using zip mode - each dataset is paired with a specific model
+  # Instead of 3×3=9 combinations, we get exactly 3 jobs:
+  #   - cifar10 with resnet
+  #   - mnist with cnn
+  #   - imagenet with transformer
+  - name: train_{dataset}_{model}
+    command: |
+      python train.py \
+        --dataset={dataset} \
+        --model={model} \
+        --output=/models/{dataset}_{model}.pt
+    depends_on:
+      - setup_environment
+    output_files:
+      - model_{dataset}_{model}
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'cnn', 'transformer']"
+    parameter_mode: zip
+
+  # Evaluation job that processes all models
+  # Note: This job uses the same parameters with zip mode to wait for the
+  # correct corresponding training jobs
+  - name: evaluate_{dataset}_{model}
+    command: |
+      python evaluate.py \
+        --model=/models/{dataset}_{model}.pt \
+        --output=/results/{dataset}_{model}_metrics.json
+    depends_on:
+      - train_{dataset}_{model}
+    input_files:
+      - model_{dataset}_{model}
+    output_files:
+      - metrics_{dataset}_{model}
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'cnn', 'transformer']"
+    parameter_mode: zip
+
+  # Final aggregation job
+  - name: aggregate_results
+    command: |
+      python aggregate.py \
+        --input-dir=/results \
+        --output=/results/summary.json
+    # Use regex to depend on all evaluation jobs
+    depends_on_regexes:
+      - "evaluate_.*"
+
+# File specifications also support zip mode
+files:
+  - name: model_{dataset}_{model}
+    path: /models/{dataset}_{model}.pt
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'cnn', 'transformer']"
+    parameter_mode: zip
+
+  - name: metrics_{dataset}_{model}
+    path: /results/{dataset}_{model}_metrics.json
+    parameters:
+      dataset: "['cifar10', 'mnist', 'imagenet']"
+      model: "['resnet', 'cnn', 'transformer']"
+    parameter_mode: zip

src/client/parameter_expansion.rs

@@ -235,6 +235,51 @@ pub fn cartesian_product(
     result
 }
 
+/// Zip parameter values together (like Python's zip function)
+/// All parameter lists must have the same length
+/// Given a map of parameter names to value lists, returns a vector where
+/// the i-th element contains the i-th value from each parameter
+pub fn zip_parameters(
+    params: &HashMap<String, Vec<ParameterValue>>,
+) -> Result<Vec<HashMap<String, ParameterValue>>, String> {
+    if params.is_empty() {
+        return Ok(vec![HashMap::new()]);
+    }
+
+    // Check that all parameter lists have the same length
+    let lengths: Vec<(&String, usize)> = params.iter().map(|(k, v)| (k, v.len())).collect();
+    let first_len = lengths[0].1;
+
+    for (name, len) in &lengths {
+        if *len != first_len {
+            return Err(format!(
+                "All parameters must have the same number of values when using 'zip' mode. \
+                 Parameter '{}' has {} values, but '{}' has {} values.",
+                lengths[0].0, first_len, name, len
+            ));
+        }
+    }
+
+    if first_len == 0 {
+        return Ok(vec![]);
+    }
+
+    // Convert HashMap to Vec for consistent ordering
+    let param_vec: Vec<(&String, &Vec<ParameterValue>)> = params.iter().collect();
+
+    // Zip the values together
+    let mut result = Vec::with_capacity(first_len);
+    for i in 0..first_len {
+        let mut combo = HashMap::new();
+        for (param_name, param_values) in &param_vec {
+            combo.insert((*param_name).clone(), param_values[i].clone());
+        }
+        result.push(combo);
+    }
+
+    Ok(result)
+}
+
 /// Substitute parameter values into a template string
 /// Supports both {param_name} and {param_name:format} syntax
 pub fn substitute_parameters(template: &str, params: &HashMap<String, ParameterValue>) -> String {