Merge pull request #510 from GoogleCloudPlatform/release-v0.5.0

Merge release v0.5.0 into main

.github/workflows/spelling.yaml

@@ -11,9 +11,9 @@ jobs:
   formatting:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Check Spelling
-      uses: crate-ci/typos@548ac37a5de9ce84871bf4db3c9b8c462896d480 # v1.16.24
+      uses: crate-ci/typos@v1.20.4
       with:
         files: ./lib/ramble/ramble ./lib/ramble/docs ./examples ./share ./bin ./etc ./var ./README.md
         config: ./.typos.toml

.typos.toml

@@ -17,6 +17,8 @@ extend-ignore-re = [
 "fom" = "fom"
 "namd" = "namd"
 "reord" = "reord"
+"PN" = "PN" # fixing tPN in IOR
+"repositor" = "repositor" # Fixing partial name without singular / plural suffix
 
 [default.extend-identifiers]
 "ATPase" = "ATPase"

AUTHORS

@@ -0,0 +1,7 @@
+# This is the list of Ramble's significant contributors.
+#
+# This does not necessarily list everyone who has contributed code,
+# especially since many employees of one corporation may be contributing.
+# To see the full list of contributors, see the revision history in
+# source control.
+Google LLC

LICENSE-APACHE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2022-2024 Google LLC.
+   Copyright 2022-2024 The Ramble Authors.
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

README.md

@@ -6,7 +6,7 @@ It works on Linux, macOS, and many supercomputers.
 Ramble can be used to configure a variety of experiments for applications.
 These can include anything from:
  - Scientific parameter sweeps
- - Performance focused scalaing studies
+ - Performance focused scaling studies
  - Compiler flag sweeps
 
 To install ramble and configure your experiment workspace, make sure you have

bin/ramble

@@ -1,5 +1,5 @@
 #!/bin/sh
-# Copyright 2022-2024 Google LLC
+# Copyright 2022-2024 The Ramble Authors
 #
 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 # https://www.apache.org/licenses/LICENSE-2.0> or the MIT license

bin/ramble-python

@@ -1,4 +1,4 @@
-# Copyright 2022-2024 Google LLC
+# Copyright 2022-2024 The Ramble Authors
 #
 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 # https://www.apache.org/licenses/LICENSE-2.0> or the MIT license

etc/ramble/defaults/spack.yaml

@@ -1,4 +1,3 @@
 spack:
-  concretized: false
   packages: {}
   environments: {}

examples/basic_expansion_config.yaml

@@ -29,16 +29,15 @@ ramble:
                 n_ranks: '1'
                 n_nodes: '1'
   spack:
-    concretized: true
     packages:
       gcc9:
         spack_spec: [email protected] target=x86_64
         compiler_spec: [email protected]
       ompi412:
         spack_spec: [email protected] +legacylaunchers +pmi +thread_multiple +cxx target=x86_64
         compiler: gcc9
-      impi2018:
-        spack_spec: intel-mpi@2018.4.274
+      impi2021:
+        spack_spec: intel-oneapi-mpi@2021.11.0
         compiler: gcc9
       openfoam:
         spack_spec: openfoam-org@7
@@ -57,5 +56,5 @@ ramble:
         - openfoam
       wrfv4:
         packages:
-        - impi2018
+        - impi2021
         - wrfv4

examples/basic_gromacs_config.yaml

@@ -38,13 +38,12 @@ ramble:
                 size: '0003'
                 type: 'rf'
   spack:
-    concretized: true
     packages:
       gcc9:
         spack_spec: [email protected] target=x86_64
         compiler_spec: [email protected]
-      impi2018:
-        spack_spec: intel-mpi@2018.4.274 target=x86_64
+      impi2021:
+        spack_spec: intel-oneapi-mpi@2021.11.0 target=x86_64
         compiler: gcc9
       gromacs:
         spack_spec: [email protected]
@@ -53,4 +52,4 @@ ramble:
       gromacs:
         packages:
         - gromacs
-        - impi2018
+        - impi2021

examples/basic_hostname_config.yaml

@@ -44,6 +44,5 @@ ramble:
                 n_nodes: '1'
                 processes_per_node: '16'
   spack:
-    concretized: true
     packages: {}
     environments: {}

examples/full_expansion_config.yaml

@@ -29,7 +29,6 @@ ramble:
                                 #(part1, 16, openfoam-skx, 2), (part1, 16, openfoam-skx, 4)
                                 #(part2, 32, openfoam-zen2, 2), (part2, 32, openfoam-zen2, 4)
   spack:
-    concretized: true
     packages:
       gcc9:
         spack_spec: [email protected] target=x86_64

examples/slurm_execute_experiment.tpl

@@ -1,6 +1,7 @@
 #!/bin/bash
 #SBATCH -N {n_nodes}
 #SBATCH --ntasks-per-node {processes_per_node}
+#SBATCH -p {partition_name}
 #SBATCH -J {application_name}_{workload_name}_{experiment_name}
 
 # This is a template execution script for
@@ -20,5 +21,6 @@
 
 cd {experiment_run_dir}
 
-{command}
+scontrol show hostnames > {experiment_run_dir}/hostfile
 
+{command}

examples/vector_gromacs_software_config.yaml

@@ -26,13 +26,12 @@ ramble:
               - n_ranks
               - gromacs_version
   spack:
-    concretized: true
     packages:
       gcc9:
         spack_spec: [email protected] target=x86_64
         compiler_spec: [email protected]
-      impi2018:
-        spack_spec: intel-mpi@2018.4.274 target=x86_64
+      impi2021:
+        spack_spec: intel-oneapi-mpi@2021.11.0 target=x86_64
         compiler: gcc9
       gromacs-{gromacs_version}:
         spack_spec: gromacs@{gromacs_version}
@@ -41,4 +40,4 @@ ramble:
       gromacs-{gromacs_version}:
         packages:
         - gromacs-{gromacs_version}
-        - impi2018
+        - impi2021

examples/vector_matrix_gromacs_config.yaml

@@ -23,13 +23,12 @@ ramble:
               - type
               - n_ranks
   spack:
-    concretized: true
     packages:
       gcc9:
         spack_spec: [email protected] target=x86_64
         compiler_spec: [email protected]
-      impi2018:
-        spack_spec: intel-mpi@2018.4.274 target=x86_64
+      impi2021:
+        spack_spec: intel-oneapi-mpi@2021.11.0 target=x86_64
         compiler: gcc9
       gromacs:
         spack_spec: [email protected]
@@ -38,4 +37,4 @@ ramble:
       gromacs:
         packages:
         - gromacs
-        - impi2018
+        - impi2021

lib/ramble/docs/conf.py

@@ -1,4 +1,4 @@
-# Copyright 2022-2024 Google LLC
+# Copyright 2022-2024 The Ramble Authors
 #
 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
 # https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
@@ -130,6 +130,7 @@ def setup(sphinx):
     "sphinx.ext.viewcode",
     "sphinxcontrib.programoutput",
     "sphinxcontrib.jquery",
+    "sphinx_copybutton",
 ]
 
 # Set default graphviz options
