diff --git a/tutorials/commands/flux-mini-submit.rst b/tutorials/commands/flux-mini-submit.rst new file mode 100644 index 00000000..41b7ed23 --- /dev/null +++ b/tutorials/commands/flux-mini-submit.rst @@ -0,0 +1,74 @@ +.. _flux-mini-submit: + +========================== +How to Submit Jobs in Flux +========================== + +Do you want to submit a job to Flux? Here's a short tutorial on how to do so! + +---------------------------- +Submit Jobs Using Flux's CLI +---------------------------- + +From within a Flux instance, you can submit your job on the command line with +optional arguments, resource options, per task options, and per resource +options: + +.. code-block:: sh + + $ flux mini submit --nodes=2 --ntasks=4 --cores-per-task=2 ./my_compute_script.lua 120 + ƒM5k8m7m + $ flux mini submit --nodes=1 --ntasks=1 --cores-per-task=2 ./my_other_script.lua 120 + ƒSUEFPDH + +In the above example, we are submitting two jobs with two different sets of +options to describe how we want our jobs to run. In the first submission, we +are asking for our job to start 4 tasks across 2 nodes, with 2 cores allocated +for each task. In the second submission, we are asking for our job to start 1 +task on just one node with 2 cores allocated for the task. + +There are many different options to customize your job submission. For further +details, please see :core:man1:`flux-mini`. + +A :ref:`jobID` (e.g., ``ƒSUEFPDH``) is returned for every job submitted. You can view +the status of your running jobs with ``flux jobs``: + +.. code-block:: sh + + $ flux jobs + JOBID USER NAME ST NTASKS NNODES TIME INFO + ƒSUEFPDH fluxuser my_other_s R 1 1 1.842s + ƒM5k8m7m fluxuser my_compute R 4 2 3.255s + +And that's it! If you have any questions, please +`let us know `_. + +------------------------------------- +More Examples of Submitting Flux Jobs +------------------------------------- + +.. code-block:: sh + + $ flux mini submit --nodes=2 --queue=foo --name=my_special_job ./my_job.lua + +This submits a job to the `foo` queue across two nodes, and sets a custom name +to the job. + +.. code-block:: sh + + $ flux mini submit --dry-run ./my_cool_job.lua + +If you don't want your job to actually run, but you are interested in looking +at the :ref:`jobspec` for your job, include the ``--dry-run`` option +when you submit your job. + +.. code-block:: sh + + $ flux mini submit --output=job-{{id}}.out ./my_super_cool_job.py + ƒ3D78hc3q + +If you want to bypass the :ref:`KVS` and specify a filename for STDOUT redirection, +include the ``--output`` option when submitting your job. You can format the +name of your output file using the jobID via mustache template. In the example +above, any output to STDOUT will be redirected to a file named +``job-ƒ3D78hc3q.out``. diff --git a/tutorials/commands/index.rst b/tutorials/commands/index.rst index 5c1e58b7..701a2ad4 100644 --- a/tutorials/commands/index.rst +++ b/tutorials/commands/index.rst @@ -7,6 +7,7 @@ Welcome to the Command Tutorials! These tutorials should help you to map specifi with your use case, and then see detailed usage. - ``flux proxy`` (:ref:`ssh-across-clusters`): "Send commands to a flux instance across clusters using ssh" + - ``flux-mini-submit`` (:ref:`flux-mini-submit`): "Submit a job in a Flux instance" This section is currently 🚧️ under construction 🚧️, so please come back later to see more command tutorials! @@ -15,4 +16,5 @@ This section is currently 🚧️ under construction 🚧️, so please come bac :maxdepth: 2 :caption: Command Tutorials - ssh-across-clusters \ No newline at end of file + ssh-across-clusters + flux-mini-submit \ No newline at end of file