Release version v0.3.0

This merge represents the release of v0.3.0 of Ramble.

This release includes 75 pull requests from 3 contributors.

Author: douglasjacobsen

.github/workflows/sphinx.yml

@@ -0,0 +1,27 @@
+name: Sphinx build
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - name: Build docs
+      run: |
+          pip install -r ./lib/ramble/docs/requirements.txt
+          sphinx-build -b html ./lib/ramble/docs ./docs
+      #uses: ammaraskar/[email protected]
+      #with:
+      #docs-folder: "./lib/ramble/docs/"
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v3
+      with:
+        name: html-docs
+        path: ./docs/
+    - name: Deploy
+      uses: peaceiris/actions-gh-pages@v3
+      if: github.ref == 'refs/heads/develop'
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: "docs"

.pre-commit-config.yaml

@@ -0,0 +1,12 @@
+repos:
+- repo: local
+  hooks:
+  - id: flake8
+    name: flake8
+    entry: share/ramble/qa/run-flake8-tests
+    language: system
+  - id: short-unit-tests
+    name: short-unit-tests
+    entry: share/ramble/qa/run-unit-tests
+    language: system
+    stages: [push]

README.md

@@ -9,7 +9,9 @@ These can include anything from:
  - Performance focused scalaing studies
  - Compiler flag sweeps
 
-To install ramble and configure your experiment workspace, make sure you have Python.
+To install ramble and configure your experiment workspace, make sure you have
+Python, and Ramble’s dependencies are installed as per the dependency section
+below.
 Then:
 
     $ git clone -c feature.manyFiles=true https://github.com/GoogleCloudPlatform/ramble.git
@@ -35,7 +37,7 @@ Documentation
 For help with Ramble’s commands, run `ramble help` or `ramble help --all`.
 
 For more information on concepts in Ramble, see Ramble’s
-[Getting Started](./docs/Getting_Started.md) guide.
+[Getting Started](./lib/ramble/docs/getting_started.rst) guide.
 
 Example configuration files are also contained in the
 [examples](./examples) directory.
