.. _scheduler:


pirs.core.scheduler subpackage
====================================

.. currentmodule:: pirs.core.scheduler

To start a computational code, several things need to be done. Where is the
code executable? What input data and other files does it need? Where it is
started? To simplify tasks connected to these questions, there are classes
defined in the :mod:`pirs.core.scheduler` module helping to create directories, set
files necessary to start a code, to start it and to wait until it completes.

A directory containing all files necessary to start a code is described in the
:class:`WorkPlace` class. An instance of this class helps to define directory
names where a code will be started. 

.. literalinclude:: examples/sched_wp1.py

.. literalinclude:: examples/sched_wp1.out
   :language: none

When the :meth:`WorkPlace.prepare` is called, the current directory is searched
for already existing directories starting with string specified in the
:attr:`WorkPlace.prefix` attribute, in the example ``wp``. If there are no such
directories, the directory ``wp0`` is created. If there already some
directories with prefix ``wp``, an integer N is chosen so that directory
``wpN`` does not exist yet, and this directory is created. The
:attr:`WorkPlace.report` attribute is a string containing the last created
directory (see also :attr:`WrokPlace.lcd`) the name of Python script where the
method was called, and creation time.  The above example results in two newly
created empty directories, ``wp0`` and ``wp1``. 

To put files in newly created directories, the :attr:`WorkPlace.files` list
attribute must be populated with instances of the
:class:`pirs.core.scheduler.InputFile` class. This class describes content and
name of the file to be written or copied to the workplace directory. The content
can be specified as a string or as a link to existing file. 

.. literalinclude:: examples/sched_if1.py

.. literalinclude:: examples/sched_if1.out
   :language: none

In this example three input files are created. The first one, ``i1``, will be
written to a file in the workplace directory with the name defined by the
:attr:`InputFile.basename`.  with content defined by the string passed to the
:attr:`InputFile.string` argument. The second input file, ``i2``, is a link to
an existing file. In this case, the file ``./srctp1`` will be copied from the
current directory to the workplace under the new name, ``srctp2``. The content
of the third input file, ``i3`` is defined again as a stging.  Additionally,
the :attr:`InputFile.executable` attribute is set to ``True`` meaning that this
file, when written to the workplace, will be added executable mode. 

As in the previous example, we create an instance of the :class:`WorkPlace`
class, ``w``, but now we append the defined input files ``i1``, ``i2`` and
``i3`` to the list attribute :attr:`~WorkPlace.files`.  The
:meth:`~WorkPlace.prepare` method creates a new directory, an we can see in the
report that this directory is now called ``wp2`` and has three files: ``'inp'``
and ``'start.sh'`` are generated from string and ``'srctp2'`` is copied from
another file. The :meth:`WorkPlace.run` method called at the last line searches
for input files with executable mode set to ``True`` and if founds, starts it
and waits until particular criteria are satisfied. In the example we specified
to wait for 1 second, other criteria are possible, see description of the
:meth:`Scheduler.wait` method. The :meth:`~WorkPlace.run` method standard
output generated by the script.


Jobs and schedulers
---------------------

TODO: to write.


Docstrings
--------------

.. autoclass:: pirs.core.scheduler.WorkPlace
   :members:

.. autoclass:: pirs.core.scheduler.InputFile
   :members:

.. autoclass:: pirs.core.scheduler.Scheduler
   :members:

.. autoclass:: pirs.core.scheduler.Job
   :members: