New README for discussion (ref #20)

Author: j-woz

workflows/common/sh/README.adoc

@@ -0,0 +1,38 @@
+
+This is the location for common shell scripting tools for the CANDLE Supervisor Workflows.
+
+== Entry points
+
+Each CANDLE workflow is invoked with a shell script, typically called +site_workflow.sh+, where the +site+ is +theta+, +titan+, etc.  In this document we will call this the workflow_sh script.
+
+=== Purpose
+
+The purpose of these scripts is:
+
+. Determining the run directory, which is the +TURBINE_OUTPUT+ directory used by Swift/T.
+
+. Set key environment variables for Python, R, etc.  These include +PYTHONPATH+, +LD_LIBRARY_PATH+, etc.
+
+. Set key environment variables and Swift/T options for the system scheduler.  These include +PROCS+, +WALLTIME+, +QUEUE+, +PROJECT+, etc.
+
+. Obtain application parameters and pass to the +swift-t+ command line.  These are currently specified in a special section of the workflow_sh.  These arguments are conventionally stored in a Bash variable +CMD_LINE_ARGS+, and passed to +swift-t+.
+
+. Record what happened.  This involves writing additional logs into the TURBINE_OUTPUT directory, particularly to capture settings and provenance that Swift/T cannot.
+
+=== Future ideas
+
+Deduplication (https://github.com/ECP-CANDLE/Supervisor/issues/20[#20]).  The current scripts flex the previously developed EMEWS templates, which make it easy to rapidly develop many workflows; additionally, they are highly linear, readable scripts.  However, they duplicate a great deal of code, making Supervisor development more difficult.
+
+. Source reusable settings.
+.. Write key environment variables once for each system.  E.g., https://github.com/ECP-CANDLE/Supervisor/blob/master/workflows/common/sh/langs-cori.sh[langs-cori.sh]
+.. Same for scheduler settings, module settings.
+. Create a new workflow_sh for each workflow.  This script will take the +site+ as an argument and source the appropriate settings files.
+. Put application parameters in a separate file.  This can be Bash-formatted for compatibility now, but may become something else.
+. Install EQ/Py, EQ/R from Git and put in a common location, maintained by Wozniak.
+. Test scripts.  Each workflow directory will have a +test/+ subdirectory.  This will contain enough bootstrapping code so that it can run and do something small without user configuration.  This will build on the daily testing scripts that Brettin has started.
+
+== Other shell tools
+
+=== ML wrappers
+
+E.g., site_run_model.sh