Skip to content

Commit

Permalink
Official 1.1.7 release (#268)
Browse files Browse the repository at this point in the history
* Addition of user enabled workspace hashing (#145)

* Addition of hashing to Study parameterization.

* Addition of the hashws option to argparse.

* Addition of a warning note for users who use labels in steps.

* Update setup.py to 1.1.4dev

* More generalized FluxScriptAdapter (#149)

* Addition of a more general flux ScriptAdapter.

* Addition of some casting from int to str

* Corrected "gpus" to "ngpus"

* Rework jobspec construction to make a valid jobspec.

* Check for empty value for cores per task.

* README tweak to update quickstart link. (#139)

* typos. fixes #141 (#154)

* Correction of flake8 style errors [new version of flake8].

* Update to setup.py to reflect dev version 1.0

* Correction to safe pathing for missed cases and make_safe_path enhancements. (#157)

* Made pickle and log path string safe for pathing.

* Tweaks to make_safe_path to include a base path.

* Updates to make_safe_path usage

* Correction to not modify the iterator copy.

* Correction to fix the format of output status time to avoid a comma that breaks printing. (#160)

* Addition of a utility function for formatting times to H:M:S

* _StepRecord time methods now call the new utility function.

* Tweaks to add days to the format to avoid 3 digit hours.

* Tweak to formatting.

* Made the day format more parsable.

* Removal of _stage_linear since it is now not needed. (#156)

* Removal of _stage_linear since it is now not needed.

* Addition of linear LULESH samples.

* Update the dev to 1.1.

* Addition of pargs for passing parameters to custom parameter generation (#152)

* Addition of a utility method to create a dictionary from a list of key-value pairs.

* Addition of the pargs interface for passing parameters to custom parameter generation.

* Addition of a Monte Carlo example that accepts pargs.

* Addition of pargs check for dependency on pgen.

* Addition of clearer error message for malformed parameters.

* Update setup.py

* do not overwrite log file. (#162)

Signed-off-by: Peter Robinson <[email protected]>

* Added confirmation message after launching a study (#163)

* Enhancements to store relative pathing in the metadata file. (#165)

* Changes to make workspaces reflect relative pathing based on step names.

* Addition of an alternative output format based on step combinations.

* Addition of tag to LULESH git dependency. (#169)

* Script Adapter Plugin (#167) (#170)

Fixes #167 

* added pytest to requirements

added Pipfile and pipenv settings

* Added property key to Abstract.ScriptAdapter (#167)
Also added impementation and tests to verify that existing functionality isn't changed

* updated factory to use key when registering adapters(#167)

* cleanedup linelength

* cleaned up imports to be specific to module (#167)

* added tests to verify exception for unknown adapter

* moved adapters tests to individual files

* added test to verify scriptadapter functionality (#167)

updated gitignore to have testing and pycharm ignores

testing existing adapters in factory (#167)

added test to verify factories.keys matches get_valid_adapters (#167)

added copyright to file

* updated __init__ modules to do dynamic includes

* removed unneeeded imports

* updated dependency versions

* fixed all flake8 errors

* updated to run flake8 and pytest when run locally

* updated tests to have documentation about purpose and function as requested in #170

* fixed line length

* Removal of nose from requirements.

* updated to remove nose from the requirements

* PyYAML vulnerability fix (#171)

* Locking the version of PyYAML to be above 2.1 because of an arbitrary code execution vulnerability.

* Addition of a version condition to pyyaml to patch a vulnerability.

* Update of Pipfile.lock to match Pipefile.

* Minor tweak to indentation for flake8 failure.

* fixed pyyaml to requirements (#172)

* Addition of a loader to the yaml load call. (#174)

Fixes #173 

* Addition of a loader to the yaml load call.

* Addition of a catch if the loader attribute is missing.

* Correction to install enum34 for Python versions < 3.4 (#176)

* Moved enum34 to condition dependent on Python<3.4.

* Addition of conditional enum34 install for requirements.txt.

* Correction of requirements.txt syntax for python version.

* Addition of a Dockerfile for tutorials and ease of trying out. (#178)

* Addition of a Dockerfile for quick tutorials.

* Tweaks for Docker and addition of git.

* Tweak to Docker file for caching.

* Addition of Docker documentation.

* Tweaks to Docker documentation.

* Removal of markdown ##

* Take out shebang from shell definition and add it when script is written. (#181)

* Take out shebang from shell definiton and at it when script is written.

* Include shebang in cmd and fix format of string written to file.

* Tweaks to fix malformed log statements. (#182)

* Correction to message when stating no to launch.

* Enhance shell batch setting to apply to scheduler scripts. (#183)

* Extension of shebang feature to allow users to specify shells.

* Addition of debug message to print kwargs.

* Addition of kwargs.

* Addition of basic batch settings to LULESH sample.

* Addition of kwargs to Flux adapters.

* Docstring tweaks.

* Docstring update.

* Fixes the addition of the shebang header for SLURM (#184)

* Docstring correction for LocalAdapter.

* Correction to addition of exec line at top of scripts.

* Correction to an accidental reassignment of cmd.

* Removal of an assignment of self._exec in SLURM adapter.

* Change to transition adapter returns to Record objects. (#177)

* Addition of a Record class for storing general data.

* Addition of SubmissionRecord type.

* Update to the order of for record parameters.

* Changes to StepRecord to expect SubmissionRecord returns.

* Updates to SLURM and local adapters to use SubmissionRecords.

* Slight tweak to LocalAdapter docstring.

* Tweak to have SubmissionRecord initialize its base.

* Addition of CancellationRecord class.

* Changes to CancellationRecord to map based on status.

* Additional interface additions and tweaks.

* Changes to have cancel use CancellationRecords.

* Update to ExecutionGraph to use records.

* Updates to SLURM and local adapters to use SubmissionRecords.

* Slight tweak to LocalAdapter docstring.

* Addition of CancellationRecord class.

* Additional interface additions and tweaks.

* Changes to have cancel use CancellationRecords.

* Cherry pick of execution commit.

* Removal of redundant "get" definiton.

* Addition of a SLURM enabled LULESH sample specification.

* Addition of output for stdout and stderr for Local adapter.

* Correction of file to open.

* Addition of 3.7 to testing stack.

* Added 3.7 to tox.ini.

* Removal of py37 in testing.

* Addition of py37 to travisCI (#187)

* Correction to 3.7 specification.

* Removed py37 from tox testing.

* Readded py37 to tox and removed duplicate from travis.

* Addition of build status badge.

* Update SLURM sample spec to add missing walltime.

* Addition of dumping the environment to a YAML file. (#190)

* Addition of documentation that covers the set up of a simple study (#168)

* Addition of simple Hello World spec.

* Addition of basics page to index.

* Addition of hello_world documentation.

* Additions to hello_world.

* More documentation in single step section.

* Continued edits to Hello World.

* Addition of parameter section.

* Addition of a note about %% token.

* Addition of directory structure.

* Continuation of parameter documentation.

* Removal of the depends key.

* Addition of the env section description.

* Addition of a link to Docker documentation for Dockerfiles.

* Addition of single parameter hello world.

* Correction of double colons.

* Correction of indentation.

* Addition of print out to verify output.

* Addition of sample specifications for multi and single params.

* Addition of more documentation for single param.

* Additional output to show parameter results.

* Correction to formatting.

* Addition of samples.

* Addition of simple Hello World spec.

* Addition of basics page to index.

* Addition of hello_world documentation.

* Additions to hello_world.

* More documentation in single step section.

* Continued edits to Hello World.

* Addition of parameter section.

* Addition of a note about %% token.

* Addition of directory structure.

* Continuation of parameter documentation.

* Removal of the depends key.

* Addition of the env section description.

* Addition of a link to Docker documentation for Dockerfiles.

* Addition of single parameter hello world.

* Correction of double colons.

* Correction of indentation.

* Addition of print out to verify output.

* Addition of sample specifications for multi and single params.

* Addition of more documentation for single param.

* Additional output to show parameter results.

* Correction to formatting.

* Updates to docstrings for data structures.

* Updates to clear Sphinx warnings.

* Removal of escape on the *args becuase of flake8 failure.

* Clean up of existing hello world specs.

* Addition of multistep example spec.

* Removal of * to fix sphinx errors.

* Correction to some docstrings.

* Tweaks to specs for consistent naming.

* Finished multi-step parameterized example.

* Tweaks to hello world docs.

* Addition of link to examples on GitHub.

* Correction of link to examples.

* Correction of link to examples (again).

* Removal of Pipfile.lock.

* Additions to gitignore for vscode and pipenv.

* Marking for v1.1.4 release.

* Corrected a missed merge for release v1.1.4

* Extend the Specification interface to break out loading from streams. (#198)

* Closes #198 

* Addition of loading specification "from_str".

* Updates to Specification docstrings.

* Updates to abstract Specification to change from str to stream.

* Updates to YAMLSpecification to use the new stream API.

* Removal of IOString

* Update to the YAMLSpecification load stream method.

* Quickfix: Addition of the accidental removal of the path member variable.

* Updating the version to 1.1.5dev (forgotten previously).

* Correction to versioning for install.

* Moved SLURM parameters to be placed in front of the submitted script. (#202)

Fixes #201

* Addition of version information to package and command line (#205)

* Addition of version information.

* Tweak to have setup.py pull from __version__

* Addition of command line arg to print version.

* Pinning version for release 1.1.5

* Addition of 1.1.5a to line up with PyPi labeling.

* Increment up to get rid of a0

* Addition of a simple example and logo to the README. (#208)

* Addition of the Maestro logo.

* Logo and hello world addition.

* Addition parameter section.

* Slight tweak to parameter section.

* Addition of a reference to samples folder.

* Update __init__.py to tick version to dev version.

* Addition of Spack shield.

* Enhances pgen to have access to environment specified in a study. (#209)

* Add the OUTPUT_PATH and SPECROOT to kwargs for pgen.

* Addition of the spec constructed environment.

* Remove "study_env" from pgen kwargs.

* Update to pgen function parameters.

* Update lulesh examples to have pgen vars.

* Correction to docstring ordering.

* Updates to add scheduled workflows and reorganize.

* Correction to HPC wikipedia link.

* Updates to the classifiers for setup.py

* Addition of long text setting.

* Correction of missing quote.

* Drop support for Python 3.4 (#218)

* Removal of enum34 and Python 3.4 classifiers.

PyYAML no longer supports Python 3.4 which is forcing Maestro to
also drop support as it has a direct dependency.

* Addition of python requirements, download url, and maintainer.

* Re-add py2.7. Note: py2.7 unofficially supported.

* Re-add enum34 for py2.7.

* Removal of py34 from tox tests.

* Removal of py3.4 from travis.

* Applies workspace substitution to the restart command. (#219)

Fixes #217 

* Sub in the new restart command.

* Addition of restart workspaces to sub.

* Fix for WORKSPACE substitutions into restart.

* Correction to override restart instead of cmd.

* Test/interfaces/lsf (#215)

* Implementation of a ScriptAdapter for the IBM LSF Scheduler.

Initial implementation of an LSF adapter.

Addition of LSF to the interface factory.

Correction to time format LSF correction.

Tweak to correct for casting

Further tweaks to the LSFScriptAdapter

Adjustments to the states the LSF adapter can return.

More tweaks to LSF states and status checking.

Update to the batch setting docstring

Tweak to make wallclock time entries two digits

Bugfix to the previous commit.

Signed-off-by: Francesco Di Natale <[email protected]>

* Addition of GPU support.

* Addition of a cancel method.

* Addition of reservation submissions.

* Tweak to use the -nrs flag for jsrun.

* Changes to resource allocation parameters.

* Removal of some batch headers for LSF.

* Tweak to error code for NOJOBS status.

* Tweak to skip lines that are part of prev status line.

* Correction of --nrs

* Correction of task batch key to nodes.

* Tweaks to _substitute_parallel_command.

Now only pass in step.run by copy and append the popped keys as
step resources "snodes" and "sprocs".

* Correction to LSF adapter to correct node specification.

* Tweaks to checking status of LSF jobs.

A tweak to formatting of the output for bjobs. With the new format
we get termination reason, which allows us to check for a timed
out status.

* Correction to bjobs formatting and nojob check.

* Corrections to how nodes and procs are being passed.

* Correction of the bkill command with multiple job ids.

* Tweaks to check_jobs for LSF adapter.

* Implementation of a ScriptAdapter for the IBM LSF Scheduler.

Initial implementation of an LSF adapter.

Addition of LSF to the interface factory.

Correction to time format LSF correction.

Tweak to correct for casting

Further tweaks to the LSFScriptAdapter

Adjustments to the states the LSF adapter can return.

More tweaks to LSF states and status checking.

Update to the batch setting docstring

Tweak to make wallclock time entries two digits

Bugfix to the previous commit.

Signed-off-by: Francesco Di Natale <[email protected]>

* Addition of GPU support.

* Addition of a cancel method.

* Tweak to use the -nrs flag for jsrun.

* Changes to resource allocation parameters.

* Removal of some batch headers for LSF.

* Tweak to error code for NOJOBS status.

* Tweak to skip lines that are part of prev status line.

* Correction of task batch key to nodes.

* Tweaks to _substitute_parallel_command.

Now only pass in step.run by copy and append the popped keys as
step resources "snodes" and "sprocs".

* Correction to LSF adapter to correct node specification.

* Tweaks to checking status of LSF jobs.

A tweak to formatting of the output for bjobs. With the new format
we get termination reason, which allows us to check for a timed
out status.

* Correction to bjobs formatting and nojob check.

* Corrections to how nodes and procs are being passed.

* Correction of the bkill command with multiple job ids.

* Tweaks to check_jobs for LSF adapter.

* Addition of LSF to key for LSFScriptAdapter.

* Correction of lsf key.

* Addition of a debug statement to catch status command.

* Correction of bjobs command.

* Additions to status checks.

* Rearraging some debug logging.

* Testing to see if .split works.

* Further LSF tweaks.

* Revert back to split with strip.

* Removal of -q option due to excessive filtering.

* Correction of a missed merge

* Correction to use new Records structures.

* Style fix for line 207.

* Correction to SubmissionRecord creation.

* Decode output in check_status to enforce str type.

* Decode output in submit.

* Addition of retcode to a logger statement.

* Sets log and err out for SLURM to parameterized step name (#220)

Fixes #213 

* First attempt at log name fix.

* Correction to header formatting.

* Update to dev0 to differentiate for pre-release.

* Ticked up version to 1.1.7dev1.

* Update Maestro logo link to full link for PyPi.

* Small Tweak to the rtd.io link

* An update to Maestro's description.

* Adding Neptune to the list on Planets (#222)

Signed-off-by: Adrien M. Bernede <[email protected]>

* Small README tweak.

* Updated the study step name in the README.md file (#227)

* Updated the package version in the Sphinx docs (#229)

* Added a link to Maestro's documentation (#231)

* Added a link to the documentation in the README.md

* Added a documentation section to the README.md

* Improve the performance of expansion (#232)

* Addition of override for ExectionGraph to not check cycles.

* Addition of documentation for justification of override.

* Addition of a newline due to style.

* Addition of dill as a dependency.

* Fix pickle and unpickle to use dill.

* Updated the description in the setup.py file (#233)

* Added dill to the requirements.txt file (#235)

* Fix to add PID to local log names. (#241)

* Refactor to move DAG operations to the back end Conductor (#242)

* Removal of SimObject references.

* Addition of PickleInterface.

* Derive Study and ExecutionGraph from PickleInterface.

* Some style clean up.

* Clean up unused dill import.

* Checking in to develop on another machine.

* Start of pre-check.

* Removal of precheck.

* Tweaks to Maestro and Conductor.

* Initial interface and refactor to Conductor class.

* Refactor of monitor_study

* Tweaks to backend conductor to use Conductor class.

* Tweaks to Maestro frontend to use Conductor class.

* Minor bug fixes in Conductor class.

* Minor tweaks to user cancel in Conductor class.

* Port status to the Conductor class.

* Continued additions to port to Conductor class.

* Slight fix to fix flake8 violation.

* Removal of named argument *, python2.7 does not support it.

* Refactor to remove parser and logging from Conductor class.

* Style clean up to fix flake8 errors.

* Updates to the docstrings for PickleInterface.

* Updates to the Conductor docstrings.

* Small flake8 error fix.

* Added pre-commit to enable flake8 checks (#244)

Added pre-commit to enable flake8 checks before a commit is accepted.

Also reordered requirements.txt to more
easily determine which are for development.

* Bugfix for logging that didn't appear in submodules (#247)

* Improved logging setup.

* Transition to a LoggerUtil class.

* Addition of docstring to LoggerUtility + cleanup.

* Added spec verification via jsonschema

added checks for valid keys

branch updates

working on validation

added schema file

updates

fixed spec

fixed spec

added jsonschema to deps

updates

ran black on yamlspecification.py

specified newest jsonschema version

added manifest

added include_package_data to setup.py

reformatted json

experimental package_data

fixed path

fixed path

fixed path again

reverted newline

added check for empty strings

reworked exception logic

implemented reviewer suggestions, shifted exception logic, renamed redundant variables

renamed variable

removed unused import

added missing `self.verify_environment()` call

Co-Authored-By: Francesco Di Natale <[email protected]>

paths and git dependencies are now array types

Co-Authored-By: Francesco Di Natale <[email protected]>

removed redundant logic

swapped number type to integer

moved env schema validation to top, which avoids some types of ambiguous errors

removed test yaml

removed some additionalProperties restrictions

unknown commit

removed debug print

* Reformatted and added color to logger messages. (#252)

Closes #248 

Added color to logging and converted some info messages to debug.

added colors and cleaned up logger

corrected formatting

added to dependencies

reverted message log level change

added debug format

debug logging format now works

flake8 fix

* Bug fix for unintentional variable section requirement. (#256)

Closes #255. A bug fix that corrects an unintentional assumption that the variable section in a specification will always exist.

* Update to broken venv documentation link.

* Addition of a simple dry-run capability. (#259)

* Addition of a simple dry-run capability.

* Addition of a DRYRUN state.

* Tweak to reduce sleep time for dry run.

* Renamed dryrun to dry to reduce redundancy.

* Enable autoyes when dry running is invoked.

* enabled raw sbatch errors to be logged (#262)

* enabled raw sbatch errors to be logged

* tweaks/correction suggested by Frank

* reduced line length

* fixed flake8 error in slurm-adapter

* Tweaks and fixes to the SLURM header. (#263)

* Tweaks and fixes to the SLURM header.

Adds the ability to specify GPUs, fixes reservation pairing with
accounts, and now uses a ChainMap to handle the internal key
conflicts between the batch and step settings. Also introduces
the exclusive key. Changed to full parameter names for clarity.

* Addition of chainmap package for python2.7

* A check to see if procs is included in the header.

Fixes #234 and includes ntasks in the header if the batch section
includes the key.

* modified executiongraph to round datetimes to nearest second

* Adds a check for UNKNOWN state. (#266)

Fixed #264 -- When testing #263, SLURM ran out of memory
during the completing stage and aborted the jobs and left the
job in an unknown state. This PR fixes this issue by defaulting to
a failure when the status is found to be UNKNOWN.

* Adds a check for UNKNOWN state.

* Correction of bad variable name "state"

* Tweak to treat UNKNOWN as failed.

* Change marking of failed state to unknown.

* Some fixes for style and credit from #265

* Official 1.1.7 release.

Co-authored-by: Elsa Gonsiorowski, PhD <[email protected]>
Co-authored-by: robinson96 <[email protected]>
Co-authored-by: jsemler <[email protected]>
Co-authored-by: Kevin Athey <[email protected]>
Co-authored-by: Joe Koning <[email protected]>
Co-authored-by: Adrien Bernede <[email protected]>
Co-authored-by: Kevin Athey <[email protected]>
Co-authored-by: Bay <[email protected]>
Co-authored-by: Benjamin Bay <[email protected]>
Co-authored-by: crkrenn <[email protected]>
Co-authored-by: Christopher R. Krenn <[email protected]>
  • Loading branch information
12 people authored May 17, 2020
1 parent d1ed291 commit b1ea900
Show file tree
Hide file tree
Showing 37 changed files with 1,733 additions and 764 deletions.
12 changes: 12 additions & 0 deletions .pre-commit-config.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
# See https://pre-commit.com for more information
# See https://pre-commit.com/hooks.html for more hooks
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.5.0
hooks:
- id: trailing-whitespace
- id: end-of-file-fixer
- id: check-yaml
- id: check-added-large-files
- id: check-toml
- id: flake8
1 change: 0 additions & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ language: python

python:
- "2.7"
- "3.4"
- "3.5"
- "3.6"

Expand Down
1 change: 1 addition & 0 deletions MANIFEST.in
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
include maestrowf/datastructures/schemas.json
19 changes: 12 additions & 7 deletions Pipfile
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,28 @@ verify_ssl = true
name = "pypi"

[packages]
"enum34" = "*"
filelock = "*"
PyYAML = ">=4.2b1"
six = "*"
filelock = "*"
tabulate = "*"
Fabric = "*"
PyYAML = ">= 4.2b1"
dill = "*"
maestrowf = {path = "."}

[dev-packages]
"flake8" = "*"
flake8 = "*"
pydocstyle = "*"
pylint = "*"
tox = "*"
coverage = "*"
sphinx_rtd_theme = "*"
Sphinx = "*"
pytest = "*"
fabric = "*"
Sphinx = "*"
pytest-cov = "*"
pre-commit = "*"
sphinx-rtd-theme = "*"

[pipenv]
allow_prereleases = true

[requires]
python_version = "3.6"
169 changes: 134 additions & 35 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,133 @@
# Maestro Workflow Conductor (MaestroWF)
![](https://github.com/LLNL/maestrowf/raw/develop/assets/logo.png?raw=true "Orchestrate your workflows with ease!")

# Maestro Workflow Conductor ([maestrowf](https://pypi.org/project/maestrowf/))

[![Build Status](https://travis-ci.org/LLNL/maestrowf.svg?branch=develop)](https://travis-ci.org/LLNL/maestrowf)
[![PyPI](https://img.shields.io/pypi/v/maestrowf.svg)](https://pypi.python.org/pypi?name=maestrowf&version=1.0.0&:action=display)
![Spack](https://img.shields.io/spack/v/py-maestrowf)
[![Issues](https://img.shields.io/github/issues/LLNL/maestrowf.svg)](https://github.com/LLNL/maestrowf/issues)
[![Forks](https://img.shields.io/github/forks/LLNL/maestrowf.svg)](https://github.com/LLNL/maestrowf/network)
[![Stars](https://img.shields.io/github/stars/LLNL/maestrowf.svg)](https://github.com/LLNL/maestrowf/stargazers)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/LLNL/maestrowf/master/LICENSE)

## Introduction
[![Downloads](https://pepy.tech/badge/maestrowf)](https://pepy.tech/project/maestrowf)
[![Downloads](https://pepy.tech/badge/maestrowf/month)](https://pepy.tech/project/maestrowf/month)
[![Downloads](https://pepy.tech/badge/maestrowf/week)](https://pepy.tech/project/maestrowf/week)

Maestro Workflow Conductor is a Python tool and library for specifying and automating multi-step computational workflows both locally and on supercomputers. Maestro parses a human-readable YAML specification that is self-documenting and portable from one user and environment to another.
Maestro can be installed via [pip](https://pip.pypa.io/):

On the backend, Maestro implements a set of standard interfaces and data structures for handling "study" construction. These objects offer you the ability to use Maestro as a library, and construct your own workflows that suit your own custom needs. We also offer other structures that make portable execution on various schedulers much easier than porting scripts by hand.
pip install maestrowf

### Core Concepts
## Documentation

There are many definitions of workflow, so we try to keep it simple and define the term as follows:
* [Maestro Documentation](https://maestrowf.readthedocs.io)
* [Maestro Samples](/samples)

## Getting Started is Quick and Easy

Create a `YAML` file named `study.yaml` and paste the following content into the file:

``` yaml
description:
name: hello_world
description: A simple 'Hello World' study.

study:
- name: say-hello
description: Say hello to the world!
run:
cmd: |
echo "Hello, World!" > hello_world.txt
```
> *PHILOSOPHY*: Maestro believes in the principle of a clearly defined process, specified as a list of tasks, that are self-documenting and clear in their intent.
Running the `hello_world` study is as simple as...

maestro run study.yaml

## Creating a Parameter Study is just as Easy

With the addition of the `global.parameters` block, and a few simple tweaks to your `study` block, the complete specification should look like this:

``` yaml
description:
name: hello_planet
description: A simple study to say hello to planets (and Pluto)
study:
- name: say-hello
description: Say hello to a planet!
run:
cmd: |
echo "Hello, $(PLANET)!" > hello_$(PLANET).txt
global.parameters:
PLANET:
values: [Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto]
label: PLANET.%%
```

> *PHILOSOPHY*: Maestro believes that a workflow should be easily parameterized with minimal modifications to the core process.

Maestro will automatically expand each parameter into its own isolated workspace, generate a script for each parameter, and automatically monitor execution of each task.

And, running the study is still as simple as:

``` bash
maestro run study.yaml
```

## Scheduling Made Simple

But wait there's more! If you want to schedule a study, it's just as simple. With some minor modifications, you are able to run on an [HPC](https://en.wikipedia.org/wiki/Supercomputer) system.

``` yaml
description:
name: hello_planet
description: A simple study to say hello to planets (and Pluto)
batch:
type: slurm
queue: pbatch
host: quartz
bank: science
study:
- name: say-hello
description: Say hello to a planet!
run:
cmd: |
echo "Hello, $(PLANET)!" > hello_$(PLANET).txt
nodes: 1
procs: 1
walltime: "00:02:00"
global.parameters:
PLANET:
values: [Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus, Neptune, Pluto]
label: PLANET.%%
```

> **NOTE**: This specification is configured to run on LLNL's quartz cluster. Under the `batch` header, you will need to make the necessary changes to schedule onto other HPC resources.
>
> *PHILOSOPHY*: Maestro believes that how a workflow is defined should be decoupled from how it's run. We achieve this capability by providing a seamless interface to multiple schedulers that allows Maestro to readily port workflows to multiple platforms.

For other samples, see the [samples](/samples) subfolder. To continue with our Hello World example, see the [Basics of Study Construction](https://maestrowf.readthedocs.io/en/latest/hello_world.html) in our [documentation](https://maestrowf.readthedocs.io/en/latest/index.html).

## An Example Study using LULESH

Maestro comes packed with a basic example using [LULESH](https://github.com/LLNL/LULESH), a proxy application provided by LLNL. You can find the example [here](https://maestrowf.readthedocs.io/en/latest/quick_start.html#).

## What is Maestro?

Maestro is an open-source HPC software tool that defines a YAML-based study specification for defining multistep workflows and automates execution of software flows on HPC resources. The core design tenants of Maestro focus on encouraging clear workflow communication and documentation, while making consistent execution easier to allow users to focus on science. Maestro’s study specification helps users think about complex workflows in a step-wise, intent-oriented, manner that encourages modularity and tool reuse. These principles are becoming increasingly important as computational science is continuously more present in scientific fields and has started to require a similar rigor to physical experiment. Maestro is currently in use for multiple projects at Lawrence Livermore National Laboratory and has been used to run existing codes including MFEM, and other simulation codes. It has also been used in other areas including in the training of machine-learned models and more.

### Maestro's Foundation and Core Concepts

There are many definitions of workflow, so we try to keep it simple and define the term as follows:

``` text
A set of high level tasks to be executed in some order, with or without dependencies on each other.
```

Expand All @@ -24,56 +136,43 @@ We have designed Maestro around the core concept of what we call a "study". A st
Maestro's core tenets are defined as follows:

##### Repeatability

A study should be easily repeatable. Like any well-planned and implemented science experiment, the steps themselves should be executed the exact same way each time a study is run over each set of parameters or over different runs of the study itself.

##### Consistent

Studies should be consistently documented and able to be run in a consistent fashion. The removal of variation in the process means less mistakes when executing studies, ease of picking up studies created by others, and uniformity in defining new studies.

##### Self-documenting

Documentation is important in computational studies as much as it is in physical science. The YAML specification defined by Maestro provides a few required key encouraging human-readable documentation. Even further, the specification itself is a documentation of a complete workflow.

----------------

## Getting Started
## Setting up your Python Environment

To get started, we recommend using virtual environments. If you do not have the
Python virtual environment package and wrapper installed follow this [guide](http://python-guide-pt-br.readthedocs.io/en/latest/dev/virtualenvs/).

### Environment Setup
If you do not have or use virtualenvwrapper:
Python `virtualenv` package installed, take a look at their official [documentation](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) to get started.

$ python -m virtualenv venv
$ source venv/bin/activate
Otherwise:
To create a new virtual environment:

$ mkvirtualenv venv
python -m virtualenv maestro_venv
source maestro_venv/bin/activate

### Getting Started for Contributors

Once set up, test the environment. The paths should point to a virtual environment folder.

$ which python
$ which pip

### Installation

For general installation, you can install MaestroWF using the following:

$ pip install maestrowf

If you plan to develop on MaestroWF, install the repository directly using:
If you plan to develop on Maestro, install the repository directly using:

$ pip install -r requirements.txt
$ pip install -e .
pip install -r requirements.txt
pip install -e .

----------------

### Quickstart Example

MaestroWF comes packed with a basic example using LULESH, a proxy application provided by LLNL. You can find the Quick Start guide [here](https://maestrowf.readthedocs.io/en/latest/quick_start.html#).
Once set up, test the environment. The paths should point to a virtual environment folder.

----------------
which python
which pip

## Contributors

Many thanks go to MaestroWF's [contributors](https://github.com/LLNL/maestrowf/graphs/contributors).

If you have any questions or to submit feature requests please [open a ticket](https://github.com/llnl/maestrowf/issues).
Expand Down
Binary file added assets/logo.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Maestro Workflow Conductor Documentation

[maestrowf.rtfd.io](http://maestrowf.readthedocs.io/en/latest/)
[maestrowf.rtd.io](http://maestrowf.readthedocs.io/en/latest/)

This documentation is built with Sphinx for ReadTheDocs.
The contents are automatically generated from the doc strings found in the code.
Expand Down
4 changes: 2 additions & 2 deletions docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -56,9 +56,9 @@
# built documents.
#
# The short X.Y version.
version = u'0.0.1dev0'
version = u'1.1'
# The full version, including alpha/beta/rc tags.
release = u'0.0.1dev0'
release = u'1.1.7dev1'

# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
Expand Down
2 changes: 1 addition & 1 deletion maestrowf/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -51,5 +51,5 @@ def emit(self, record):
LOGGER = logging.getLogger(__name__)
LOGGER.addHandler(NullHandler())

__version_info__ = ("1", "1", "6")
__version_info__ = ("1", "1", "7")
__version__ = '.'.join(__version_info__)
43 changes: 38 additions & 5 deletions maestrowf/abstracts/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -33,23 +33,56 @@
This module contains all of the abstract classes and APIs for defining objects.
Abstracts include abstract data stuctures (like a graph), APIs for concepts
such as queueing adapters and environment APIs, as well as fundamental data
structures like a SimObject.
structures.
"""
# NOTE: Some of these abstracts will be moved in the future. The Graph abstract
# class does not belong here, and should be moved to something more general.
# NOTE: The SimObject base class may not be required, since it basically
# just requires objects to be dictionaries.
import dill
import logging

from maestrowf.abstracts.abstractclassmethod import abstractclassmethod
from maestrowf.abstracts.envobject import Dependency, Source, Substitution
from maestrowf.abstracts.graph import Graph
from maestrowf.abstracts.simobject import SimObject
from maestrowf.abstracts.specification import Specification


__all__ = ("abstractclassmethod", "Dependency", "Graph", "SimObject",
__all__ = ("abstractclassmethod", "Dependency", "Graph", "PickleInterface",
"Singleton", "Source", "Specification", "Substitution")

LOGGER = logging.getLogger(__name__)


class PickleInterface:
"""A mixin class that implements a general pickle interface using dill."""

@classmethod
def unpickle(cls, path):
"""
Load a pickled instance from a pickle file.
:param path: Path to a pickle file containing a class instance.
"""
with open(path, 'rb') as pkl:
obj = dill.load(pkl)

if not isinstance(obj, cls):
msg = "Object loaded from {path} is of type {type}. Expected an" \
" object of type '{cls}.'".format(path=path, type=type(obj),
cls=type(cls))
LOGGER.error(msg)
raise TypeError(msg)

return obj

def pickle(self, path):
"""
Generate a pickle file of of a class instance.
:param path: The path to write the pickle to.
"""
with open(path, 'wb') as pkl:
dill.dump(self, pkl)


class _Singleton(type):
_instances = {}
Expand Down
1 change: 1 addition & 0 deletions maestrowf/abstracts/enums/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ class State(Enum):
TIMEDOUT = 10
UNKNOWN = 11
CANCELLED = 12
DRYRUN = 13


class StudyStatus(Enum):
Expand Down
Loading

0 comments on commit b1ea900

Please sign in to comment.