@@ -60,10 +62,12 @@ When you send your request, make ``develop`` the destination branch on the
 
 Your PR must pass Ramble's unit tests and documentation tests, and must be
 [PEP 8](https://www.python.org/dev/peps/pep-0008/) compliant.  We enforce
-these guidelines with our CI process. To run these tests locally,
-please use the test runners:
- - share/ramble/qa/run-unit-tests
- - share/ramble/qa/run-flake8-tests
+these guidelines with our CI process.
+
+These tests can be run locally through test runners in the share/ramble/qa/
+directory. Alternatively, [pre-commit](https://pre-commit.com/#install) can be
+used to manage our git hooks. To install the hooks, simply run:
+- pre-commit install
 
  For additional requirements about contributing, including Google’s CLA, see our
  [Contribution Guide](.github/CONTRIBUTING.md).

bin/ramble

@@ -1,3 +1,4 @@
+#!/bin/sh
 # Copyright 2022-2023 Google LLC
 #
 # Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or

etc/ramble/defaults/spack.yaml

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

examples/README.md

@@ -106,5 +106,6 @@ The slurm execute experiment script shows an example of creating an
 `execute_experiment` script for use in a slurm cluster.
 
 To use this, place it in the configs directory for your workspace, and change
-the `ramble:batch:submit` definition in your ramble.yaml to: `sbatch {slurm_execute_experiment}`.
-Then when performing `ramble workspace setup`, the `all_experiments` script will submit to slurm.
+the `ramble:variables:batch_submit` definition in your ramble.yaml to:
+`sbatch {slurm_execute_experiment}`. Then when performing `ramble workspace
+setup`, the `all_experiments` script will submit to slurm.

examples/basic_expansion_config.yaml

@@ -1,16 +1,7 @@
 ramble:
-  mpi:
-    command: mpirun
-    args:
-      - -n
-      - '{n_ranks}'
-      - -ppn
-      - '{processes_per_node}'
-      - -hostfile
-      - hostfile
-  batch:
-    submit: '{execute_experiment}'
   variables:
+    mpi_command: 'mpirun -n {n_ranks} -ppn {processes_per_node} -hosfile hostfile'
+    batch_submit: '{execute_experiment}'
     n_ranks: '{processes_per_node}*{n_nodes}'
   applications:
     openfoam:
@@ -23,6 +14,7 @@ ramble:
                 processes_per_node: ['16', '32']
                 #^-- (partition, processes_per_node) -> (part1, 16), (part2, 32)
                 n_nodes: ['2', '4']
+                wrf_path: execute_experiment in wrfv4.CONUS_2p5km.new_test
               matrices:
                 - - n_nodes
                 #^-- (partiton, processes_per_node, n_nodes) ->
@@ -38,38 +30,31 @@ ramble:
                 n_nodes: '1'
 spack:
   concretized: true
-  compilers:
+  packages:
     gcc9:
-      base: gcc
-      version: 9.3.0
-      target: x86_64
-  mpi_libraries:
+      spack_spec: [email protected] target=x86_64
     ompi412:
-      base: openmpi
-      version: 4.1.2
-      variants: +legacylaunchers +pmi +thread_multiple +cxx
-      target: x86_64
+      spack_spec: [email protected] +legacylaunchers +pmi +thread_multiple +cxx target=x86_64
+      compiler: gcc9
     impi2018:
-      base: intel-mpi
-      version: 2018.4.274
-  applications:
+      spack_spec: [email protected]
+      compiler: gcc9
+    openfoam:
+      spack_spec: openfoam-org@7
+      compiler: gcc9
+    flex:
+      spack_spec: [email protected]
+      compiler: gcc9
+    wrfv4:
+      spack_spec: [email protected] build_type=dm+sm compile_type=em_real nesting=basic ~chem ~pnetcdf
+      compiler: gcc9
+  environments:
     openfoam:
-      flex:
-        base: flex
-        version: 2.6.4
-        compiler: gcc9
-      openfoam:
-        base: openfoam-org
-        version: '7'
-        compiler: gcc9
-        mpi: ompi412
-        dependencies:
-        - flex
+      packages:
+      - ompi412
+      - flex
+      - openfoam
     wrfv4:
-      wrf:
-        base: wrf
-        version: '4.2'
-        variants: build_type=dm+sm compile_type=em_real nesting=basic ~chem ~pnetcdf
-        compiler: gcc9
-        mpi: impi2018
-        required: true
+      packages:
+      - impi2018
+      - wrfv4

examples/basic_gromacs_config.yaml

@@ -1,64 +1,52 @@
 ramble:
-    variables:
-        processes_per_node: 16
-    mpi:
-        command: mpirun
-        args:
-        - '-n'
-        - '{n_ranks}'
-        - -ppn
-        - '{processes_per_node}'
-        - -hostfile
-        - hostfile
-    batch:
-        submit: '{execute_experiment}'
-    applications:
-        gromacs: # Application name
-            workloads:
-                water_gmx50: # Workload name from application
-                    experiments:
-                        pme_single_rank: # Arbitrary experiment name
-                            variables:
-                                n_ranks: '1'
-                                n_threads: '1'
-                                size: '0003'
-                                type: 'pme'
-                        rf_single_rank:
-                            variables:
-                                n_ranks: '1'
-                                n_threads: '1'
-                                size: '0003'
-                                type: 'rf'
-                water_bare:
-                    experiments:
-                        pme_single_rank:
-                            variables:
-                                n_ranks: '1'
-                                n_threads: '1'
-                                size: '0003'
-                                type: 'pme'
-                        rf_single_rank:
-                            variables:
-                                n_ranks: '1'
-                                n_threads: '1'
-                                size: '0003'
-                                type: 'rf'
+  variables:
+    processes_per_node: 16
+    mpi_command: 'mpirun -n {n_ranks} -ppn {processes_per_node} -hostfile hostfile'
+    batch_submit: '{execute_experiment}'
+  applications:
+    gromacs: # Application name
+      workloads:
+        water_gmx50: # Workload name from application
+          experiments:
+            pme_single_rank: # Arbitrary experiment name
+              variables:
+                n_ranks: '1'
+                n_threads: '1'
+                size: '0003'
+                type: 'pme'
+            rf_single_rank:
+              variables:
+                n_ranks: '1'
+                n_threads: '1'
+                size: '0003'
+                type: 'rf'
+        water_bare:
+          experiments:
+            pme_single_rank:
+              variables:
+                n_ranks: '1'
+                n_threads: '1'
+                size: '0003'
+                type: 'pme'
+              rf_single_rank:
+                variables:
+                  n_ranks: '1'
+                  n_threads: '1'
+                  size: '0003'
+                  type: 'rf'
 spack:
     concretized: true
-    compilers:
-        gcc9:
-            base: gcc
-            version: 9.3.0
-            target: x86_64
-    mpi_libraries:
-        impi2018:
-            base: intel-mpi
-            version: 2018.4.274
-            target: x86_64
-    applications:
-        gromacs: # Application name
-            gromacs: # Spec name. Semi-abstract, but could be required
-                base: gromacs
-                version: '2021.6'
-                compiler: gcc9
-                mpi: impi2018
+    packages:
+      gcc9:
+        spack_spec: [email protected] target=x86_64
+      impi2018:
+        spack_spec: [email protected] target=x86_64
+        compiler: gcc9
+      gromacs:
+        spack_spec: [email protected]
+        compiler: gcc9
+    environments:
+      gromacs:
+        packages:
+        - gromacs
+        - impi2018

examples/basic_hostname_config.yaml

@@ -20,15 +20,12 @@
 #               n_ranks: '{processes_per_node}'
 
 ramble:
-  mpi:
-    command: mpirun
-    args: []
-  batch:
-    submit: '{execute_experiment}'
   env-vars:
     set:
       OMP_NUM_THREADS: '{n_threads}'
   variables:
+    mpi_command: 'mpirun'
+    batch_submit: '{execute_experiment}'
     processes_per_node: -1
   applications:
     hostname:
@@ -48,10 +45,5 @@ ramble:
                 processes_per_node: '16'
 spack:
   concretized: true
-  compilers: {}
-  mpi_libraries: {}
-  applications: {}
-    # app_name
-    #   spec_name:
-    #     base: ''
-    #     version: ''
+  packages: {}
+  environments: {}