Merge pull request #715 from douglasjacobsen/workspace-precedence-docs

Update configuration precedence documentation

Author: rfbgo

lib/ramble/docs/configuration_files.rst

@@ -71,15 +71,24 @@ highest) Ramble contains the following scopes:
 5. **custom**: Stored in a custom directory, specified by ``--config-scope``.
    If multiple scopes are listed on the command line, they are ordered from lowest
    to highest precedence. Settings here override all previously defined scoped.
-6. **workspace configs dir**: Stored in ``$(workspace_root)/configs``
-   generally as a ``<config_section>.yaml`` file (i.e. ``variables.yaml``). These
-   settings apply to a specific workspace, and override all previous configuration
-   scopes.
+6. **included files in workspace configuration file**: Paths referred to in the
+   file from #7 above. For more information see the
+   :ref:`documentation for including external configuration files<workspace_including_external_files>`.
 7. **workspace configuration file**: Stored in
    ``$(workspace_root)/configs/ramble.yaml``. Configuration scopes defined within
    this config file override all previously defined configuration scopes.
-8. **command line**: Configuration options defined on the command line take
+8. **workspace configs dir**: Stored in ``$(workspace_root)/configs``
+   generally as a ``<config_section>.yaml`` file (i.e. ``variables.yaml``). These
+   settings apply to a specific workspace, and override all previous configuration
+   scopes.
+9. **command line**: Configuration options defined on the command line take
    precedence over all other scopes.
+10. **application / workload / experiment scope sections**: Several
+    configuration sections can be defined within the ``application``,
+    ``workload``, and ``experiment`` portions of the ``applications``
+    configuration section. These will override all other scopes. See the
+    :ref:`application section documentation<application-config>` for more
+    details.
 
 Each configuration directory may contain several configuration files, such as
 ``config.yaml``, ``variables.yaml``, or ``modifiers.yaml``. When configurations

lib/ramble/ramble/test/cmd/config.py

