Merge pull request #43 from douglasjacobsen/release-v0.2.0

Release v0.2.0

Author: rfbgo

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -25,13 +25,13 @@ body:
         If Ramble reported an error, provide the error message. If it did not report an error but the output appears incorrect, provide the incorrect output. If there was no error message and no output but the result is incorrect, describe how it does not match what you expect.
       placeholder: |
         ```console
-        $ spack --debug --stacktrace <command>
+        $ ramble --debug --stacktrace <command>
         ```
   - type: textarea
     id: information
     attributes:
       label: Information on your system
-      description: Please include the output of `spack debug report`
+      description: Please include the output of `ramble debug report`
     validations:
       required: true
   - type: markdown
@@ -53,6 +53,4 @@ body:
     attributes:
       value: |
         We encourage you to try, as much as possible, to reduce your problem to the minimal example that still reproduces the issue. That would help us a lot in fixing it quickly and effectively!
-        If you want to ask a question about the tool (how to use it, what it can currently do, etc.), try the `#general` channel on [our Slack](https://slack.spack.io/) first. We have a welcoming community and chances are you'll get your reply faster and without opening an issue.
-        
         Other than that, thanks for taking the time to contribute to Ramble!

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -36,6 +36,4 @@ body:
   - type: markdown
     attributes:
       value: |
-        If you want to ask a question about the tool (how to use it, what it can currently do, etc.), try the `#general` channel on [our Slack](https://slack.spack.io/) first. We have a welcoming community and chances are you'll get your reply faster and without opening an issue.
-        
-        Other than that, thanks for taking the time to contribute to Ramble!
+        Thanks for taking the time to contribute to Ramble!

.gitignore

@@ -1,3 +1,4 @@
 __pycache__/
 *.x
 *.txt
+var/ramble/cache

LICENSE-APACHE

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

LICENSE-MIT

@@ -1,7 +1,6 @@
 MIT License
 
-Copyright (c) 2013-2020 Google LLC, and other Spack or Ramble
-Project Developers.
+Copyright (c) 2022-2023 Google LLC, Ramble Project Developers.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

LICENSE.md

@@ -20,3 +20,8 @@ config:
     connect_timeout: 10
     checksum: true
     shell: 'sh'
+    spack_flags:
+      install: '--reuse'
+      concretize: '--reuse'
+    input_cache: $ramble/var/ramble/cache
+    workspace_dirs: $ramble/var/ramble/workspaces

etc/ramble/defaults/config.yaml

@@ -0,0 +1 @@
+mirrors: {}

etc/ramble/defaults/mirrors.yaml

@@ -1,8 +1,18 @@
-# Getting Started
------------------
+.. Copyright 2022-2023 Google LLC
 
-# System Requirements:
-------------------------
+   Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+   https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+   <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+   option. This file may not be copied, modified, or distributed
+   except according to those terms.
+
+===============
+Getting Started
+===============
+
+--------------------
+System Requirements:
+--------------------
 
 Ramble's dependencies are listed within the top level
 requirements.txt file.
@@ -14,24 +24,26 @@ Please see [Spack's documentation](https://spack.readthedocs.io/en/latest/gettin
 for getting spack installed.
 
 
-# Installation:
------------------
+-------------
+Installation:
+-------------
 
 Installing ramble is easy. You can clone it from the
 [github repository](https://github.com/GoogleCloudPlatform/ramble) using this command:
 
-```
+.. code-block:: console
    $ git clone -c feature.manyFiles=true https://github.com/GoogleCloudPlatform/ramble.git
-```
+
 
 This will create a directory called ``ramble``.
 
-# Shell Support:
-------------------
+^^^^^^^^^^^^^^
+Shell Support:
+^^^^^^^^^^^^^^
 
 Once you have cloned Ramble, we recommend sourcing the appropriate script for your shell:
 
-```
+.. code-block:: console
    # For bash/zsh/sh
    $ . ramble/share/ramble/setup-env.sh
 
@@ -40,7 +52,6 @@ Once you have cloned Ramble, we recommend sourcing the appropriate script for yo
 
    # For fish
    $ . ramble/share/ramble/setup-env.fish
-```
 
 That's it! You're ready to use Ramble.
 
@@ -58,40 +69,42 @@ continue to use the same consistent python version regardless of changes in the
 environment.
 
 
-# Command Help:
------------------
+-------------
+Command Help:
+-------------
 To get information on the available commands, you can execute:
 
-```
+.. code-block:: console
     $ ramble help --all
-```
+
 
 For help with sub-commands, the ``-h`` flag can be used:
 
-```
+.. code-block:: console
    $ ramble <subcommand> -h
-```
 
-# Defined Applications:
--------------------------
+
+---------------------
+Defined Applications:
+---------------------
 
 In order to get information about the available applications defined within
 ``ramble``, you can use the command:
 
-```
+.. code-block:: console
    $ ramble list
-```
+
 
 This command uses filtering to search the defined applications, e.g.:
 
-```
+.. code-block:: console
    $ ramble list wrf
-```
 
 will list both ``wrfv3`` and ``wrfv4``.
 
-# Ramble Workspaces:
-----------------------
+------------------
+Ramble Workspaces:
+------------------
 
 To configure experiments, you need to use a Ramble workspace. A workspace is a
 self contained directory that contains configuration files, template files, and
@@ -111,50 +124,48 @@ commands.
 A workspace can be selected when executing ``ramble`` through the use of the
 ``-w`` and ``-D`` flags.
 
-## Creating Workspaces:
--------------------------
+^^^^^^^^^^^^^^^^^^^^
+Creating Workspaces:
+^^^^^^^^^^^^^^^^^^^^
 
 To create a new Ramble workspace, you can use:
 
-```
+.. code-block:: console
     $ ramble workspace create [<name>] [-d <path>]
-```
 
 Once a workspace is created, you can activate the workspace. This allows some
 subsequent commands to work without explicitly passing in a workspace. This
 is done through:
 
-```
+.. code-block:: console
     $ ramble workspace activate [<name>/<path>]
-```
 
 With an activated workspace, you can get information about the workspace with:
 
-```
+.. code-block:: console
     $ ramble workspace info
-```
 
-## Configuring A Workspace:
------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
+Configuring A Workspace:
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Within the created workspace, a ``configs`` directory is created to house the
 configuration files.
 
 A newly created workspace will contain:
 
-```
+.. code-block:: console
    - configs
      | - ramble.yaml
      | - execute_experiment.tpl
-```
 
 The ``ramble.yaml`` file contains the configuration of the workspace. Any file
 placed in this ``configs`` directory with the extension ``.tpl`` will generate
 a "rendered" version within every experiment directory.
 
 These files can be edited with your favorite editor, or though the command:
 
-```
+.. code-block:: console
     $ ramble workspace edit
 ```
 
@@ -164,70 +175,72 @@ configuration file.
 Variables are defined of the format ``{file_prefix}``, that contain the path to
 the rendered version within every experiment. As an example:
 
-```
+.. code-block:: console
     configs/execute_experiment.tpl
-```
 
-Will define ``{execute_experiment}``
+Will define ``{execute_experiment}`` with a value set to the path of hte
+generated file.
+(More explicitly, ``execute_experiment={experiment_run_dir}/{template_name_sans_extension}``)
 
-## Concretizing A Workspace:
-------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^
+Concretizing A Workspace:
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
 After configuring a workspace with applications, workloads, and experiments,
 Ramble can be used to inject default software configurations for the requested
 experiments. To do this, you can use the:
 
-```
+.. code-block:: console
     $ ramble workspace concretize
-```
 
 This will fill out the ``spack`` dictionary within the ``ramble.yaml`` file
 with defaults. The defaults can be configured however you want before
 installing the actual software.
 
-## Setting Up A Workspace:
-----------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
+Setting Up A Workspace:
+^^^^^^^^^^^^^^^^^^^^^^^
 
 Once a workspace is concretized, it can be set up. This process is executed through:
 
-```
+.. code-block:: console
     $ ramble workspace setup
-```
 
 The setup action will:
  - Install required / requested software
  - Download required input files
  - Create and configure experiment directories
  - Create the ``all_experiments`` script
 
-## Executing Experiments:
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^
+Executing Experiments:
+^^^^^^^^^^^^^^^^^^^^^^
 
 After the workspace is set up, its experiments can be executed. The two methods
 to run the experiments are:
 
-```
+.. code-block:: console
     $ ramble on
+   or;
     $ ./all_experiments
-```
-
 
-## Analyzing Experiments:
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^
+Analyzing Experiments:
+^^^^^^^^^^^^^^^^^^^^^^
 
 Once the experiments within a workspace are complete, the experiments can be
 analyzed. This is done through:
 
-```
+.. code-block:: console
     $ ramble workspace analyze
-```
 
 This creates a ``results`` file in the root of the workspace that contains
 extracted figures of merit.
 
 
-## Archiving A Workspace:
----------------------------
+^^^^^^^^^^^^^^^^^^^^^^
+Archiving A Workspace:
+^^^^^^^^^^^^^^^^^^^^^^
 
 Ramble can create an archive of a workspace. This is a self contained copy of various important aspects of the workspace, including:
  - All files in the ``configs`` directory
@@ -238,12 +251,10 @@ Ramble can create an archive of a workspace. This is a self contained copy of va
 
 You can archive a workspace with:
 
-```
+.. code-block:: console
     $ ramble workspace archive
-```
 
 And you can create a tar-ball with:
 
-```
+.. code-block:: console
     $ ramble workspace archive -t
-```