Command Queue - cmd_queue
=========================
.. .. |Appveyor| |Codecov|
|Pypi| |Downloads| |GitlabCIPipeline| |GitlabCICoverage| |ReadTheDocs|
+------------------+-------------------------------------------------------------------------------------+
| Read the docs | https://cmd-queue.readthedocs.io |
+------------------+-------------------------------------------------------------------------------------+
| Gitlab | https://gitlab.kitware.com/computer-vision/cmd_queue |
+------------------+-------------------------------------------------------------------------------------+
| Pypi | https://pypi.org/project/cmd_queue |
+------------------+-------------------------------------------------------------------------------------+
| Slides | https://docs.google.com/presentation/d/1BjJkjMx6bxu1uek-hAGpwj760u9rraVn7st8J5OsZME |
+------------------+-------------------------------------------------------------------------------------+
This is a simple module for "generating" a bash script that schedules multiples
jobs (in parallel if possible) on a single machine. There are 3 backends with
increasing levels of complexity: serial, tmux, and slurm.
In serial mode, a single bash script gets written that executes your jobs in
sequence. There are no external dependencies
In tmux mode, multiple tmux sessions get opened and each of them executes your
independent parts of your jobs. Dependencies are handled.
In slurm mode, a real heavy-weight scheduling algorithm is used. In this mode
we simply convert your jobs to slurm commands and execute them.
Under the hood we build a DAG based on your specified dependencies and use this
to appropriately order jobs.
By default, bash scripts that would execute your jobs print to the console.
This gives the user fine-grained control if they only want to run a subset of a
pipeline manually. But if asked to run, cmd_queue will execute the bash jobs.
Features
~~~~~~~~
* Bash command scheduling
* Execution is optional, can just print commands instead
* No-parallelism always-available serial backend
* Tmux based lightweight backend
* Slurm based heavyweight backend
* Python and Bash interface
* Rich monitoring / live-control
Installation
============
The cmd_queue package is available on pypi.
.. code:: bash
pip install cmd_queue
The serial queue backend will always work. To gain access other backends you
must install their associated dependencies. The tmux backend is the easiest and
simply requires that tmux is installed (e.g. ``sudo apt install tmux`` on
Debian systems).
Other backends require more complex setups. The slurm backend will require that
`slurm is installed <https://slurm.schedmd.com/quickstart_admin.html>`_ and the
daemon is running. The slurm backend is functional and tested, but improvements
can still be made (help wanted). The airflow backend similarly requires a
configured airflow server, but is not fully functional or tested (contributions
to make airflow work / easier are wanted!).
Tmux Queue Demo
===============
After installing, the following command runs a demo of the tmux queue:
.. code:: bash
# Reproduce the
INTERACTIVE_TEST=1 xdoctest -m cmd_queue.tmux_queue TMUXMultiQueue.monitor:1
This executes the following code, which creates two parallel tmux workers and
submits several bash jobs with non-trivial dependencies.
.. code:: python
# xdoctest: +REQUIRES(env:INTERACTIVE_TEST)
from cmd_queue.tmux_queue import * # NOQA
# Setup a lot of longer running jobs
n = 2
self = TMUXMultiQueue(size=n, name='demo_cmd_queue')
first_job = None
for i in range(n):
prev_job = None
for j in range(4):
command = f'sleep 1 && echo "This is job {i}.{j}"'
job = self.submit(command, depends=prev_job)
prev_job = job
first_job = first_job or job
command = f'sleep 1 && echo "this is the last job"'
job = self.submit(command, depends=[prev_job, first_job])
self.print_commands(style='rich')
self.print_graph()
if self.is_available():
self.run(block=True, other_session_handler='kill')
When running the ``print_commands`` command will first display all of the submitted
commands that will be distributed across multiple new tmux sessions. These are
the commands will be executed. This is useful for spot checking that your bash
command templating is correct before the queue is executed with ``run``.
.. .. Screenshot of the print_commands output
.. image:: https://i.imgur.com/rVbyHzM.png
:height: 300px
:align: left
The ``print_graph`` command will render the DAG to be executed using
`network text <https://networkx.org/documentation/stable/reference/readwrite/generated/networkx.readwrite.text.write_network_text.html#networkx.readwrite.text.write_network_text>`_.
And finally ``run`` is called with ``block=True``, which starts executing the
DAG and displays progress and job status in rich or textual monitor.
.. .. image:: https://i.imgur.com/RbyTvP9.png
.. :height: 300px
.. :align: left
.. .. Animated gif of the queue from dev/record_demo.sh
.. image:: https://i.imgur.com/4mxFIMk.gif
:height: 300px
:align: left
While this is running it is possible to simply attach to a tmux sessions (e.g.
``tmux a``) and inspect a specific queue while it is running. (We recommend
using ``<ctrl-b>s`` inside of a tmux session to view and navigate through the
tmux sessions). Unlike the slurm backend, the entire execution of the DAG is
entirely transparent to the developer! The following screenshot shows the tmux
sessions spawned while running this demo.
.. .. Screenshot of the tmux sessions
.. image:: https://i.imgur.com/46LRK8M.png
:height: 300px
:align: left
By default, if there are no errors, these sessions will exit after execution
completes, but this is configurable. Likewise if there are errors, the tmux
sessions will persist to allow for debugging.
Modivation
==========
Recently, I needed to run several jobs on 4 jobs across 2 GPUs and then execute
a script after all of them were done. What I should have done was use slurm or
some other proper queuing system to schedule the jobs, but instead I wrote my
own hacky scheduler using tmux. I opened N (number of parallel workers) tmux
sessions and then I ran independent jobs in each different sessions.
This worked unreasonably well for my use cases, and it was nice to be able to effectively schedule jobs without heavyweight software like slurm on my machine.
Eventually I did get slurm on my machine, and I abstracted the API of my
tmux_queue to be a general "command queue" that can use 1 of 3 backends:
serial, tmux, or slurm.
Niche
=====
There are many DAG schedulers out there:
* airflow
* luigi
* submitit
* rq_scheduler
The the niche for this is when you have large pipelines of bash commands that
depend on each other and you want to template out those parameters with logic
that you define in Python.
We plan on adding an airflow backend.
Examples
========
All of the dependency checking and book keeping logic is handled in bash
itself. Write (or better yet template) your bash scripts in Python, and then
use cmd_queue to "transpile" these sequences of commands to pure bash.
.. code:: python
import cmd_queue
self = cmd_queue.Queue.create(name='demo_queue', backend='serial')
job1 = self.submit('echo hello && sleep 0.5')
job2 = self.submit('echo world && sleep 0.5', depends=[job1])
job3 = self.submit('echo foo && sleep 0.5')
job4 = self.submit('echo bar && sleep 0.5')
job5 = self.submit('echo spam && sleep 0.5', depends=[job1])
job6 = self.submit('echo spam && sleep 0.5')
job7 = self.submit('echo err && false')
job8 = self.submit('echo spam && sleep 0.5')
job9 = self.submit('echo eggs && sleep 0.5', depends=[job8])
job10 = self.submit('echo bazbiz && sleep 0.5', depends=[job9])
# Display the "user-friendly" pure bash
self.print_commands()
# Display the real bash that gets executed under the hood
# that is independencly executable, tracks the success / failure of each job,
# and manages dependencies.
self.print_commands(1, 1)
# Blocking will display a job monitor while it waits for everything to
# complete
self.run(block=True)
This prints the bash commands in an appropriate order to resolve dependencies.
.. code:: bash
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_cc9d551e/demo_queue_2022-04-08_cc9d551e.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 10 - demo_queue-job-0
echo hello && sleep 0.5
#
### Command 2 / 10 - demo_queue-job-1
echo world && sleep 0.5
#
### Command 3 / 10 - demo_queue-job-2
echo foo && sleep 0.5
#
### Command 4 / 10 - demo_queue-job-3
echo bar && sleep 0.5
#
### Command 5 / 10 - demo_queue-job-4
echo spam && sleep 0.5
#
### Command 6 / 10 - demo_queue-job-5
echo spam && sleep 0.5
#
### Command 7 / 10 - demo_queue-job-6
echo err && false
#
### Command 8 / 10 - demo_queue-job-7
echo spam && sleep 0.5
#
### Command 9 / 10 - demo_queue-job-8
echo eggs && sleep 0.5
#
### Command 10 / 10 - demo_queue-job-9
echo bazbiz && sleep 0.5
.. code:: python
# Need to tell the tmux queue how many processes can run at the same time
import cmd_queue
self = cmd_queue.Queue.create(size=4, name='demo_queue', backend='tmux')
job1 = self.submit('echo hello && sleep 0.5')
job2 = self.submit('echo world && sleep 0.5', depends=[job1])
job3 = self.submit('echo foo && sleep 0.5')
job4 = self.submit('echo bar && sleep 0.5')
job5 = self.submit('echo spam && sleep 0.5', depends=[job1])
job6 = self.submit('echo spam && sleep 0.5')
job7 = self.submit('echo err && false')
job8 = self.submit('echo spam && sleep 0.5')
job9 = self.submit('echo eggs && sleep 0.5', depends=[job8])
job10 = self.submit('echo bazbiz && sleep 0.5', depends=[job9])
# Display the "user-friendly" pure bash
self.print_commands()
# Display the real bash that gets executed under the hood
# that is independencly executable, tracks the success / failure of each job,
# and manages dependencies.
self.print_commands(1, 1)
# Blocking will display a job monitor while it waits for everything to
# complete
self.run(block=True)
This prints the sequence of bash commands that will be executed in each tmux session.
.. code:: bash
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_0_2022-04-08_a1ef7600.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 3 - demo_queue-job-7
echo spam && sleep 0.5
#
### Command 2 / 3 - demo_queue-job-8
echo eggs && sleep 0.5
#
### Command 3 / 3 - demo_queue-job-9
echo bazbiz && sleep 0.5
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_1_2022-04-08_a1ef7600.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 2 - demo_queue-job-2
echo foo && sleep 0.5
#
### Command 2 / 2 - demo_queue-job-6
echo err && false
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_2_2022-04-08_a1ef7600.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 2 - demo_queue-job-0
echo hello && sleep 0.5
#
### Command 2 / 2 - demo_queue-job-5
echo spam && sleep 0.5
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_3_2022-04-08_a1ef7600.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 1 - demo_queue-job-3
echo bar && sleep 0.5
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_4_2022-04-08_a1ef7600.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 1 - demo_queue-job-4
echo spam && sleep 0.5
# --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_5_2022-04-08_a1ef7600.sh
#!/bin/bash
#
# Jobs
#
### Command 1 / 1 - demo_queue-job-1
echo world && sleep 0.5
Slurm mode is the real deal. But you need slurm installed on your machint to
use it. Asking for tmux is a might ligher weight tool. We can specify slurm
options here
.. code:: python
import cmd_queue
self = cmd_queue.Queue.create(name='demo_queue', backend='slurm')
job1 = self.submit('echo hello && sleep 0.5', cpus=4, mem='8GB')
job2 = self.submit('echo world && sleep 0.5', depends=[job1], parition='default')
job3 = self.submit('echo foo && sleep 0.5')
job4 = self.submit('echo bar && sleep 0.5')
job5 = self.submit('echo spam && sleep 0.5', depends=[job1])
job6 = self.submit('echo spam && sleep 0.5')
job7 = self.submit('echo err && false')
job8 = self.submit('echo spam && sleep 0.5')
job9 = self.submit('echo eggs && sleep 0.5', depends=[job8])
job10 = self.submit('echo bazbiz && sleep 0.5', depends=[job9])
# Display the "user-friendly" pure bash
self.print_commands()
# Display the real bash that gets executed under the hood
# that is independencly executable, tracks the success / failure of each job,
# and manages dependencies.
self.print_commands(1, 1)
# Blocking will display a job monitor while it waits for everything to
# complete
self.run(block=True)
This prints the very simple slurm submission script:
.. code:: bash
# --- /home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/demo_queue-20220408T170615-a9e238b5.sh
mkdir -p "$HOME/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs"
JOB_000=$(sbatch --job-name="J0000-demo_queue-20220408T170615-a9e238b5" --cpus-per-task=4 --mem=8000 --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0000-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo hello && sleep 0.5' --parsable)
JOB_001=$(sbatch --job-name="J0002-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0002-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo foo && sleep 0.5' --parsable)
JOB_002=$(sbatch --job-name="J0003-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0003-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo bar && sleep 0.5' --parsable)
JOB_003=$(sbatch --job-name="J0005-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0005-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo spam && sleep 0.5' --parsable)
JOB_004=$(sbatch --job-name="J0006-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0006-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo err && false' --parsable)
JOB_005=$(sbatch --job-name="J0007-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0007-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo spam && sleep 0.5' --parsable)
JOB_006=$(sbatch --job-name="J0001-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0001-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo world && sleep 0.5' "--dependency=afterok:${JOB_000}" --parsable)
JOB_007=$(sbatch --job-name="J0004-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0004-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo spam && sleep 0.5' "--dependency=afterok:${JOB_000}" --parsable)
JOB_008=$(sbatch --job-name="J0008-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0008-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo eggs && sleep 0.5' "--dependency=afterok:${JOB_005}" --parsable)
JOB_009=$(sbatch --job-name="J0009-demo_queue-20220408T170615-a9e238b5" --output="/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0009-demo_queue-20220408T170615-a9e238b5.sh" --wrap 'echo bazbiz && sleep 0.5' "--dependency=afterok:${JOB_008}" --parsable)
.. |Pypi| image:: https://img.shields.io/pypi/v/cmd_queue.svg
:target: https://pypi.python.org/pypi/cmd_queue
.. |Downloads| image:: https://img.shields.io/pypi/dm/cmd_queue.svg
:target: https://pypistats.org/packages/cmd_queue
.. |ReadTheDocs| image:: https://readthedocs.org/projects/cmd-queue/badge/?version=release
:target: https://cmd-queue.readthedocs.io/en/release/
.. # See: https://ci.appveyor.com/project/jon.crall/cmd_queue/settings/badges
.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/py3s2d6tyfjc8lm3/branch/main?svg=true
:target: https://ci.appveyor.com/project/jon.crall/cmd_queue/branch/main
.. |GitlabCIPipeline| image:: https://gitlab.kitware.com/computer-vision/cmd_queue/badges/main/pipeline.svg
:target: https://gitlab.kitware.com/computer-vision/cmd_queue/-/jobs
.. |GitlabCICoverage| image:: https://gitlab.kitware.com/computer-vision/cmd_queue/badges/main/coverage.svg?job=coverage
:target: https://gitlab.kitware.com/computer-vision/cmd_queue/commits/main
.. |CircleCI| image:: https://circleci.com/gh/Erotemic/cmd_queue.svg?style=svg
:target: https://circleci.com/gh/Erotemic/cmd_queue
.. |Travis| image:: https://img.shields.io/travis/Erotemic/cmd_queue/main.svg?label=Travis%20CI
:target: https://travis-ci.org/Erotemic/cmd_queue
.. |Codecov| image:: https://codecov.io/github/Erotemic/cmd_queue/badge.svg?branch=main&service=github
:target: https://codecov.io/github/Erotemic/cmd_queue?branch=main
Raw data
{
"_id": null,
"home_page": "https://gitlab.kitware.com/computer-vision/cmd_queue",
"name": "cmd-queue",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Kitware Inc., Jon Crall",
"author_email": "kitware@kitware.com, jon.crall@kitware.com",
"download_url": null,
"platform": null,
"description": "Command Queue - cmd_queue\n=========================\n\n.. .. |Appveyor| |Codecov|\n\n|Pypi| |Downloads| |GitlabCIPipeline| |GitlabCICoverage| |ReadTheDocs|\n\n\n+------------------+-------------------------------------------------------------------------------------+\n| Read the docs | https://cmd-queue.readthedocs.io |\n+------------------+-------------------------------------------------------------------------------------+\n| Gitlab | https://gitlab.kitware.com/computer-vision/cmd_queue |\n+------------------+-------------------------------------------------------------------------------------+\n| Pypi | https://pypi.org/project/cmd_queue |\n+------------------+-------------------------------------------------------------------------------------+\n| Slides | https://docs.google.com/presentation/d/1BjJkjMx6bxu1uek-hAGpwj760u9rraVn7st8J5OsZME |\n+------------------+-------------------------------------------------------------------------------------+\n\n\nThis is a simple module for \"generating\" a bash script that schedules multiples\njobs (in parallel if possible) on a single machine. There are 3 backends with\nincreasing levels of complexity: serial, tmux, and slurm.\n\nIn serial mode, a single bash script gets written that executes your jobs in\nsequence. There are no external dependencies\n\nIn tmux mode, multiple tmux sessions get opened and each of them executes your\nindependent parts of your jobs. Dependencies are handled.\n\nIn slurm mode, a real heavy-weight scheduling algorithm is used. In this mode\nwe simply convert your jobs to slurm commands and execute them.\n\nUnder the hood we build a DAG based on your specified dependencies and use this\nto appropriately order jobs.\n\nBy default, bash scripts that would execute your jobs print to the console.\nThis gives the user fine-grained control if they only want to run a subset of a\npipeline manually. But if asked to run, cmd_queue will execute the bash jobs.\n\nFeatures\n~~~~~~~~\n\n* Bash command scheduling\n\n* Execution is optional, can just print commands instead\n\n* No-parallelism always-available serial backend\n\n* Tmux based lightweight backend\n\n* Slurm based heavyweight backend\n\n* Python and Bash interface\n\n* Rich monitoring / live-control\n\n\nInstallation\n============\n\nThe cmd_queue package is available on pypi.\n\n.. code:: bash\n\n pip install cmd_queue\n\nThe serial queue backend will always work. To gain access other backends you\nmust install their associated dependencies. The tmux backend is the easiest and\nsimply requires that tmux is installed (e.g. ``sudo apt install tmux`` on\nDebian systems).\n\nOther backends require more complex setups. The slurm backend will require that\n`slurm is installed <https://slurm.schedmd.com/quickstart_admin.html>`_ and the\ndaemon is running. The slurm backend is functional and tested, but improvements\ncan still be made (help wanted). The airflow backend similarly requires a\nconfigured airflow server, but is not fully functional or tested (contributions\nto make airflow work / easier are wanted!).\n\n\nTmux Queue Demo\n===============\n\nAfter installing, the following command runs a demo of the tmux queue:\n\n.. code:: bash\n\n # Reproduce the\n INTERACTIVE_TEST=1 xdoctest -m cmd_queue.tmux_queue TMUXMultiQueue.monitor:1\n\n\nThis executes the following code, which creates two parallel tmux workers and\nsubmits several bash jobs with non-trivial dependencies.\n\n.. code:: python\n\n # xdoctest: +REQUIRES(env:INTERACTIVE_TEST)\n from cmd_queue.tmux_queue import * # NOQA\n # Setup a lot of longer running jobs\n n = 2\n self = TMUXMultiQueue(size=n, name='demo_cmd_queue')\n first_job = None\n for i in range(n):\n prev_job = None\n for j in range(4):\n command = f'sleep 1 && echo \"This is job {i}.{j}\"'\n job = self.submit(command, depends=prev_job)\n prev_job = job\n first_job = first_job or job\n command = f'sleep 1 && echo \"this is the last job\"'\n job = self.submit(command, depends=[prev_job, first_job])\n self.print_commands(style='rich')\n self.print_graph()\n if self.is_available():\n self.run(block=True, other_session_handler='kill')\n\n\nWhen running the ``print_commands`` command will first display all of the submitted\ncommands that will be distributed across multiple new tmux sessions. These are\nthe commands will be executed. This is useful for spot checking that your bash\ncommand templating is correct before the queue is executed with ``run``.\n\n\n.. .. Screenshot of the print_commands output\n.. image:: https://i.imgur.com/rVbyHzM.png\n :height: 300px\n :align: left\n\n\nThe ``print_graph`` command will render the DAG to be executed using\n`network text <https://networkx.org/documentation/stable/reference/readwrite/generated/networkx.readwrite.text.write_network_text.html#networkx.readwrite.text.write_network_text>`_.\nAnd finally ``run`` is called with ``block=True``, which starts executing the\nDAG and displays progress and job status in rich or textual monitor.\n\n.. .. image:: https://i.imgur.com/RbyTvP9.png\n.. :height: 300px\n.. :align: left\n\n.. .. Animated gif of the queue from dev/record_demo.sh\n.. image:: https://i.imgur.com/4mxFIMk.gif\n :height: 300px\n :align: left\n\n\nWhile this is running it is possible to simply attach to a tmux sessions (e.g.\n``tmux a``) and inspect a specific queue while it is running. (We recommend\nusing ``<ctrl-b>s`` inside of a tmux session to view and navigate through the\ntmux sessions). Unlike the slurm backend, the entire execution of the DAG is\nentirely transparent to the developer! The following screenshot shows the tmux\nsessions spawned while running this demo.\n\n.. .. Screenshot of the tmux sessions\n.. image:: https://i.imgur.com/46LRK8M.png\n :height: 300px\n :align: left\n\nBy default, if there are no errors, these sessions will exit after execution\ncompletes, but this is configurable. Likewise if there are errors, the tmux\nsessions will persist to allow for debugging.\n\n\nModivation\n==========\nRecently, I needed to run several jobs on 4 jobs across 2 GPUs and then execute\na script after all of them were done. What I should have done was use slurm or\nsome other proper queuing system to schedule the jobs, but instead I wrote my\nown hacky scheduler using tmux. I opened N (number of parallel workers) tmux\nsessions and then I ran independent jobs in each different sessions.\n\nThis worked unreasonably well for my use cases, and it was nice to be able to effectively schedule jobs without heavyweight software like slurm on my machine.\n\nEventually I did get slurm on my machine, and I abstracted the API of my\ntmux_queue to be a general \"command queue\" that can use 1 of 3 backends:\nserial, tmux, or slurm.\n\n\nNiche\n=====\nThere are many DAG schedulers out there:\n\n * airflow\n * luigi\n * submitit\n * rq_scheduler\n\n\nThe the niche for this is when you have large pipelines of bash commands that\ndepend on each other and you want to template out those parameters with logic\nthat you define in Python.\n\nWe plan on adding an airflow backend.\n\n\nExamples\n========\n\n\nAll of the dependency checking and book keeping logic is handled in bash\nitself. Write (or better yet template) your bash scripts in Python, and then\nuse cmd_queue to \"transpile\" these sequences of commands to pure bash.\n\n\n.. code:: python\n\n import cmd_queue\n self = cmd_queue.Queue.create(name='demo_queue', backend='serial')\n job1 = self.submit('echo hello && sleep 0.5')\n job2 = self.submit('echo world && sleep 0.5', depends=[job1])\n job3 = self.submit('echo foo && sleep 0.5')\n job4 = self.submit('echo bar && sleep 0.5')\n job5 = self.submit('echo spam && sleep 0.5', depends=[job1])\n job6 = self.submit('echo spam && sleep 0.5')\n job7 = self.submit('echo err && false')\n job8 = self.submit('echo spam && sleep 0.5')\n job9 = self.submit('echo eggs && sleep 0.5', depends=[job8])\n job10 = self.submit('echo bazbiz && sleep 0.5', depends=[job9])\n\n # Display the \"user-friendly\" pure bash\n self.print_commands()\n\n # Display the real bash that gets executed under the hood\n # that is independencly executable, tracks the success / failure of each job,\n # and manages dependencies.\n self.print_commands(1, 1)\n\n # Blocking will display a job monitor while it waits for everything to\n # complete\n self.run(block=True)\n\n\nThis prints the bash commands in an appropriate order to resolve dependencies.\n\n\n.. code:: bash\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_cc9d551e/demo_queue_2022-04-08_cc9d551e.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 10 - demo_queue-job-0\n echo hello && sleep 0.5\n #\n ### Command 2 / 10 - demo_queue-job-1\n echo world && sleep 0.5\n #\n ### Command 3 / 10 - demo_queue-job-2\n echo foo && sleep 0.5\n #\n ### Command 4 / 10 - demo_queue-job-3\n echo bar && sleep 0.5\n #\n ### Command 5 / 10 - demo_queue-job-4\n echo spam && sleep 0.5\n #\n ### Command 6 / 10 - demo_queue-job-5\n echo spam && sleep 0.5\n #\n ### Command 7 / 10 - demo_queue-job-6\n echo err && false\n #\n ### Command 8 / 10 - demo_queue-job-7\n echo spam && sleep 0.5\n #\n ### Command 9 / 10 - demo_queue-job-8\n echo eggs && sleep 0.5\n #\n ### Command 10 / 10 - demo_queue-job-9\n echo bazbiz && sleep 0.5\n\n\n\n.. code:: python\n\n # Need to tell the tmux queue how many processes can run at the same time\n import cmd_queue\n self = cmd_queue.Queue.create(size=4, name='demo_queue', backend='tmux')\n job1 = self.submit('echo hello && sleep 0.5')\n job2 = self.submit('echo world && sleep 0.5', depends=[job1])\n job3 = self.submit('echo foo && sleep 0.5')\n job4 = self.submit('echo bar && sleep 0.5')\n job5 = self.submit('echo spam && sleep 0.5', depends=[job1])\n job6 = self.submit('echo spam && sleep 0.5')\n job7 = self.submit('echo err && false')\n job8 = self.submit('echo spam && sleep 0.5')\n job9 = self.submit('echo eggs && sleep 0.5', depends=[job8])\n job10 = self.submit('echo bazbiz && sleep 0.5', depends=[job9])\n\n # Display the \"user-friendly\" pure bash\n self.print_commands()\n\n # Display the real bash that gets executed under the hood\n # that is independencly executable, tracks the success / failure of each job,\n # and manages dependencies.\n self.print_commands(1, 1)\n\n # Blocking will display a job monitor while it waits for everything to\n # complete\n self.run(block=True)\n\n\nThis prints the sequence of bash commands that will be executed in each tmux session.\n\n.. code:: bash\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_0_2022-04-08_a1ef7600.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 3 - demo_queue-job-7\n echo spam && sleep 0.5\n #\n ### Command 2 / 3 - demo_queue-job-8\n echo eggs && sleep 0.5\n #\n ### Command 3 / 3 - demo_queue-job-9\n echo bazbiz && sleep 0.5\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_1_2022-04-08_a1ef7600.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 2 - demo_queue-job-2\n echo foo && sleep 0.5\n #\n ### Command 2 / 2 - demo_queue-job-6\n echo err && false\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_2_2022-04-08_a1ef7600.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 2 - demo_queue-job-0\n echo hello && sleep 0.5\n #\n ### Command 2 / 2 - demo_queue-job-5\n echo spam && sleep 0.5\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_3_2022-04-08_a1ef7600.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 1 - demo_queue-job-3\n echo bar && sleep 0.5\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_4_2022-04-08_a1ef7600.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 1 - demo_queue-job-4\n echo spam && sleep 0.5\n\n # --- /home/joncrall/.cache/base_queue/demo_queue_2022-04-08_a1ef7600/queue_demo_queue_5_2022-04-08_a1ef7600.sh\n\n #!/bin/bash\n #\n # Jobs\n #\n ### Command 1 / 1 - demo_queue-job-1\n echo world && sleep 0.5\n\n\n\nSlurm mode is the real deal. But you need slurm installed on your machint to\nuse it. Asking for tmux is a might ligher weight tool. We can specify slurm\noptions here\n\n.. code:: python\n\n import cmd_queue\n self = cmd_queue.Queue.create(name='demo_queue', backend='slurm')\n job1 = self.submit('echo hello && sleep 0.5', cpus=4, mem='8GB')\n job2 = self.submit('echo world && sleep 0.5', depends=[job1], parition='default')\n job3 = self.submit('echo foo && sleep 0.5')\n job4 = self.submit('echo bar && sleep 0.5')\n job5 = self.submit('echo spam && sleep 0.5', depends=[job1])\n job6 = self.submit('echo spam && sleep 0.5')\n job7 = self.submit('echo err && false')\n job8 = self.submit('echo spam && sleep 0.5')\n job9 = self.submit('echo eggs && sleep 0.5', depends=[job8])\n job10 = self.submit('echo bazbiz && sleep 0.5', depends=[job9])\n\n # Display the \"user-friendly\" pure bash\n self.print_commands()\n\n # Display the real bash that gets executed under the hood\n # that is independencly executable, tracks the success / failure of each job,\n # and manages dependencies.\n self.print_commands(1, 1)\n\n # Blocking will display a job monitor while it waits for everything to\n # complete\n self.run(block=True)\n\n\nThis prints the very simple slurm submission script:\n\n.. code:: bash\n\n # --- /home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/demo_queue-20220408T170615-a9e238b5.sh\n\n mkdir -p \"$HOME/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs\"\n JOB_000=$(sbatch --job-name=\"J0000-demo_queue-20220408T170615-a9e238b5\" --cpus-per-task=4 --mem=8000 --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0000-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo hello && sleep 0.5' --parsable)\n JOB_001=$(sbatch --job-name=\"J0002-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0002-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo foo && sleep 0.5' --parsable)\n JOB_002=$(sbatch --job-name=\"J0003-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0003-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo bar && sleep 0.5' --parsable)\n JOB_003=$(sbatch --job-name=\"J0005-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0005-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo spam && sleep 0.5' --parsable)\n JOB_004=$(sbatch --job-name=\"J0006-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0006-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo err && false' --parsable)\n JOB_005=$(sbatch --job-name=\"J0007-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0007-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo spam && sleep 0.5' --parsable)\n JOB_006=$(sbatch --job-name=\"J0001-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0001-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo world && sleep 0.5' \"--dependency=afterok:${JOB_000}\" --parsable)\n JOB_007=$(sbatch --job-name=\"J0004-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0004-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo spam && sleep 0.5' \"--dependency=afterok:${JOB_000}\" --parsable)\n JOB_008=$(sbatch --job-name=\"J0008-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0008-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo eggs && sleep 0.5' \"--dependency=afterok:${JOB_005}\" --parsable)\n JOB_009=$(sbatch --job-name=\"J0009-demo_queue-20220408T170615-a9e238b5\" --output=\"/home/joncrall/.cache/slurm_queue/demo_queue-20220408T170615-a9e238b5/logs/J0009-demo_queue-20220408T170615-a9e238b5.sh\" --wrap 'echo bazbiz && sleep 0.5' \"--dependency=afterok:${JOB_008}\" --parsable)\n\n\n\n.. |Pypi| image:: https://img.shields.io/pypi/v/cmd_queue.svg\n :target: https://pypi.python.org/pypi/cmd_queue\n\n.. |Downloads| image:: https://img.shields.io/pypi/dm/cmd_queue.svg\n :target: https://pypistats.org/packages/cmd_queue\n\n.. |ReadTheDocs| image:: https://readthedocs.org/projects/cmd-queue/badge/?version=release\n :target: https://cmd-queue.readthedocs.io/en/release/\n\n.. # See: https://ci.appveyor.com/project/jon.crall/cmd_queue/settings/badges\n.. |Appveyor| image:: https://ci.appveyor.com/api/projects/status/py3s2d6tyfjc8lm3/branch/main?svg=true\n :target: https://ci.appveyor.com/project/jon.crall/cmd_queue/branch/main\n\n.. |GitlabCIPipeline| image:: https://gitlab.kitware.com/computer-vision/cmd_queue/badges/main/pipeline.svg\n :target: https://gitlab.kitware.com/computer-vision/cmd_queue/-/jobs\n\n.. |GitlabCICoverage| image:: https://gitlab.kitware.com/computer-vision/cmd_queue/badges/main/coverage.svg?job=coverage\n :target: https://gitlab.kitware.com/computer-vision/cmd_queue/commits/main\n\n.. |CircleCI| image:: https://circleci.com/gh/Erotemic/cmd_queue.svg?style=svg\n :target: https://circleci.com/gh/Erotemic/cmd_queue\n\n.. |Travis| image:: https://img.shields.io/travis/Erotemic/cmd_queue/main.svg?label=Travis%20CI\n :target: https://travis-ci.org/Erotemic/cmd_queue\n\n.. |Codecov| image:: https://codecov.io/github/Erotemic/cmd_queue/badge.svg?branch=main&service=github\n :target: https://codecov.io/github/Erotemic/cmd_queue?branch=main\n",
"bugtrack_url": null,
"license": "Apache 2",
"summary": "The cmd_queue module for a DAG of bash commands",
"version": "0.1.20",
"project_urls": {
"Homepage": "https://gitlab.kitware.com/computer-vision/cmd_queue"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "45aaa090657a9a6f609c8ca19650eb96e1492f1ac2399dfa3238d26330533b4d",
"md5": "7229d3628804ba470755dbf7fa56148c",
"sha256": "52170bf8d081b8cbafdeede098e3b23d6610f816ed2d52b5819fd563cbbd2bd6"
},
"downloads": -1,
"filename": "cmd_queue-0.1.20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7229d3628804ba470755dbf7fa56148c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 84125,
"upload_time": "2024-03-20T02:55:53",
"upload_time_iso_8601": "2024-03-20T02:55:53.508887Z",
"url": "https://files.pythonhosted.org/packages/45/aa/a090657a9a6f609c8ca19650eb96e1492f1ac2399dfa3238d26330533b4d/cmd_queue-0.1.20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-20 02:55:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "cmd-queue"
}
JSON