@@ -714,7 +714,7 @@ def test_config_remove_from_workspace(mutable_empty_config, mutable_mock_workspa
         config("rm", "config:dirty")
         output = config("get")
 
-    expected = ramble.workspace.default_config_yaml()
+    expected = ramble.workspace.Workspace._default_config_yaml()
     expected += """  config: {}
 """
     for line in io.StringIO(expected).readlines():

lib/ramble/ramble/test/cmd/workspace.py

@@ -2055,3 +2055,60 @@ def test_workspace_simplify():
     # ensure apps/pkgs/envs are not merged into workspace config from other config files
     assert search_files_for_string([ws_config_path], "app_not_in_ws_config") is False
     assert search_files_for_string([ws_config_path], "pkg_not_in_ws_config") is False
+
+
+def write_variables_config_file(file_path, levels, value):
+    with open(file_path, "w+") as f:
+        f.write("variables:\n")
+        for i in range(0, levels):
+            f.write(f"  scope{i}: {value}\n")
+
+
+def test_workspace_config_precedence(request, tmpdir):
+    workspace_name = request.node.name
+    ws = ramble.workspace.create(workspace_name)
+
+    global_args = ["-w", workspace_name]
+
+    # Highest precedence, experiment scope
+    workspace(
+        "manage",
+        "experiments",
+        "basic",
+        "--wf",
+        "test_wl",
+        "-e",
+        "unit-test",
+        "-v",
+        "n_nodes=1",
+        "-v",
+        "n_ranks=1",
+        "-v",
+        "scope0=experiment",
+        global_args=global_args,
+    )
+
+    # 2nd highest precedence, included (in an included path)
+    included_path = os.path.join(ws.root, "variables.yaml")
+    with open(ws.config_file_path, "a") as f:
+        f.write("  include:\n")
+        f.write(f"  - {included_path}\n")
+
+    write_variables_config_file(included_path, 2, "include_path")
+
+    # 3rd highest precedence, workspace overrides (in configs/variables.yaml)
+    workspace_overrides = os.path.join(ws.config_dir, "variables.yaml")
+    write_variables_config_file(workspace_overrides, 3, "workspace_overrides")
+
+    # 4th highest precedence, workspace (in ramble.yaml)
+    config("add", "variables:scope0:workspace", global_args=global_args)
+    config("add", "variables:scope1:workspace", global_args=global_args)
+    config("add", "variables:scope2:workspace", global_args=global_args)
+    config("add", "variables:scope3:workspace", global_args=global_args)
+
+    output = workspace("info", "-vv", global_args=global_args)
+
+    assert "scope0 = experiment" in output
+    assert "scope1 = include_path" in output
+    assert "scope2 = workspace_override" in output
+    assert "scope3 = workspace" in output

lib/ramble/ramble/workspace/__init__.py

@@ -27,7 +27,6 @@
     config_dict,
     create,
     deactivate,
-    default_config_yaml,
     exists,
     is_workspace_dir,
     get_workspace_path,
@@ -67,7 +66,6 @@
     "config_dict",
     "create",
     "deactivate",
-    "default_config_yaml",
     "exists",
     "is_workspace_dir",
     "get_workspace_path",

lib/ramble/ramble/workspace/workspace.py

@@ -106,74 +106,10 @@
 config_file_name = "ramble.yaml"
 licenses_file_name = "licenses.yaml"
 
-
-def default_config_yaml():
-    """default ramble.yaml file to put in new workspaces"""
-    return """\
-# This is a ramble workspace config file.
-#
-# It describes the experiments, the software stack
-# and all variables required for ramble to configure
-# experiments.
-# As an example, experiments can be defined as follows.
-# applications:
-#   hostname: # Application name, as seen in `ramble list`
-#     variables:
-#       iterations: '5'
-#     workloads:
-#       serial: # Workload name, as seen in `ramble info <app>`
-#         variables:
-#           type: 'test'
-#         experiments:
-#           single_node: # Arbitrary experiment name
-#             variables:
-#               n_ranks: '{processes_per_node}'
-
-ramble:
-  env_vars:
-    set:
-      OMP_NUM_THREADS: '{n_threads}'
-  variables:
-    mpi_command: mpirun -n {n_ranks}
-    batch_submit: '{execute_experiment}'
-    processes_per_node: 1
-  applications: {}
-  software:
-    packages: {}
-    environments: {}
-"""
-
-
 workspace_all_experiments_file = "all_experiments"
 
 workspace_execution_template = "execute_experiment" + workspace_template_extension
 
-shell = ramble.config.get("config:shell")
-shell_path = os.path.join("/bin/", shell)
-template_execute_script = (
-    f"#!{shell_path}\n"
-    + """\
-# This is a template execution script for
-# running the execute pipeline.
-#
-# Variables surrounded by curly braces will be expanded
-# when generating a specific execution script.
-# Some example variables are:
-#   - experiment_run_dir (Will be replaced with the experiment directory)
-#   - command (Will be replaced with the command to run the experiment)
-#   - log_dir (Will be replaced with the logs directory)
-#   - experiment_name (Will be replaced with the name of the experiment)
-#   - workload_run_dir (Will be replaced with the directory of the workload
-#   - application_name (Will be repalced with the name of the application)
-#   - n_nodes (Will be replaced with the required number of nodes)
-#   Any experiment parameters will be available as variables as well.
-
-cd "{experiment_run_dir}"
-
-{command}
-"""
-)
-
 #: Name of lockfile within a workspace
 lockfile_name = "ramble.lock"
 
@@ -557,7 +493,7 @@ def _read(self):
 
             read_default = not os.path.exists(self.config_file_path)
             if read_default:
-                self._read_config(config_section, default_config_yaml())
+                self._read_config(config_section, self._default_config_yaml())
             else:
                 with open(self.config_file_path) as f:
                     self._read_config(config_section, f)
@@ -588,7 +524,73 @@ def _read(self):
 
             if read_default_script:
                 template_name = workspace_execution_template[0:-ext_len]
-                self._read_template(template_name, template_execute_script)
+                self._read_template(template_name, self._template_execute_script())
+
+    @classmethod
+    def _template_execute_script(self):
+        shell = ramble.config.get("config:shell")
+        shell_path = os.path.join("/bin/", shell)
+        script = (
+            f"#!{shell_path}\n"
+            + """\
+# This is a template execution script for
+# running the execute pipeline.
+#
+# Variables surrounded by curly braces will be expanded
+# when generating a specific execution script.
+# Some example variables are:
+#   - experiment_run_dir (Will be replaced with the experiment directory)
+#   - command (Will be replaced with the command to run the experiment)
+#   - log_dir (Will be replaced with the logs directory)
+#   - experiment_name (Will be replaced with the name of the experiment)
+#   - workload_run_dir (Will be replaced with the directory of the workload
+#   - application_name (Will be repalced with the name of the application)
+#   - n_nodes (Will be replaced with the required number of nodes)
+#   Any experiment parameters will be available as variables as well.
+
+cd "{experiment_run_dir}"
+
+{command}
+"""
+        )
+
+        return script
+
+    @classmethod
+    def _default_config_yaml(self):
+        return """\
+# This is a ramble workspace config file.
+#
+# It describes the experiments, the software stack
+# and all variables required for ramble to configure
+# experiments.
+# As an example, experiments can be defined as follows.
+# applications:
+#   hostname: # Application name, as seen in `ramble list`
+#     variables:
+#       iterations: '5'
+#     workloads:
+#       serial: # Workload name, as seen in `ramble info <app>`
+#         variables:
+#           type: 'test'
+#         experiments:
+#           single_node: # Arbitrary experiment name
+#             variables:
+#               n_ranks: '{processes_per_node}'
+
+ramble:
+  env_vars:
+    set:
+      OMP_NUM_THREADS: '{n_threads}'
+  variables:
+    mpi_command: mpirun -n {n_ranks}
+    batch_submit: '{execute_experiment}'
+    processes_per_node: 1
+  applications: {}
+  software:
+    packages: {}
+    environments: {}
+"""
 
     def _read_application_config(self, path, f, raw_yaml=None):
         """Read an application configuration file"""