@@ -396,3 +397,9 @@ class RambleStyle(DefaultStyle):
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
 }
+
+# sphinx_copybutton
+# Do not copy the prompt, or any console outputs.
+copybutton_exclude = '.gp, .go'
+# Escape hatch for turning off the copy button.
+copybutton_selector = "div:not(.hide-copy) > div.highlight > pre"

lib/ramble/docs/configuration_files.rst

@@ -1,4 +1,4 @@
-.. Copyright 2022-2024 Google LLC
+.. Copyright 2022-2024 The Ramble Authors
 
    Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
    https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
@@ -54,31 +54,31 @@ Ramble provides several configuration scopes, which are used to denote
 precedence of configuration options. In precedence order (from lowest to
 highest) Ramble contains the following scopes:
 
-(1) **default**: Stored in ``$(prefix)/etc/ramble/defaults/``. These are the
-default settings provided with Ramble. Users should generally not modify these
-settings, and instead use a higher precedence configuration scope. These
-defaults will change from version to version of Ramble.
-(2) **system**: Store in ``/etc/ramble/``. These are Ramble settings for an
-entire machine. These settings are typically managed by a systems
-administrator, or something with root access on the machine. Settings defined
-in this scope override settings in the **default** scope.
-(3) **site**: Stored in ``$(prefix)/etc/ramble/``. Settings here only affect
-*this instance* of Ramble, and they override both the **default** and
-**system** scopes.
-(4) **user**: Stored in ``~/.ramble/``. Settings here only affect a specific
-user, and override **default**, **system**, and **site** 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.
-(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
-precedence over all other scopes.
+1. **default**: Stored in ``$(prefix)/etc/ramble/defaults/``. These are the
+   default settings provided with Ramble. Users should generally not modify these
+   settings, and instead use a higher precedence configuration scope. These
+   defaults will change from version to version of Ramble.
+2. **system**: Store in ``/etc/ramble/``. These are Ramble settings for an
+   entire machine. These settings are typically managed by a systems
+   administrator, or something with root access on the machine. Settings defined
+   in this scope override settings in the **default** scope.
+3. **site**: Stored in ``$(prefix)/etc/ramble/``. Settings here only affect
+   *this instance* of Ramble, and they override both the **default** and
+   **system** scopes.
+4. **user**: Stored in ``~/.ramble/``. Settings here only affect a specific
+   user, and override **default**, **system**, and **site** 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.
+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
+   precedence over all other scopes.
 
 Each configuration directory may contain several configuration files, such as
 ``config.yaml``, ``variables.yaml``, or ``modifiers.yaml``. When configurations
@@ -262,9 +262,14 @@ The format of this config section is as follows:
 The above example is general, and intended to show the available functionality
 of configuring environment variables. Below the ``env_vars`` level, one of four
 actions is available. These actions are:
-* ``set`` - Define a variable equal to a given value. Overwrites previously configured values
-* ``append`` - Append the given value to the end of a previous variable definition. Delimited for vars is defined by ``var_separator``, ``paths`` uses ``:``
-* ``prepend`` - Prepent the given value to the beginning of a previous variable definition. Only supports paths, delimiter is ``:``
+
+* ``set`` - Define a variable equal to a given value. Overwrites previously
+  configured values
+* ``append`` - Append the given value to the end of a previous variable
+  definition. Delimited for vars is defined by ``var_separator``, ``paths``
+  uses ``:``
+* ``prepend`` - Prepent the given value to the beginning of a previous variable
+  definition. Only supports paths, delimiter is ``:``
 * ``unset`` - Remove a variable definition, if it is set.
 
 .. _formatted-execs-config:
@@ -471,7 +476,6 @@ environments created from those packages. Its format is as follows:
 .. code-block:: yaml
 
     spack:
-      concretized: [True/False] # Should be false unless defined in a concretized workspace
       [variables: {}]
       packages:
         <package_name>:
@@ -517,70 +521,21 @@ Below is an annotated example of the spack dictionary.
         gcc9: # Abstract name to refer to this package
           spack_spec: [email protected] target=x86_64 # Spack spec for this package
           compiler_spec: [email protected] # Spack compiler spec for this package
-        impi2018:
-          spack_spec: intel-mpi@2018.4.274 target=x86_64
+        impi2021:
+          spack_spec: intel-oneapi-mpi@2021.11.0 target=x86_64
           compiler: gcc9 # Other package name to use as compiler for this package
         gromacs:
           spack_spec: [email protected]
           compiler: gcc9
       environments:
         gromacs:
           packages: # List of packages to include in this environment
-          - impi2018
+          - impi2021
           - gromacs
 
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Vector and Matrix Packages and Environments:
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Package and environment definitions can generate many packages and environments
-following Ramble's
-:ref:`vector<ramble-vector-logic>` / :ref:`matrix<ramble-matrix-logic>` logic.
-
-Below is an example of using this logic within the spack dictionary:
-
-.. code-block:: yaml
-
-    spack:
-      packages:
-        gcc-{ver}:
-          variables:
-            ver: ['9.3.0', '10.3.0', '12.2.0']
-          spack_spec: gcc@{ver} target=x86_64
-          compiler_spec: gcc@{ver}
-        intel-mpi-{comp}:
-          variables:
-            comp: gcc-{ver}
-            ver: ['9.3.0', '10.3.0', '12.2.0']
-          spack_spec: [email protected]
-          compiler: {comp}
-        openmpi-{comp}:
-          variables:
-            comp: gcc-{ver}
-            ver: ['9.3.0', '10.3.0', '12.2.0']
-          spack_spec: [email protected]
-          compiler: {comp}
-        wrf-{comp}:
-          variables:
-            comp: gcc-{ver}
-            ver: ['9.3.0', '10.3.0', '12.2.0']
-          spack_spec: [email protected]
-          compiler: {comp}
-      environments:
-        wrf-{comp}-{mpi}:
-          variables:
-            comp: gcc-{ver}
-            ver: ['9.3.0', '10.3.0', '12.2.0']
-            mpi: [intel-mpi-{comp}, openmpi-{comp}']
-          matrix:
-          - mpi
-          packages:
-          - {mpi}
-          - wrf-{comp}
-
-The above file will generate 3 versions of ``gcc``, 3 versions each of ``wrf``,
-``intel-mpi`` and ``openmpi`` built with each ``gcc`` version, and 6 spack
-environments, with each combination of the 2 ``mpi`` libraries and 3 compilers.
+Packages and environments defined inside the ``spack`` config section are
+merely templates. They will be rendered into explicit environments and packages
+by each individual experiment.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 External Spack Environment Support:

lib/ramble/docs/dev_guides.rst

@@ -1,4 +1,4 @@
-.. Copyright 2022-2024 Google LLC
+.. Copyright 2022-2024 The Ramble Authors
 
    Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
    https://www.apache.org/licenses/LICENSE-2.0> or the MIT license

lib/ramble/docs/dev_guides/application_dev_guide.rst

@@ -1,4 +1,4 @@
-.. Copyright 2022-2024 Google LLC
+.. Copyright 2022-2024 The Ramble Authors
 
    Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
    https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
@@ -265,7 +265,7 @@ directives that are intended to be package manager specific. As an example,
 there are directives for Spack defined by:
 
 * :meth:`ramble.language.shared_language.software_spec`
-* :meth:`ramble.language.shared_language.default_compiler`
+* :meth:`ramble.language.shared_language.define_compiler`
 * :meth:`ramble.language.shared_language.required_package`
 
 These provide Ramble with information about how Spack could install and require