Document the Environment Parameterization and Variable Propagation

Makefile

@@ -480,6 +480,8 @@ build/check-doc.build-stamp: doc/build/html/index.html doc/build/html/htmlcov/in
 	test -s doc/build/html/autoapi/mlos_viz/index.html
 	test -s doc/build/html/autoapi/mlos_viz/dabl/index.html
 	grep -q -e '--config CONFIG' doc/build/html//mlos_bench.run.usage.html
+	# Look for malformed rst links: `LinkName <LinkTarget>`_
+	if find doc/build/html -name '*.html' -print0 | xargs -0 grep -m1 '&gt;`_' | grep -m1 .; then echo "Bad links found"; false; fi
 	# Check doc logs for errors (but skip over some known ones) ...
 	@cat doc/build/log.txt \
 		| egrep -C1 -e WARNING -e CRITICAL -e ERROR \

mlos_bench/mlos_bench/config/__init__.py

@@ -197,9 +197,40 @@
      "current_dir": "$PWD",
      "some_expanded_var": "$some_var: $experiment_id",
      "location": "eastus",
+
+     // This can be specified in the CLI config or the globals config
+     "tunable_params_map": {
+        // a map of tunable_params variables to their covariant group names
+        "environment1_tunables": [
+            "covariant_group_name",
+            "another_covariant_group_name"
+        ],
+        "environment2_tunables": [
+            // empty list means no tunables
+            // are enabled for this environment
+            // during this experiment
+            // (e.g., only use defaults for this environment)
+        ],
    }
 
-There are additional details about variable propagation in the
+Users can have multiple global config files, each specified with a ``--globals``
+CLI arg or ``"globals"`` CLI config property.
+
+At runtime, parameters from these files will be combined into a single
+dictionary, in the order they appear, and pushed to the root
+:py:class:`Environment <mlos_bench.environments>`.
+
+Any global or :py:class:`~.Environment` parameter can also be overridden from
+the command line, by simply specifying ``--PARAMETER_NAME PARAMETER_VALUE``.
+
+Another common use of global config files is to store sensitive data (e.g.,
+passwords, tokens, etc.) that should not be version-controlled.
+
+This way, users can keep their experiment-specific parameters separately from
+the Environment configs making them more reusable.
+
+There are additional details about `Variable Propagation
+<../environments/index.html#variable-propagation>`_ in the
 :py:mod:`mlos_bench.environments` module.
 
 Well Known Variables
@@ -216,6 +247,13 @@
 - ``$trial_runner_id``: A unique identifier for the ``TrialRunner``.
     This can be useful when running multiple trials in parallel (e.g., to
     provision a numbered VM per worker).
+- ``$tunable_params_map``: A map of ``tunable_params`` ``$name`` to their list of covariant group names.
+    This is usually used in a CLI ``--config`` CLI config or ``--globals``
+    (e.g., "experiment") config file and is used to control what the
+    ``"tunable_params": $tunable_group_name`` specified in the the
+    :py:mod:`mlos_bench.environments` JSONC configs resolves to.
+    This can be used to control which tunables are enabled for tuning for an
+    experiment without having to change the underlying Environment config.
 
 Tunable Configs
 ^^^^^^^^^^^^^^^
@@ -353,4 +391,4 @@
 `mlos_bench/tests/config/README.md
 <https://github.com/microsoft/MLOS/tree/main/mlos_bench/mlos_bench/tests/config/>`_
 for additional documentation and examples in the source tree.
-"""
+"""  # pylint: disable=line-too-long # noqa: E501

mlos_bench/mlos_bench/config/environments/network/virtual-network-environment.jsonc

@@ -18,7 +18,7 @@
     "config": {
         // FIXME: There aren't currently any tunable params for the network environment.
         // But one is required to workaround a bug (#613) in the config storage layer.
-        "tunable_params": ["dummy_params"],
+        "tunable_params": ["dummy_params_group1"],
 
         // Typically don't want to deprovision the network environment on teardown
         // since other experiments in this same RG might be using it.

mlos_bench/mlos_bench/config/tunables/dummy-tunables.jsonc

@@ -1,6 +1,6 @@
 // FIXME: A workaround to a bug (#613) in the config system that requires non-empty configs.
 {
-    "dummy_params": {
+    "dummy_params_group1": {
         "cost": 0,
         "description": "Dummy parameter group to allow a non-empty config for testing creating singleton resources that have no tunable params.",
         "params": {
@@ -11,5 +11,35 @@
                 "default": "dummy"
             }
         }
+    },
+    "dummy_params_group2": {
+        "cost": 1,
+        "description": "Dummy parameter group for testing",
+        "params": {
+            "dummy_param_int": {
+                "description": "An integer dummy parameter.",
+                "type": "int",
+                "range": [0, 100],
+                "default": 0
+            },
+            "dummy_param_float": {
+                "description": "A float dummy parameter.",
+                "type": "float",
+                "range": [0, 1],
+                "default": 0.5
+            }
+        }
+    },
+    "dummy_params_group3": {
+        "cost": 1,
+        "description": "Another dummy parameter group for testing",
+        "params": {
+            "dummy_param3": {
+                "description": "One more dummy parameter.",
+                "type": "float",
+                "range": [-1, 1],
+                "default": 0.0
+            }
+        }
     }
 }