Ramble is a multi-platform experimentation framework that increases exploration productivity and improves reproducibility. Ramble is capable of driving software installation, acquiring input files, configuring experiments, and extracting results. 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 scaling studies
- Compiler flag sweeps
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
python3 -m venv ramble/env
. ramble/env/bin/activate
pip install -r ramble/requirements.txt
./ramble/bin/ramble workspace create -d test_workspace -c ramble/examples/basic_hostname_config.yaml
Ramble’s python dependencies can be installed using the included requirements.txt file.
e.g.
pip install -r requirements.txt
We recommend Python >= 3.7 for Ramble, but a best effort attempt is made to
support Python 3.6 as it is used by older operating systems such as Centos7.
Specifically, you might need to update pip and downgrade protobuf when
using Python 3.6.
Outside of these requirements, Ramble requires package managers to be configured if they will be used as part of the experiments Ramble creates.
Although package manager support is not required to use Ramble, some experiments are more easily accomplished by allowing Ramble to drive the package manager execution. To allow this, package managers generally need to be installed indepednently from Ramble. For more information on this, see Ramble's supported package managers.
Ramble’s documentation can be viewed at https://ramble.readthedocs.io/.
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 guide.
Example configuration files are also contained in the examples directory.
Ramble is an open source project. Questions, discussion, and contributions are welcome. Contributions can be anything from new packages to bugfixes, documentation, or even new core features.
Resources:
- Github Discussions: not just for discussions, also Q&A.
When developing features for Ramble, it can be helpful to install the development requirements instead of the user requirements:
e.g.
pip install -r requirements-dev.txt
Contributing to Ramble is relatively easy. Just send us a
pull request.
When you send your request, make develop the destination branch on the
Ramble repository.
Your PR must pass Ramble's unit tests and documentation tests, and must be PEP 8 compliant. We enforce these guidelines with our CI process.
These tests can be run locally through test runners in the share/ramble/qa/ directory. Alternatively, pre-commit 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.
Ramble's develop branch has the latest contributions. Pull requests
should target develop, and users who want the latest package versions,
features, etc. can use develop.
Each Ramble release series also has a corresponding branch, e.g.
releases/v0.1 has 0.1.x versions of Ramble, and releases/v0.2 has
0.2.x versions. We backport important bug fixes to these branches but
we do not advance the application definitions or make other changes that would
change the way experiments Ramble would create within a release branch.
So, you can base your Ramble deployment on a release branch subsequent updates
can be considered non-breaking.
The latest release is always available with the releases/latest tag.
Please note that Ramble has a Code of Conduct. By participating in the Ramble community, you agree to abide by its rules.
Many thanks go to Ramble's contributors.
Ramble was created by Doug Jacobsen, [email protected].
This software is distributed under the terms of both the MIT license and the Apache License (Version 2.0).
See LICENSE for details.
SPDX-License-Identifier: (Apache-2.0 OR MIT)