adding comments to sunspot scripts

sunspot/sunspot_nodes_broken.sh

 #! /bin/bash
 
+# goal: show state of nodes that are listed as broken
+# include: nodes with broken attribute set to True (excluded from workq)
+# output: hostname, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resources_available.broken=="True") | [.resources_available.host,.state] | @tsv'

sunspot/sunspot_nodes_debug.sh

 #! /bin/bash
 
+# goal: show state of debug nodes excluded from workq queue
+# include: nodes marked as debug
+# output: hostname, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resources_available.debug=="True") | [.resources_available.host,.state] | @tsv'

sunspot/sunspot_nodes_resv.sh

 #! /bin/bash
 
+# goal: show state of nodes currently under reservation
+# include: nodes with non-null resv attribute
+# output: hostname, resv attribute value, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resv!=null) | [.resources_available.host,.resv,.state] | @tsv'

sunspot/sunspot_nodes_special.sh

 #! /bin/bash
 
+# goal: print info about debug + validation nodes (which can overlap)
+# include: nodes marked as debug or validation
+# output: hostname, debug, validation, reservation, broken, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resources_available.debug=="True" or .resources_available.validation=="True") | [.resources_available.host,"DEBUG",.resources_available.debug=="True","VALIDATION",.resources_available.validation=="True","RESV",.resv!=null,"BROKEN",.resources_available.broken=="True","STATE",.state] | @tsv'

sunspot/sunspot_nodes_states.sh

 #! /bin/bash
 
+# goal: print list of current unique values for node state
+
 pbsnodes -a -F json | jq '[.nodes[].state] | unique'

sunspot/sunspot_nodes_unavailable.sh

 #! /bin/bash
 
+# goal: print info for nodes that are offline, down, broken, state-unknown, etc
+# include: nodes with states other than free or job-exclusive
+# include: nodes marked as broken
+# output: hostname, reservation, broken, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select( (.state!="free" and .state!="job-exclusive") or .resources_available.broken=="True") | [.resources_available.host,"RESV",.resv!=null,"BROKEN",.resources_available.broken=="True","STATE",.state] | @tsv'

sunspot/sunspot_nodes_validation.sh

 #! /bin/bash
 
+# goal: show state of validation nodes excluded from workq queue
+# include: nodes marked as validation
+# output: hostname, state
+
 pbsnodes -a -F json | jq -r '.nodes[] | select(.resources_available.validation=="True") | [.resources_available.host,.state] | @tsv'

sunspot/sunspot_nodes_workq.sh

 #! /bin/bash
 
+# goal: determine the max job size that could run in workq queue in near future
+# example: ./sunspot_nodes_workq.sh | wc -l
+# include: nodes in "free" or "job-exclusive" state
+# exclude: nodes marked as "debug", "validation", or "broken"
+# output: hostname, state
+# issues: unsure how state relates to reservations on sunspot
+
 pbsnodes -a -F json | jq -r '.nodes[] | select( (.state=="free" or .state=="job-exclusive") and .resources_available.debug!="True" and .resources_available.validation!="True" and .resources_available.broken!="True") | [.resources_available.host,.state] | @tsv'