digit_sum_study.dc

############################################################################
# This module was written so that I could have a clearer understanding     #
# of the musical implications of the various variable settings involved    #
# in the midi_digit_sum* examples.                                         #
#                                                                          #
# There are 2 public words: `run_sample` and `range_sample`                #
#                                                                          #
# `run_sample` will show `end - start` (default 1024) iterations of        #
# the output of `digit_sum`, given the variables set by the user.          #
# These variables are defined below, but can be changed so various         #
# behaviors can be studied, and a new run kicked off with `run_sample`.    #
# Some documention of these variables is inline below, as comments.        #
#                                                                          #
# `mul_study` will vary the `mul` from 2 to `study_end` and do a           #
# `run_sample` on each iteration. It will output lines that represent:     #
#                                                                          #
#   <current_mul> <min_count> <max_count> <max_count / min_count>          #
#                                                                          #
# ....where <min_count> is the digit_sum __least hit__ during the run,     #
# and <max_count> represents the digit_sum __most hit__ during the run.    #
# This allow one to understand the "meta-features" of a given run of       #
# `digit_sum` given a certain `base`, `wrap`, `shift`, and `slots`,        #
# while the `mul` changes. Using the MIDI examples, this will have musical #
# implications.                                                            #
############################################################################

"math.dc" import
"string.dc" import
"redis_midi.dc" import

32 const FIGURE_STORAGE_SIZE
var figures FIGURE_STORAGE_SIZE allot

var start
0 start !

var end
1024 end !

var study_end
129 study_end !

# used by the `draw_sample_infinite` routines as a global index
var x
0 x !

# `mul` and `base` are the core args consumed by `digit_sum`
var mul
1 mul !

var base
2 base !

# `wrap` is the largest digit sum (prior to shifting) that you
# want to "wrap" (AKA do a modulus operation) around.
var wrap
32 wrap !

# `scale` is an experimental scaling extension
var scale
1 scale !

# `shift` offsets the resulting digit_sum by the assigned amount.
# If in a musical scale/gamut situation, this would be a "mode".
var shift
0 shift !

# `slots` would, for example, represent the largest digit_sum
# _after shifting_ that you'd want to "wrap" (AKA do an `absmod` modulus wrap)
# around. If you set/keep `wrap` and `slots` to 32, and `shift` to 0,
# the "natural behavior" of `digit_sum` is shown, which can be useful for
# understanding.
var slots
32 slots !

var drawchars
"0123456789abcdefghijklmnopqrstuvwxyz" drawchars !

: _clear_figures
  FIGURE_STORAGE_SIZE times
    0 figures i + !
  again
;

: _show_figures
  slots @ times
    i 2 0 .pz "\b: " print
    figures i + @ 5 0 .pz cr
  again
;

: _run_sample_inner
  end @ start @ 1
  for
    mul @ i * base @ digit_sum
    wrap @ absmod shift @ + slots @ absmod
    figures + dup @ 1 + swap !
  next
;

: _draw_row
  dup
  0 >
  if
    dup
    times
      " " print
    again
  endif
  drawchars @ swap dup 1 + strslice print cr
;

: _draw_sample_inner
  end @ start @ 1
  for
    mul @ i * base @ digit_sum
      scale @
    * round
    wrap @ absmod
      shift @
    +
    slots @ absmod
    _draw_row
  next
;

: _draw_sample_infinite
  redis_midi.get_mul x @ * redis_midi.get_base digit_sum
  redis_midi.get_wrap absmod
    redis_midi.get_mode
  +
  14 absmod
  _draw_row
  redis_midi.get_on_gate sleep
  x dup @ 1 + swap !
  _draw_sample_infinite
;

: _get_non_zero_size
  slots @ 1 -
  -1 over -1
  for
    figures i + @
    0 <>
    if
      i min
    endif
  next
  slots @ swap -
;

: _get_lowest_figure
  slots @
    _get_non_zero_size
  -
    figures
  +
  @
;

: _get_highest_figure
  figures
    slots @ 1 -
  +
  @
;

################
# The main API #
################

: run_sample
  _clear_figures
  _run_sample_inner
  _show_figures
;

: draw_sample
  _clear_figures
  _draw_sample_inner
;

: draw_sample_infinite
  0 x !
  _clear_figures
  _draw_sample_infinite
;

: mul_study
  "mul num_nz_slots min_cnt max_cnt max_cnt/min_cnt" print cr
  study_end @ 1 1
  for
    i mul !
    _clear_figures
    _run_sample_inner
    figures slots @ sortnums
    i 3 0 .pz
    _get_non_zero_size 2 0 .pz
    _get_highest_figure _get_lowest_figure
    2dup
    4 0 .pz
    4 0 .pz
    / .  cr
  next
;

: wrap_study
  "wrap num_nz_slots min_cnt max_cnt max_cnt/min_cnt" print cr
  slots @ 1 +  5  1
  for
    i wrap !
    _clear_figures
    _run_sample_inner
    figures slots @ sortnums
    i 3 0 .pz
    _get_non_zero_size 2 0 .pz
    _get_highest_figure _get_lowest_figure
    2dup
    4 0 .pz
    4 0 .pz
    / .  cr
  next
;