Merge pull request #758 from radical-cybertools/tutorial/tum

Tutorial/tum

CHANGES.md

@@ -6,6 +6,12 @@
     https://github.com/radical-cybertools/radical.saga/issues?q=is%3Aissue+is%3Aopen+
 
 
+Version 1.0.1  Release                                                2020-01-23
+--------------------------------------------------------------------------------
+
+  - small fixes and cleanup for slurm and docs (tutorial prep)
+
+
 Version 1.0.0  Release                                                2019-12-24
 --------------------------------------------------------------------------------
 

VERSION

@@ -1 +1 @@
-1.0.0
+1.0.1

docs/source/_themes/armstrong/theme.conf

@@ -25,9 +25,11 @@ black = #111111
 light_color = #C5D2DD
 light_medium_color = #DDEAF0
 medium_color = #6588A5
+medium_color_hover = rgba(255, 255, 255, 0.25)
 medium_color_link = #634320
 medium_color_link_hover = #261a0c
 dark_color = #293947
+green_highlight = #8ecc4c
 
 h1 = #5a5a5a
 h2 = #5a5a5a
@@ -36,10 +38,6 @@ h3 = #5a5a5a
 link_color = #0088cc
 link_color_decoration = #0088cc
 
-medium_color_hover = rgba(255, 255, 255, 0.25)
-medium_color = rgba(255, 255, 255, 0.5)
-green_highlight = #8ecc4c
-
 
 positive_dark = rgba(51, 77, 0, 1.0)
 positive_medium = rgba(102, 153, 0, 1.0)

docs/source/usage/config.rst

@@ -5,8 +5,13 @@ Configuration
 
 .. note::
 
-   SAGA has been designed as a zero-configuration library. Unless you are 
-   experiencing problems with one of the default configuration settings, there's 
+   This section is outdated!
+
+
+.. note::
+
+   SAGA has been designed as a zero-configuration library. Unless you are
+   experiencing problems with one of the default configuration settings, there's
    really no need to create a configuration file for SAGA.
 
 SAGA and its individual middleware adaptors provide various optional
@@ -22,8 +27,8 @@ Configuration Files
 -------------------
 
 If you need to make persistent changes to any of SAGA's :ref:`conf_options`, the
-simplest option is to create a configuration file. During startup, SAGA checks 
-for the existence of a configuration file in `$HOME/.saga.conf`.  If that 
+simplest option is to create a configuration file. During startup, SAGA checks
+for the existence of a configuration file in `$HOME/.saga.conf`.  If that
 configuration file is found, it is parsed by SAGA's configuration system.
 SAGA configuration files use a structure that looks like this::
 
@@ -32,7 +37,7 @@ SAGA configuration files use a structure that looks like this::
 
     [saga.logger]
         option = value
-        
+
     [saga.adaptor.name]
         option = value
 
@@ -47,10 +52,10 @@ Module saga.utils.config
 
 The config module provides classes and functions to introspect and modify
 SAGA's configuration. The :func:`getConfig` function is used to get the
-:class:`GlobalConfig` object which represents the current configuration 
+:class:`GlobalConfig` object which represents the current configuration
 of SAGA::
 
-   from saga.utils.config import getConfig 
+   from saga.utils.config import getConfig
 
    sagaconf = getConfig()
    print sagaconf.get_category('saga.utils.logger')

docs/source/usage/install.rst

@@ -9,14 +9,14 @@ Requirements
 
 radical.saga has the following requirements:
 
-* Python 2.7 or newer
+* Python 3.5 or newer
 
 
 Installation via PyPi
 ---------------------
 
-radical.saga is available for download via PyPI and may be installed using 
-easy_install or pip (preferred). Both automatically download and install all 
+radical.saga is available for download via PyPI and may be installed using
+easy_install or pip (preferred). Both automatically download and install all
 dependencies required by radical.saga if they can't be found on your system:
 
 .. code-block:: bash
@@ -28,20 +28,20 @@ dependencies required by radical.saga if they can't be found on your system:
 Using Virtualenv
 ----------------
 
-If you don't want to (or can't) install RADICAL-SAGA into your system's Python 
-environment, there's a simple (and often preferred) way to create an 
-alternative Python environment (e.g., in your home directory): 
+If you don't want to (or can't) install RADICAL-SAGA into your system's Python
+environment, there's a simple (and often preferred) way to create an
+alternative Python environment (e.g., in your home directory):
 
 .. code-block:: bash
 
     virtualenv --no-site-package $HOME/sagaenv/
     . $HOME/sagaenv/bin/activate
-    pip install radical.saga   
+    pip install radical.saga
 
 
 **What if my system Doesn't come With virtualenv, pip or easy_install?**
 
-There's a simple workaround for that using the 'instant' version of virtualenv. 
+There's a simple workaround for that using the 'instant' version of virtualenv.
 It also installs easy_install and pip:
 
 .. code-block:: bash
