minor bug fixing, refactoring, and doc improvements for benchmark-nq stuff

Makefile
 - remove a nonexistent and put in the two actual new PHONY's

benchmarking/quilc-mon-prof.lisp
 - add top-level documentation, explaining "WIP" limitation
 - restore use of sample-interval arg to MONITOR-RUN, left
   commented out in error
 - add doc string for MONITOR-RUN
 - remove depth check subsection, which contained obsolete code

benchmarking/quilc-perf.lisp
 - document format of *benchmark-quilc-perf-series*, which is also
   results returned by benchmark-nq and the format of the main arg to
   the CSV emitter.
 - replace two nearly identical CSV emitter functions by a single one,
   and add a doc string for it.

Author: David, Mark H

Makefile

@@ -164,7 +164,7 @@ test-ccl:
 ###############################################################################
 # BENCHMARKS
 ###############################################################################
-.PHONY: benchmark-qasm benchmark-qasm-big
+.PHONY: benchmark-qasm benchmark-nq benchmark-nq-2x
 
 benchmark-qasm:
 	$(QUICKLISP) \

benchmarking/quilc-mon-prof.lisp

@@ -9,14 +9,28 @@
 ;;;; Monitoring and Profiling
 
 ;; This builds on quilc-perf.lisp and is for monitoring and profiling,
