ecFlow's documentation is now on readthedocs!

Please go to https://ecflow.readthedocs.io/en/latest/index.html

Previous Up Next
Tasks can be logically grouped into family‘s.
You can picture a suite as a hierarchical structure very similar to a UNIX
file system, where the families are the directories, and the tasks are the files.
The suite is a family with some extra attributes (See Dates and Clocks).
Like directories, families can themselves contain other families.
And like directories, there can be many tasks with the same name, as long as
they are in different families.
Unless you tell ecFlow where to find specific files, the default behaviour
is to expect the file structure to reflect the structure of the suite.
  

Ecf Script

In the suite definition below we will create a family f1 with two tasks t1 and t2.
In this case, you will have to create a directory $HOME/course/test/f1,
and move t1.ecf and t2.ecf into it.
Conversely, the ecFlow jobs and the outputs will be created in this directory.
Because we have moved the scripts to another directory, ecFlow will not find
the two included files head.h and tail.h one directory up from
the scripts.
We could modify the scripts to search the include file two directories up,
but this would be very cumbersome.
The solution is to define a special ecFlow variable called ECF_INCLUDE
that points to the directory containing the include files. See pre-processing
Whenever angled brackets are used, ecFlow first looks to see if ECF_INCLUDE
variable is specified. If the variable exists, it checks to see if the file
%ECF_INCLUDE%/head.h exists, otherwise it looks for %ECF_HOME%/head.h
This has the added advantage that specific includes files can be placed under
ECF_INCLUDE, and includes file common to many tasks can be placed in
ECF_HOME. For more details see directives.
We need to do the following changes to the ecf script‘s.

from:

%include "../head.h"
echo "I am part of a suite that lives in %ECF_HOME%"
%include "../tail.h"

to:

%include <head.h>
echo "I am part of a suite that lives in %ECF_HOME%"
%include <tail.h>

suite‘s, family‘s and task‘s are called node‘s.


Text

# Definition of the suite test.
 suite test
   edit ECF_INCLUDE "$HOME/course"  # replace '$HOME' with the path to your home directory
   edit ECF_HOME    "$HOME/course"
   family f1
      task t1
      task t2
   endfamily
endsuite

Python

If you are using the Suite Definition API: Update $HOME/course/test.py

$HOME/course/test.py
import os
from ecflow import Defs,Suite,Family,Task,Edit
         
def create_family_f1():
    return Family("f1",
                Task("t1"),
                Task("t2"))
            
print("Creating suite definition") 
home = os.path.join(os.getenv("HOME"),  "course") 
defs = Defs( 
        Suite("test",
            Edit(ECF_INCLUDE=home,ECF_HOME=home),
            create_family_f1()))
print(defs) 

print("Checking job creation: .ecf -> .job0")  
print(defs.check_job_creation())

print("Saving definition to file 'test.def'")
defs.save_as_defs("test.def")

The hierarchy is shown as a tree in ecflow_ui

What to do

  1. Update the suite definition
  2. Create the directories needed, move the ecf script‘s
  3. Edit the script to include head.h and tail.h from the ECF_INCLUDE directory.
  4. Replace the suite
    python: python3 test.py
                 python3 client.py
    text:      ecflow_client --suspend=/test ;  ecflow_client --replace=/test test.def
  5. View the suite in ecflow_ui , notice the tree structure. You may have to unfold test and f1 to see the tasks.
      


Previous Up Next

1 Comment

  1. Avi Bahra

    Alternative styles that produce the same definition:

    import os
from ecflow import *
        
print("Creating suite definition")
home = os.path.join(os.getenv("HOME"),  "course") 

defs = Defs(Suite("test",
                Edit(ECF_INCLUDE=home,ECF_HOME=home),
                Family("f1",
                    Task("t1"),
                    Task("t2"))))
print(defs)

print("Checking job creation: .ecf -> .job0") 
print(defs.check_job_creation())
print("Saving definition to file 'test.def'")
defs.save_as_defs("test.def")

print("Replace suite /test in the server")
defs.test.replace_on_server()
    import os
from ecflow import *
        
print("Creating suite definition")
home = os.path.join(os.getenv("HOME"),  "course") 

defs = Defs() + (Suite("test") + Edit(ECF_INCLUDE=home,ECF_HOME=home))
defs.test += Family("f1") + [ Task("t{0}".format(i)) for i in range(1,3) ]
print(defs)

print("Checking job creation: .ecf -> .job0") 
print(defs.check_job_creation())
print("Saving definition to file 'test.def'")
defs.save_as_defs("test.def")

print("Replace suite /test in the server")
defs.test.replace_on_server()