==========================================
Jobmanagement (:mod:`~mojo.jobManagement`)
==========================================

JobManagement provides a set of classes to executes different types of jobs on a workstation or a cluster. It needs a
bash environment on the workstation and PBS(portable bash system) on the cluster. It consists on a central job list class
which serves as controller for the jobmanagement. A job list instance owns a graph which displays the dependencies
between the jobs in the list and to resources instances which manages the number of processors and nodes to use.
The job class is build as factory pattern which creates instances of the job you need in dependency of your needs.
You can put a job list in a job list if you want to, but for the correct handling of the resources you need to pass the
resources instances of the root job list. For every job a output file will be created automatically, when no path is
given.

To work on a cluster you need a ASCII file /etc/CLUSTERNAME containing the name of the cluster or an environment
variable CLUSTERNAME with the name of the cluster.

Usage
-----
import::

    from mojo.jobManagement.jobs.jobList import JobList
    from mojo.jobManagement.jobs.job import Job

Simple example with three jobs with easy dependencies::
 
    myJobList = Joblist(nNodesAvailable = 0, nProcsAvailable = 6)  # We want to compute local and use six processors
    job1 = Job("<path to a cleanup script>")
    job2 = Job("<path to a TRACE executable>", nProcs = 4, args = ["<a argument>", "<another argument>"])
    job3 = Job("<path to a POST executable>", args = ["<a argument>", "<another argument>"])
    job4 = Job("<path to a analysis script>")
    myJobList.addJob(job1)
    myJoblist.addJob(job2, [job1.id])   # pass a list with the parents ids to get the dependencies right
    myJobList.addJob(job3, [job2.id])
    myJobList.addJob(job4, [job3.id])
    myJobList.viewJobs()  # if you want to
    myJobList.runJoblist()
    myJobList.cleanup()  # if you want to; removes the output files of all successful jobs

If we were on a cluster we could do the same, but for job1 and job4 we would pass executeOnMaster = True to not allocate
a own node for the small scripts. We would pass a number of nodes we wanted to use at the same time. 

A other example with a job list in a job list::

    myJobList = Joblist(nNodesAvailable = 20, nProcsAvailable = 2, name = myJoblist)  # a name for the joblist
    job1 = Job("<path to a cleanup script>")
    myJobList.addJob(job1)
    # passing the management
    ajoblist = JobList(nodeManagement = myJobList.nodeManagement, procManagement = myJoblist.procManagement)
    job2 = Job(..., executeOnMaster = True)  # if you are on a cluster the job will be executed on the master
    job3 = Job(print, args = ["Hello World!"])  # a MethodJob
    ajoblist.addJob(job2)
    ajoblist.addJob(job3, [job2.id])
    myJobList.addJob(ajoblist, [job1.id])

A example executing a single job::

    myJob = Job("<path to executable>", runInBackground = False)
    myJob.runJob()
    myJob.cleanup(False)  # removes the output file even if the job failed; the optional False is available for
                          # the joblist too

Running a MethodJob and receiving the result via a instance variable::
    
    def myMethod(a, b):
        return a + b

    myJob = Job(myMethod, args = [42, 3141], runInBackground = False)
    myJob.runJob()

    print myJob.returnValue

.. attention::

    You will only get pickable return values!

For all available joblist or job options please view the further documentation at the bottom.

.. attention::

    Set runInBackground to false only if you want to execute the job without a job list


.. automodule:: mojo.jobManagement

Modules
-------

    .. automodule:: mojo.jobManagement.jobs.jobList
        :members: JobList

    .. automodule:: mojo.jobManagement.jobs.job
        :members: Job

    .. automodule:: mojo.jobManagement.jobs.abstractJob
        :members: AbstractJob

    .. automodule:: mojo.jobManagement.jobs.shellJob
        :members: ShellJob

    .. automodule:: mojo.jobManagement.jobs.methodJob
        :members: MethodJob

    .. automodule:: mojo.jobManagement.jobs.TracePrepPost.qSubJob
        :members: QSubJob

    .. automodule:: mojo.jobManagement.graph.graph
        :members: Graph

    .. automodule:: mojo.jobManagement.graph.node
        :members: Node

    .. automodule:: mojo.jobManagement.management.idGenerator
        :members: IdGenerator

    .. automodule:: mojo.jobManagement.management.resources
        :members: Resources

    .. automodule:: mojo.jobManagement.management.cpuInfo
        :members: CPUInfo

    .. automodule:: mojo.jobManagement.management.clusterInfo
        :members: ClusterInfo