@@ -62,3 +62,4 @@ You can install the latest development version of RADICAL-SAGA directly from our
 .. code-block:: bash
 
     pip install -e git://github.com/radical-cybertools/radical.saga.git@devel#egg=radical.saga
+

docs/source/usage/logger.rst

@@ -7,7 +7,7 @@ In a distributed environment unified error logging and reporting is a crucial
 capability for debugging and monitoring. SAGA has a configurable logging system
 that  captures debug, info, warning and error messages across all of
 its middelware adaptors. The logging system can be controlled in two different
-ways: via :ref:`env_vars` variables, which should be sufficient in most 
+ways: via :ref:`env_vars` variables, which should be sufficient in most
 scenarios, and via the :ref:`log_api`, which provides programmatic access to
 the logging system for advanced use-cases.
 
@@ -17,101 +17,80 @@ the logging system for advanced use-cases.
 Environment Variables
 ---------------------
 
-Several environment variables can be used to control SAGA's logging behavior from 
+Several environment variables can be used to control SAGA's logging behavior from
 the command line. Obviously, this can come in handy when debugging a problem
-with an existing SAGA application. Environment variables are set in the 
-executing shell and evaluated by SAGA at program startup. 
+with an existing SAGA application. Environment variables are set in the
+executing shell and evaluated by SAGA at program startup.
 
-.. envvar:: SAGA_VERBOSE
+.. envvar:: RADICAL_SAGA_LOG_LVL
 
    Controls the log level. This controls the amount of output generated by the
-   logging system. ``SAGA_VERBOSE`` expects either a numeric (0-4) value or a 
+   logging system. ``RADICAL_LOG_LVL`` expects either a numeric (0-4) value or a
    string (case insensitive) representing the log level:
 
    +---------------+---------------------+------------------------------------+
    | Numeric Value | Log Level           | Type of Messages Displayed         |
    +===============+=====================+====================================+
    | 0             | ``CRITICAL``        | Only fatal events that will cause  |
-   | (default)     |                     | SAGA to abort.                     | 
+   | (default)     |                     | SAGA to abort.                     |
    |               |                     |                                    |
    +---------------+---------------------+------------------------------------+
    | 1             | ``ERROR``           | Errors that will not necessarily   |
-   |               |                     | cause SAGA to abort.               | 
+   |               |                     | cause SAGA to abort.               |
    |               |                     |                                    |
    +---------------+---------------------+------------------------------------+
    | 2             | ``WARNING``         | Warnings that are generated by     |
-   |               |                     | SAGA and its middleware adaptors.  | 
+   |               |                     | SAGA and its middleware adaptors.  |
    |               |                     |                                    |
    +---------------+---------------------+------------------------------------+
-   | 3             | ``INFO``            | Useful (?) runtime information     |   
-   |               |                     | that is generated by SAGA and its  | 
+   | 3             | ``INFO``            | Useful (?) runtime information     |
+   |               |                     | that is generated by SAGA and its  |
    |               |                     | middleware adaptors.               |
    +---------------+---------------------+------------------------------------+
    | 4             | ``DEBUG``           | Debug message added to the code    |
-   |               |                     | by the developers. (Lots of output)| 
+   |               |                     | by the developers. (Lots of output)|
    |               |                     |                                    |
    +---------------+---------------------+------------------------------------+
 
-   For example, if you want to see the debug messages that SAGA generates during 
-   program execution, you would set :envvar:`SAGA_VERBOSE` to ``DEBUG`` before 
-   you run your program::
+   For example, if you want to see the debug messages that SAGA generates during
+   program execution, you would set :envvar:`RADICAL_LOG_LVL` to ``DEBUG``
+   before you run your program::
 
-       SAGA_VERBOSE=DEBUG python mysagaprog.py
+       RADICAL_SAGA_LOG_LVL=DEBUG python mysagaprog.py
 
 
-.. envvar:: SAGA_LOG_FILTERS
+  .. envvar:: RADICAL_LOG_LVL
 
-   Controls the message sources displayed. SAGA uses a 
-   hierarchal structure for its log sources. Starting with the root logger
-   ``saga``, several sub loggers are defined for SAGA-internal logging events
-   (``saga.engine``) and individual middleware adaptors ``saga.adaptor.name``.
-   ``SAGA_LOG_FILTERS`` expects either a single source name or a 
-   comma-separated list of source names. Non-existing source names are ignored.
+     Controls the message sources displayed. RCT use an hierarchal structure for
+     its log sources. Starting with the root logger ``RADICAL``, sub loggers are
+     defined for internal logging events (``RADICAL_SAGA``,
+     ``RADICAL_SAGA_ENGINE`` etc.) and individual middleware adaptors, e.g.,
+     ``RADICAL_SAGA_ADAPTORS_NAME``.  ``LOG_LVL`` and ``LOG_TGT`` can be set
+     individually for those loggers.
 
