From 41900e5624aa3c6b097010aa1f8b9e9dba7da936 Mon Sep 17 00:00:00 2001
From: Christopher Moussa <moussa1@llnl.gov>
Date: Mon, 25 Nov 2024 12:36:57 -0800
Subject: [PATCH] doc: add example on priority configs for queues

Problem: The accounting guide makes mention of setting priorities for a
queue so that it can affect the priority calculation for a submitted
job, but there are no examples this configuration anywhere in the docs.

Add a section in the Multi-Factor Priority Plugin section on how
configuring priorities for certain queues affects a job's calculated
priority. Write a short example on how the priority for a job changes
depending on this configuration.
---
 doc/guide/accounting-guide.rst | 48 ++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/doc/guide/accounting-guide.rst b/doc/guide/accounting-guide.rst
index ffcf86e8..6f73ba51 100644
--- a/doc/guide/accounting-guide.rst
+++ b/doc/guide/accounting-guide.rst
@@ -398,6 +398,54 @@ Both "types" of jobs, *running* and *active*, are based on Flux's definitions
 of job states_. *Active* jobs can be in any state but INACTIVE. *Running* jobs
 are jobs in either RUN or CLEANUP states.
 
+Queue Priority Calculation Configuration
+========================================
+
+Mentioned above, the queue that a job is submitted under can influence its
+calculated priority. Priorities specific to queues can be configured in the
+flux-accounting database when they are first added:
+
+.. code-block:: console
+
+  $ flux account add-queue bronze --priority=100
+
+Or changed later on:
+
+.. code-block:: console
+
+  $ flux account edit-queue bronze --priority=500
+
+If a priority is not specified when a queue is added, it will have a priority
+of 0, meaning it will not positively or negatively affect a job's integer
+priority.
+
+example
+-------
+
+Given an association with a fair-share value of 0.5, the priority plugin loaded
+and configured to just use its default factor weights, let's walk through how a
+job's priority could be affected by running under certain queues. Assume the
+following configuration for queues and their associated priorities:
+
++-------------+----------+
+| queue       | priority |
++=============+==========+
+| bronze      | 100      |
++-------------+----------+
+| silver      | 300      |
++-------------+----------+
+| gold        | 500      |
++-------------+----------+
+
+If the association submitted their job with default urgency in the ``bronze``
+queue, their priority would be:
+
+:math:`P = (0.5 \times 100000) + (100 \times 10000) + (16 - 16) = (50000) + (1000000) = 1050000`
+
+versus this same job submitted in the ``gold`` queue:
+
+:math:`P = (0.5 \times 100000) + (500 \times 10000) + (16 - 16) = (50000) + (5000000) = 5050000`
+
 .. _glossary-section:
 
 ********