From 9c2865468a3517f6960eb0e790098cc74a2bc835 Mon Sep 17 00:00:00 2001 From: Jim Garlick Date: Wed, 16 Oct 2024 13:18:30 -0700 Subject: [PATCH] doc: add priority equation to accounting guide Problem: the accounting guide uses words to describe how priority is calculated but words would be clearer. Add "queue" to the lists of factors and format the list as a dictionary rather than a bullet list. Use a math expression for the priority value. --- doc/guide/accounting-guide.rst | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/doc/guide/accounting-guide.rst b/doc/guide/accounting-guide.rst index 66e3886c..ffcf86e8 100644 --- a/doc/guide/accounting-guide.rst +++ b/doc/guide/accounting-guide.rst @@ -348,15 +348,24 @@ Multi-Factor Priority Plugin The multi-factor priority plugin is a jobtap_ plugin that generates an integer job priority for incoming jobs in a Flux system instance. It uses a number of factors to calculate a priority and, in the future, can add more -factors. Each factor has an associated integer weight that determines its -importance in the overall priority calculation. The current factors present in -the multi-factor priority plugin are: +factors. Each factor :math:`F` has an associated integer weight :math:`W` +that determines its importance in the overall priority calculation. The +current factors present in the multi-factor priority plugin are: -* **fair-share**: the ratio between the amount of resources allocated vs. resources +fair-share + The ratio between the amount of resources allocated vs. resources consumed. See the :ref:`Glossary definition ` for a more detailed explanation of how fair-share is utilized within flux-accounting. -* **urgency**: a user-controlled factor to prioritize their own jobs. +queue + A configurable factor assigned to a queue. + +urgency + A user-controlled factor to prioritize their own jobs. + +Thus the priority :math:`P` is calculated as follows: + +:math:`P = (F_{fairshare} \times W_{fairshare}) + (F_{queue} \times W_{queue}) + (F_{urgency} - 16)` Each of these factors can be configured with a custom weight to increase their relevance to the final calculation of a job's integer priority. By default,