========
pybatsim
========

|pybatsim| is the official Pythonic abstraction of Batsim_: it helps you
develop your own |batsim| external decision components in Python.

The package provides:

1. a low-level API to communicate with |batsim|,
2. a higher-level and object-oriented API to define external decision
   components (EDC),
3. and a command-line interface to run |EDC|.

The package also provides |EDC| implementations for the following reference
scheduling policies:

- FCFS (first-come, first-serve) list scheduling policy.

.. caution::

   |batsim| and |pybatsim| have different development paces.
   The versions of both project are unrelated.

   |pybatsim| version 4 is compatible with |batsim| version 5.


Installation
------------

|pybatsim| is packaged as a regular Python package, and is published on
`PyPI <https://pypi.org/project/pybatsim/>`__.
It hence can easily be installed with ``pip``.

For more details on how to install a Python package, one can refer to
https://packaging.python.org/tutorials/installing-packages/

The latest stable (recommended) version can be installed with the following
command (assuming ``pip`` is installed):

.. code-block:: console

   $ pip install pybatsim

..

It is recommended to use a virtual environment to install |pybatsim|.
Again, one can refer to
https://packaging.python.org/tutorials/installing-packages/ to get a more
comprehensive overview.

On a typical Linux environment, the commands to use would be:

.. code-block:: console

   $ python3 -m venv pybatsim_venv
   $ source pybatsim_venv/bin/activate
   $ pip install pybatsim

This will create a new virtual environment in the ``pybatsim_venv``
subdirectory, and configure the current shell to use it as the default
``python`` environment.
This will then install |pybatsim| in this new environment without interfering
with the already installed packages.

One would then exit this environment either by exiting the current shell, or by
typing the command ``deactivate``.

Further uses of |pybatsim| only require to activate the virtual environment
with the following command:

.. code-block:: console

   $ source pybatsim_venv/bin/activate


Usage
-----

List available |EDC|
^^^^^^^^^^^^^^^^^^^^

|pybatsim| CLI uses a plugin system to collect the usable |EDC|
(see the `recommended development`_ paragraph for more information).
The list of known |EDC| is available with the ``--list-edcs`` option.

.. code:: console

   $ pybatsim --list-external-decision-components
   fcfs:
     FCFSScheduler
   prototype:
     Load an unpackaged External Decision Component from a file.


Launch an |EDC|
^^^^^^^^^^^^^^^

We assume |batsim| is `installed <https://batsim.rtfd.io/en/latest/installation.html>`__
and correctly configured for the following commands to succeed.
We advise to launch |batsim| in a dedicated shell first, and then start
|pybatsim| in its own shell.
Any |EDC| listed by ``--list-edcs`` (*e.g*, ``fcfs``) can be launched.

.. code:: console

   batsim-shell$ batsim --platform="${platform}.xml" --workload="${workload}.json" --edc-socket-str 'tcp://localhost:28000' ''
   ...
   pybatsim-shell$ pybatsim fcfs
   ...


Developing an |EDC|
-------------------

The ``prototype`` |EDC| can be used for quick and dirty tests.
We strongly advise against using this |EDC| for anything else than testing: it
has poor performance as every call is proxied, and it does not allow for a
proper packaging.

.. _`recommended development`:

The recommended way to develop an |EDC| is to create a Python package with
|pybatsim| as a dependency.
This allows to properly track and manage the specific dependencies of the
developed |EDC|.
The |EDC| is made available by registering it under the
``pybatsim.external_decision_components`` entry-point.

.. TODO add link to tutorial


.. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. .. ..

.. _Batsim: https://batsim.rtfd.io/

.. |EDC| replace:: *EDC*
.. |batsim| replace:: Batsim
.. |pybatsim| replace:: ``pybatsim``