-   For example, if you want to see only the debug messages generated by 
-   ``saga.engine`` and a specific middleware adaptor called ``xyz`` you would 
-   set the following environment variables::
+     For example, if you want to see only the debug messages generated by
+     ``saga.engine`` and a specific middleware adaptor called ``xyz`` you would
+     set the following environment variables::
 
-       SAGA_VERBOSE=DEBUG SAGA_LOG_FILTERS=saga.engine,saga.adaptor.xyz python mysagaprog.py
+         RADICAL_LOG_LVL=ERROR \                       # mute everything
+         RADICAL_SAGA_ENGINNE_LOG_LVL=DEBUG \          # enable engine logger
+         RADICAL_SAGA_ADAPTORS_XYZ_LOG_LVL=DEBUG \     # enable XYZ logger
+         python mysagaprog.py
 
 
-.. envvar:: SAGA_LOG_TARGETS
+.. envvar:: RADICAL_SAGA_LOG_TGT
 
-   Controls where the log messages go. Multiple concurrent locations are 
-   supported. 
-   ``SAGA_LOG_TARGETS`` expects either a single location or a comma-separated 
-   list of locations, where a location can either be a path/filename or
-   the ``STDOUT`` keyword (case insensitive) for logging to the console. 
+   Controls where the log messages go. Multiple concurrent locations are
+   supported.  ``RADICAL_LOG_TGT`` expects either a single location or
+   a comma-separated list of locations, where a location can either be
+   a path/filename or the ``stdout``/``stderr`` keyword (case sensitive) for
+   logging to the console.
 
    For example, if you want to see debug messages on the console but also
-   want to log them in a file for further analysis, you would set the the 
+   want to log them in a file for further analysis, you would set the the
    following environment variables::
 
-       SAGA_VERBOSE=DEBUG SAGA_LOG_TARGETS=STDOUT,/tmp/mysaga.log python mysagaprog.py
-
-
-.. _log_api:
-
-Application Level Logging
--------------------------
-
-The RADICAL-SAGA logging utilities are a thin wrapper around Python's logging
-facilities, integrated into the RADICAL-SAGA configuration facilities.
-To support the seamless integration of application level logging needs, the
-:func:`saga.utils.logger.getLogger` allows to produce additional logger
-facilities, which are again native Python :class:`logging.Logger` instances, but
-preconfigured according to the RADICAL-SAGA logging configuration.
-Those instances can then be further customized as needed::
-
-   from saga.utils.logger import getLogger, INFO
-
-   app_logger       = getLogger ('application.test')
-   app_logger.level = INFO
-
-   app_logger.info ('application level log message on INFO level')
-
-
-.. automodule:: saga.utils.logger
-   :members:
+       RADICAL_SAGA_LOG_LVL=DEBUG RADICAL_SAGA_LOG_TGT=stdout,./rs.log \
+       python mysagaprog.py
 
 

examples/jobs/localjob.py

@@ -5,10 +5,12 @@
 __license__   = "MIT"
 
 
-""" This examples shows how to run a job on the local machine
-    using the 'local' job adaptor.
+"""
+This examples shows how to run a job on the local machine
+using the 'local' job adaptor.
 """
 
+import os
 import sys
 import radical.saga as saga
 
@@ -30,7 +32,7 @@ def main():
             jd.executable        = '/usr/bin/touch'
             jd.arguments         = ['$FILENAME']
 
-            jd.working_directory = "/tmp/A/B/C"
+            jd.working_directory = "/tmp/%d/A/B/C" % os.getuid()
             jd.output            = "examplejob.out"
             jd.error             = "examplejob.err"
 

examples/jobs/slurmjob.py

@@ -17,7 +17,7 @@
 import radical.saga as rs
 
 
-js_url = "slurm+gsissh://stampede2.tacc.xsede.org:2222/"
+js_url = "slurm://localhost/"
 
 
 # ------------------------------------------------------------------------------
@@ -40,8 +40,8 @@ def start():
         jd.arguments         = ['$FILENAME']
 
         jd.name              = "examplejob"
-        jd.queue             = "normal"
-        jd.project           = "TG-MCB090174" 
+      # jd.queue             = "normal"
+      # jd.project           = "TG-MCB090174" 
 
         jd.working_directory = ".saga/test"
         jd.output            = "examplejob.out"
@@ -52,13 +52,13 @@ def start():
         job = js.create_job(jd)
 
         # Check our job's id and state
-        print("Job ID    : %s" % (job.id))
-        print("Job State : %s" % (job.state))
+        print("Job State   : %s" % (job.state))
 
         # Now we can start our job.
         print("starting job")
         job.run()
 
+        print("Job ID      : %s" % (job.id))
         print("Job State   : %s" % job.state)
         print("Exitcode    : %s" % job.exit_code)
         print("Exec. hosts : %s" % job.execution_hosts)