-;; as opposed to simple benchmarks, and is a WIP.
+;; as opposed to simple benchmarks, and is a WIP in that we have not
+;; established a makefile entry to run this. That is because, while
+;; it's been useful to run for probing and experimenting in a REPL, we
+;; so far lack really good theory of operation and associated modes of
+;; running. We hope with time to get there.
 
 
 (defparameter *monitor-types*
   '(:mon #+sbcl :sb-sprof))
 
 (defun monitor-run (program-type chip-type nq repeats monitor
                     &optional report-type sample-interval)
+  "Do REPEATS perf runs for PROGRAM-TYPE and CHIP-TYPE (as documented
+   at the top of QUILC-PERF module) using the specified MONITOR, which
+   must be one of those in the list *monitor-types*.  Optional args
+   REPORT-TYPE and SAMPLE-INTERVAL are only relevant when MONITOR is
+   :SB-SPROF in which case REPORT-TYPE is passed as the same-named arg
+   to SB-SPROF:REPORT, and SAMPLE-INTERVAL is passed as the same-named
+   arg to SB-SPROF:START-PROFILING. Note as well that for :SB-SPROF
+   monitor, only the current thread is profiled. This returns no
+   useful value. It's just run in order to get output from the
+   monitor."
   (when (not (member monitor *monitor-types*))
     (unless (null monitor) ; if so, just silently default with no warning
       (warn "unrecognized monitor, should be one of ~s; using ~s"
@@ -55,8 +69,7 @@
          (progn
            (sb-sprof:reset)
            (sb-sprof:start-profiling
-            ;; :sample-interval (or sample-interval 0.005)    ; default = 0.01
-            :sample-interval 0.0001
+            :sample-interval (or sample-interval 0.005)    ; default = 0.01
             :threads (list sb-thread:*current-thread*))
            (funcall thunk)
            (sb-sprof:report
@@ -116,34 +129,6 @@
 
 
 
-
-;;;; depth check
-
-(defun quil-parse-to-logical-schedule (parse)
-  (let* ((instructions-vector (quil:parsed-program-executable-code parse))
-         (instructions-list (concatenate 'list instructions-vector))
-         (lsched (quil.si:make-lscheduler)))
-    (quil.si:append-instructions-to-lschedule lsched instructions-list)
-    lsched))
-
-(defun depth-check (nq)
-  (let* ((parse (build-benchmark-program nq :hadamard))
-         (logical-schedule (quil-parse-to-logical-schedule parse)))
-    (depth-check-1 logical-schedule)))
-
-(defun depth-check-1 (logical-schedule)
-  (let* ((old-walk-depth
-           (let ((quil::*new-walk* nil))
-             (quil::lscheduler-calculate-depth logical-schedule)))
-         (new-walk-depth
-           (let ((quil::*new-walk* t))
-             (quil::lscheduler-calculate-depth logical-schedule))))
-    (list
-     (= old-walk-depth new-walk-depth)
-     old-walk-depth new-walk-depth logical-schedule)))
-
-
-
 ;;;; SB-SPROF run 20, 50, 80, 110, 140
 
 (defun sb-sprof-run ()

benchmarking/quilc-perf.lisp

@@ -14,7 +14,7 @@
 ;;; We provide a few kinds of chips and Quil programs and several
 ;;; methods of benchmarking as a function of nQ.
 ;;;
-;;; The chip types: :fully-connectes, :linear 
+;;; The chip types: :fully-connected, :linear 
 ;;;
 ;;; The program types:
 ;;;
@@ -48,17 +48,24 @@
 (defvar *benchmark-quilc-perf-series* '()
   "Initially an empty list, gets set to the list of results by each
   run of benchmark-nq, provided as a developer convenience for later
-  perusal, e.g., in a REPL.")
+  perusal, e.g., in a REPL.  These results are in a list of sublists
+  of the form
+
+    ((program-type chip-type) . timings)
+
+  where timings is a list of lists of the form (nQ time), where time
+  is an integer as a multiple of internal-time-units-per-second. Each
+  sublist has the same length and contains the same nQ values.")
 
 (defun benchmark-nq ()
   (setq *benchmark-quilc-perf-series*
         (benchmark-quilc-perf
          :start *default-benchmark-nq-start*
          :step *default-benchmark-nq-step*
          :end *default-benchmark-nq-end*))
-  (csv-raw-timings *benchmark-quilc-perf-series*)
+  (csv-timings *benchmark-quilc-perf-series*)
   (terpri)
-  (csv-max-of-series-style *benchmark-quilc-perf-series*)
+  (csv-timings *benchmark-quilc-perf-series* :max-of-series-style t)
   *benchmark-quilc-perf-series*)
 
 (defparameter *benchmark-program-types*
@@ -219,68 +226,59 @@
                                          `(((,Program-type ,chip-type)
                                             ,@perf-series)))))))
 
-(defun csv-raw-timings (x)
-  ;; Arrange like so:
-  ;; header row:
-  ;; "nQ", program1/chip1, ..., programn, chipn"
-  ;; rest of rows:
-  ;; <nQ>, <time of program1/chip1>, ..., <time of programn/chipn>
+(defun csv-timings (x &key max-of-series-style)
+  "Output timing data X as comma-separated values like so
 
-  ;; header row:
-  (princ "nQ")
-  (loop :with rows := '()
-        :for ((chip-type program-type) . timings) :in x
-        :do (format t ", ~(~a/~a~)" chip-type program-type)
-            (loop :for (nq time) :in timings
-                  :as time-in-seconds-float
-                    := (internal-time-to-seconds time)
-                  :as row := (assoc nq rows)
-                  :when (null row)
-                    :do (setq row (list nq))
-                        (setq rows (nconc rows (list row)))
-                  :do (nconc row (list time-in-seconds-float)))
-        :finally (terpri)
-                 (loop :for (nq . times) :in rows
-                       :do (format t "~d" nq)
-                           (loop :for time :in times
-                                 :do (format t ", ~,3f" time))
-                           (terpri))
-                 (return rows)))
+header row:
+  \"nQ\", program/chip-1, ..., program/chip-n
+data rows:
+  <nQ>, <time of program/chip-1>, ..., <time of program/chip-n>
 
-(defun transform-val-to-ratio-of-max (original-val max-of-series)
-  (/ (float original-val) max-of-series))
+In the header row, each program/chip pair is the name of the program
+type and chip type, respectively. In the data rows each row represents
+a series of program/chip timings, each written as a floating point
+number.  MAX-OF-SERIES-STYLE defaults to false, but if specified true,
+each timing is converted to be a ratio of the origin timing to the
+maximum timing of the series.
 
-(defun csv-max-of-series-style (x)
-  ;; Arrange like so:
-  ;; header row:
-  ;; "nQ", program1/chip1, ..., programn, chipn"
-  ;; rest of rows:
-  ;; <nQ>, <time of program1/chip1>, ..., <time of programn/chipn>
+X's format is as documented for *benchmark-quilc-perf-series*.
 
+Besides outputting the rows as described, this returns a list of the
+data rows only, each row being of the form (nQ . timings), where nQ is
+a fixnum and timings is a list of floats."
   ;; header row:
   (princ "nQ")
   (loop :with rows := '()
         :for ((chip-type program-type) . timings) :in x
         :as max-of-series
-          := (loop :for (nil time) :in timings
-                   :maximize time)
+          := (and max-of-series-style
+                  (loop :for (nil time) :in timings
+                        :maximize time))
         :do (format t ", ~(~a/~a~)" chip-type program-type)
             (loop :for (nq time) :in timings
-                  :as time-ratio
-                    := (transform-val-to-ratio-of-max time max-of-series)
+                  :as time-as-float
+                    := (if max-of-series-style
+                           ;; time/max ratio
+                           (transform-val-to-ratio-of-max time max-of-series)
+                           ;; time in seconds
+                           (internal-time-to-seconds time))
                   :as row := (assoc nq rows)
                   :when (null row)
                     :do (setq row (list nq))
                         (setq rows (nconc rows (list row)))
-                  :do (nconc row (list time-ratio)))
+                  :do (nconc row (list time-as-float)))
         :finally (terpri)
+                 ;; data rows:
                  (loop :for (nq . times) :in rows
                        :do (format t "~d" nq)
                            (loop :for time :in times
                                  :do (format t ", ~,3f" time))
                            (terpri))
                  (return rows)))
 
+(defun transform-val-to-ratio-of-max (original-val max-of-series)
+  (/ (float original-val) max-of-series))
+