From 6028cafaefe5699eb743de748501cb8b463ea7d0 Mon Sep 17 00:00:00 2001
From: Edward L Platt <ed@elplatt.com>
Date: Tue, 20 Aug 2019 15:32:39 -0400
Subject: [PATCH] Add comments to network module.

---
 network.rkt | 61 ++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 56 insertions(+), 5 deletions(-)

diff --git a/network.rkt b/network.rkt
index 1274caf..bb9960a 100644
--- a/network.rkt
+++ b/network.rkt
@@ -1,13 +1,64 @@
 ;; Copyright 2019 Edward L. Platt <elplatt@alum.mit.edu>
 ;;
-;; TODO: comments and tests
+;; This module implements a family of graphs based on permutations of
+;; sylvester-radix numbers.
 
 #lang racket
 
 (provide
+ 
+ ;; Generate the list of graph nodes.
+ ;;
+ ;; Params:
+ ;; m: Dimensionality of sylvester-radix numbers used as vertices.
+ ;; 
+ ;; Example:
+ ;; > (sylvester-nodes 2)
+ ;; '((0 0) (1 0) (0 1) (1 1) (0 2) (1 2))
  sylvester-nodes
+
+ ;; Generate the list of directed graph edges.
+ ;;
+ ;; Params:
+ ;; m: Dimensionality of sylvester-radix numbers used as vertices.
+ ;;
+ ;; Example:
+ ;; > (sylvester-edges 1)
+ ;; '(((0) (1)) ((1) (0)))
  sylvester-edges
- sylvester-undirected-edges)
+
+ ;; Generate the list of undirected graph edges.
+ ;;
+ ;; Params:
+ ;; m: Dimensionality of sylvester-radix numbers used as vertices.
+ ;;
+ ;; Example:
+ ;; > (sylvester-undirected-edges 1)
+ ;; '(((1) (0)))
+ sylvester-undirected-edges
+
+ ;; Create cyclic permutation operator for one digit of sylvester-radix number.
+ ;;
+ ;; Params:
+ ;; i: Index of digit to permute.
+ ;; n: Number of times to cycle digit.
+ ;;
+ ;; Example:
+ ;; > ((cycle-sylvester-radix 2 1) '(0 0 0 0))
+ ;; '(0 0 1 0)
+ cycle-sylvester-radix
+
+ ;; Create skip operator.
+ ;; The skip operator is a composition of single-digit cyclic permutations.
+ ;; Skip operators are used to generate the graph edges.
+ ;;
+ ;; Params:
+ ;; i: Results in an operator acting on the lowest i digits.
+ ;;
+ ;; Example:
+ ;; > ((skip-sylvester-radix 2) '(0 0 0))
+ ;; '(1 2 6)
+ skip-sylvester-radix)
 
 (require "sylvester.rkt")
 
@@ -33,7 +84,7 @@
 (define (sylvester-color-edge k)
   (lambda (v) (list v ((skip-sylvester-radix k) v))))
 
-(define (permutation-sylvester-radix i n)
+(define (cycle-sylvester-radix i n)
   (lambda (v)
     (let* ([v ((extend-sylvester-radix (+ i 1)) v)]
            [head (take v i)]
@@ -49,9 +100,9 @@
 (define (skip-sylvester-radix i)
   (lambda (v)
     (if (= i 0)
-        ((permutation-sylvester-radix 0 1) v)
+        ((cycle-sylvester-radix 0 1) v)
         (let* ([prev (skip-sylvester-radix (- i 1))]
                [partial (take v (min i (length v)))]
                [value (sylvester-radix-value (prev partial))])
-          ((compose (permutation-sylvester-radix i (+ 1 value)) prev) v)))))
+          ((compose (cycle-sylvester-radix i (+ 1 value)) prev) v)))))
           
\ No newline at end of file