Merge branch 'master' of https://git.scc.kit.edu/jk7683/gridka-school-fireworks

docs/basics.rst

@@ -103,11 +103,11 @@ If a workflow has been added without check it can be check later with::
 
     lpad check_wflow -i <firework ID>
 
-Note: The correctness check is recommended for all exercises in the tutorial.
+**NOTE:** The correctness check is recommended for all exercises in this tutorial.
 
 
-View workflows
---------------
+Visualize workflows
+-------------------
 
 Already added workflows can be converted into DOT format and viewed graphically
 as PDF::
@@ -134,10 +134,14 @@ To run all fireworks in *READY* state in a sequence::
 
     rlaunch rapidfire
 
-Note: Every firework changes its state to *READY* after all its dependency fireworks
-are completed (state *COMPLETED*) and the states of linked child fireworks are updated 
-as soon as a firework if completed. This means that any workflow will be run until 
-there are no more fireworks in *READY* state.
+**NOTE:** Every firework changes its state to *READY* after all its parent 
+fireworks are completed (state *COMPLETED*) and the states of linked child 
+fireworks are updated as soon as a firework if completed. This means that any 
+workflow will be run until there are no more fireworks in *READY* state.
+
+**NOTE:** In singleshot mode ``rlaunch`` runs the firework in the directory where it is 
+started. In rapidfire mode ``rlaunch`` creates a runtime sibdirectory one per firework 
+and executes each firework in a separate directory.
 
 To suppress verbose information on the screen the *-s* flag can be added::
 
@@ -155,13 +159,13 @@ To query individual fireworks use the command::
 
     lpad get_fws [-i <firework ID> [-d <more|all>]]
 
-Note: The query from the command line is recommended for thi tutorial.
+Note: The query from the command line is recommended in this tutorial.
 
 Alternatively the web GUI can be used::
 
     lpad webgui
 
-Note: Make sure that a web browser is configured in your terminal session and an
+**NOTE:** Make sure that a web browser is configured in your terminal session and an
 X server is running on your machine and it is configured and tunneled properly 
 in your terminal session.
 

docs/exercise5.rst

-.. _exercise5:
-
 Exercise 5: Writing a Firetask
 ==============================
 
+This exercise bases on an extended version of the example from **Exercise 2**. 
+It is implemented as a python script 
+**exercises/problems/5_author_firetask/recruiting-script.py**. It has two new aspects:
+
+    1. All parameters are loaded at the beginning from a JSON document 
+       **parameters.json**.
+    2. The steps candidates_apply() and screen_candidates() are repeated as long 
+       as the size of the canditate list is smaller than ``number_to_invite``.
+
+
+Anatomy of Firetasks
+--------------------
+
+All firetasks are classes derived from the ``FiretaskBase`` class. Many built-in 
+Firetasks are available in the upstream FireWorks, such as the ``ScriptTask``, 
+``PyTask``, FileTransferTask. Additional firetasks can be written for both 
+generic and specific purposes.
+
+The skeleton of a Firetask looks like this::
+
+    from fireworks.core.firework import FiretaskBase, FWAction
+    from fireworks.utilities.fw_utilities import explicit_serialize
+
+    @explicit_serialize
+    class MyFiretask(FiretaskBase):
+        """ My new Firetask """
+
+        _fw_name = 'MyFiretask'
+        required_params = ['par1', 'par2']
+        optional_params = ['optional par']
+
+        def run_task(self, fw_spec):
+            """
+            This is the method called upon Firetask execution. It has access
+            to the spec through the fw_spec parameter. The required and the 
+            optional parameters are accessed through self, i.e. they are class 
+            attributes. Optionally this function returns a FWAction object to pass
+            data to next Firetasks and Fireworks and/or to dynamically modify the
+            workflow.
+            """
+
+            print(self[par1], self[par2]) # print the values of required params
+            print(self.fw_spec['name']) # print the name of the Firework
+
+            if self.get('optional par'):
+                actions = [
+                    'update_spec': {
+                        'par1': self[par1],
+                        'optional par': self['optional par']
+                    }
+                ]
+            else:
+                actions = []
+
+            return FWAction(*actions)
+
+Here a firework using this firetask::
+
+    - fw_id: 1
+      name: Sample firework
+      spec:
+        _tasks:
+        - _fw_name: {{custom_tasks.MyFiretask}}
+          par1: data.json
+          par2: data.yaml
+          optional par: {}
+
+
+**NOTE**: the python module ``custom_tasks`` must be in $PYTHONPATH in order to 
+be correctly registered. For this reason keep the file **custom_tasks.py** either
+in **lib** or in **exercises/work/5_author_firetask** where you start the ``lpad`` 
+and ``rlaunch`` commands. In the latter case you should add that directory to 
+$PYTHONPATH with::
+
+    export PYTHONPATH=`pwd`:$PYTHONPATH
+
+
+Problem 5.1: Data Loader Task
+-----------------------------
+
+Write a DataLoaderTask to load the necessary parameters from the JSON document. 
+If necessary the input data structure can be split into more than one file.
+The resulting workflow, which is given in **dataloader.json**, must be successfully 
+running with no further modifications.
+
+**Hint**: You can use the ``load()`` method from the ``json`` package to load 
+JSON documents as list or dictionaries and then return a ``FWAction`` object 
+with ``update_spec`` and the structure (see above example). 
+
 
-A. Data Loader Task
+Problem 5.2: Conditional Repeater Task
+--------------------------------------
 
-A firetask has to be written to realize the given workflow.
+Write a RepeatIfLengthLesser firetask that can implement the while loop in the
+script. The firetask should integrate into the workflow available in 
+**dataloader+repeater.json** without further adaptations.
 
+Hint: You can use the ``load_object`` function from 
+``fireworks.utilities.fw_serializers`` to construct a firework object and 
+the ``detours`` keyword argument of ``FWAction`` `to insert the firework 
+dynamically::
 
-B. While-task
\ No newline at end of file
+    firework = Firework(
+        tasks=[load_object(task) for task in fw_spec['_tasks']],
+        spec=fw_spec,
+        name='repeat '+self['measure']
+    )
+    return FWAction(detours=firework)
\ No newline at end of file