doc: add fair-share documentation #536
Conversation
cmoussa1
added
documentation
cmoussa1
changed the title
doc/components/fair-share.rst
Outdated
|
|
||
| flux-accounting dynamically adjusts fair-share as resources are consumed. | ||
| Historical job usage diminishes in signficance over time, ensuring that | ||
| long-term heavy usage does not permanently impact an association's fair-share. |
There was a problem hiding this comment.
This doesn't quite make sense to me -- it seems like the diminishing significance of past data would mean that short term heavy usage would not permanently impact an association's fair share. If an association had long-term (I'm thinking over a span of weeks, months, years) we would want that to diminish their fair-share? Am I missing something?
There was a problem hiding this comment.
No, I think you're absolutely right. I think I changed the structure of this sentence halfway through to talk about short-term usage versus long-term usage and never actually changed the term. Good catch! I'll change this to short-term
doc/components/fair-share.rst
Outdated
| weight at 1.84467. Therefore, ``leaf.3.1`` receives the highest rank of all of | ||
| the users. ``leaf.3.2`` follows with the second highest rank, and ``account3`` | ||
| is now fully sorted. We repeat this process for the rest of the banks in the | ||
| hierarchy. |
There was a problem hiding this comment.
Suggestion: a sorted table would be really helpful for illustration here
doc/components/fair-share.rst
Outdated
|
|
||
| .. code-block:: text | ||
|
|
||
| Bank|Username|RawShares|RawUsage|Fairshare |
There was a problem hiding this comment.
You might want to turn this into a table too ;) (sorry, I know RST is annoying!)
cmoussa1
force-pushed
the
fair-share.documentation
branch
from
3d571b1 to
6ed796a
Compare
|
Thanks for reviewing @wihobbs!! I just force-pushed up some changes based on your feedback. Let me know what you think! |
| is now fully sorted. We repeat this process for the rest of the banks in the | ||
| hierarchy: | ||
|
|
||
| .. list-table:: |
There was a problem hiding this comment.
I think this is what I'd like to see for this table:
| rank | parent | name | weight |
|---|---|---|---|
| root | |||
| root | account3 | 1.1982 | |
| 1 | account3 | leaf3.1 | 1.84467 |
| 2 | account3 | leaf3.2 | 0.90901 |
| root | account2 | 1.08927 | |
| 3 | account2 | leaf2.1 | 1.25 |
| 4 | account2 | leaf2.2 | 0.333333 |
| root | account1 | 0.990246 | |
| 5 | account1 | leaf1.3 | 10.9009 |
| 6 | account1 | leaf1.1 | 0.109009 |
| 7 | account1 | leaf1.2 | 0.990991 |
It illustrates the "ranking" process and helps explain that accounts are sorted first, then leaves, then the leaves are individually ranked. Does that make sense to you?
There was a problem hiding this comment.
Sure! I can copy this table over. That makes sense
There was a problem hiding this comment.
Just force-pushed up a change to use this table that includes the rank next to the users.
doc/components/fair-share.rst
Outdated
|
|
||
| \text{F}_{leaf.2.2} = \frac{\text{rank}_{leaf.2.2}}{\text{N}_{users}} = \frac{\text{4}}{\text{7}} = \text{0.571429} | ||
|
|
||
| After performing a weighted walk on this hierarchy, the fair-share distribution |
There was a problem hiding this comment.
LOL I googled it and I get a bunch of fitness articles
There was a problem hiding this comment.
Weighted walk here is just the term for how the hierarchy is being traversed in order to calculate the weight for each bank + user, i.e it is traversing the tree starting at the root of the tree and calculating the weight for each bank and user.
cmoussa1
force-pushed
the
fair-share.documentation
branch
from
6ed796a to
ba3803a
Compare
Problem: flux-accounting doesn't really have any in-depth documentation about how fair-share is calculated for a hierarchy of banks and users. Add some documentation about how fair-share is calculated for a hierarchy of banks and users in flux-accounting. Create an example hierarchy and walk through the process of calculating fair-share for an association.
cmoussa1
force-pushed
the
fair-share.documentation
branch
from
ba3803a to
483bc82
Compare
|
Thanks for your help reviewing this @wihobbs! I went ahead and added a weighted walk definition to this page too. I'll go ahead and set MWP here |
Problem
flux-accounting doesn't really have any in-depth documentation about how fair-share is calculated for a hierarchy of banks and users.
This PR adds some documentation about how fair-share is calculated for a hierarchy of banks and users in flux-accounting. I've also created a small example hierarchy and walked through the process of calculating fair-share for an association.