added some internal documentation, plus created an examples directory…

… and shifted some code there

test/Data/dyadic_tree_3.dot → examples/Data/dyadic_tree_3.dot

@@ -10,44 +10,44 @@ node_day_1 [shape=none, pos="7.875,1!", label="Day 1", fontsize=18]
    node_1 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-1</TD></TR>
-         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0"> 0 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-2.25,1!"
          ];
    node_1:R -> node_0;
    node_2 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">1</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
          </TABLE>>,pos="2.25,1!"
          ];
    node_2:L -> node_0;
 node_day_2 [shape=none, pos="7.875,2!", label="Day 2", fontsize=18]
    node_3 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-2</TD></TR>
-         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1"> -1 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1,1"> -1 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-4.5,2!"
          ];
    node_3:R -> node_1;
    node_4 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">2</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1"> 1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1,1"> 1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
          </TABLE>>,pos="4.5,2!"
          ];
    node_4:L -> node_2;
    node_5 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">1/2</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1"> 1 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1,1"> 1 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="1.125,2!"
          ];
    node_5:L -> node_0;
    node_5:R -> node_2;
    node_6 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-1/2</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1"> -1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0"> 0 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1,1"> -1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-1.125,2!"
          ];
    node_6:L -> node_1;
@@ -56,61 +56,61 @@ node_day_3 [shape=none, pos="7.875,3!", label="Day 3", fontsize=18]
    node_7 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-3</TD></TR>
-         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-2"> -2 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-2,1"> -2 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-6.75,3!"
          ];
    node_7:R -> node_3;
    node_8 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">3</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="2"> 2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="2,1"> 2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
          </TABLE>>,pos="6.75,3!"
          ];
    node_8:L -> node_4;
    node_9 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">1/4</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1/2"> 1/2 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1/2,1"> 1/2 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="0.5625,3!"
          ];
    node_9:L -> node_0;
    node_9:R -> node_5;
    node_10 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-1/4</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1/2"> -1/2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0"> 0 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1/2,1"> -1/2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-0.5625,3!"
          ];
    node_10:L -> node_6;
    node_10:R -> node_0;
    node_11 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">3/4</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1/2"> 1/2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1"> 1 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1/2,1"> 1/2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1,1"> 1 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="1.6875,3!"
          ];
    node_11:L -> node_5;
    node_11:R -> node_2;
    node_12 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-3/4</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1"> -1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1/2"> -1/2 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1,1"> -1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1/2,1"> -1/2 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-1.6875,3!"
          ];
    node_12:L -> node_1;
    node_12:R -> node_6;
    node_13 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">3/2</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1"> 1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="2"> 2 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="1,1"> 1 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="2,1"> 2 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="3.375,3!"
          ];
    node_13:L -> node_2;
    node_13:R -> node_4;
    node_14 [shape=none,margin=0,label=
          <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
          <TR><TD COLSPAN="2">-3/2</TD></TR>
-         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-2"> -2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1"> -1 </TD> &nbsp; </TR></TABLE> </TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-2,1"> -2 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="-1,1"> -1 </TD> &nbsp; </TR></TABLE> </TD></TR>
          </TABLE>>,pos="-3.375,3!"
          ];
    node_14:L -> node_3;

test/dyadic_tree.jl → examples/dyadic_tree.jl

@@ -3,7 +3,7 @@ using SurrealNumbers
 # var_args = "color=red"
 var_args = ""
 n=3; x_scale = 2.25
-n=4; x_scale = 5.00
+# n=4; x_scale = 5.00
 out_dir = "Data/"
 
 name_map = Dict{SurrealFinite, Integer}()

test/examples.jl → examples/examples.jl

@@ -27,7 +27,7 @@ generation.(A)
 A .== canonicalise.(A)
 
 
-n = 3
+n = 1
 x = convert.(SurrealFinite, 0:n)
 A = zeros(SurrealFinite, n+1, n+1)    
 for i=1:n+1

src/SurrealFinite.jl

@@ -311,7 +311,29 @@ end
 pf(io::IO, x::SurrealFinite) = println(io, "{ ", x.L, " | ", x.R, " }")
 pf(x::SurrealFinite) = pf(STDOUT, x) 
 
-# expand at some level, 0 steps (if possible), 1 step, or completely
+"""
+    expand(x::SurrealFinite; level=0) 
+
+ Writes a surreal as a string with varying levels of expansion.
+
+## Arguments
+* `x::SurrealFinite`: the number of elements to expand
+* `level=0`: the amount of expansion
+    
+    + 0 : write shorthand if it exists, or ``\\{ X_L \\| X_R \\}`` if not
+    + 1 : ``\\{ X_L \\| X_R \\}``
+    + 2 : expand out ``X_L`` and ``X_R`` recursively
+
+## Examples
+```jldoctest
+julia> expand( convert(SurrealFinite, 2))
+"2"
+julia> expand( convert(SurrealFinite, 2); level=1)
+"{ 1 | ϕ }"
+julia> expand( convert(SurrealFinite, 2); level=2)
+"{ { { ϕ | ϕ } | ϕ } | ϕ }"
+```
+"""
 function expand(x::SurrealFinite; level=0)
     if level==0
         s = x.shorthand != "" ? x.shorthand : expand(x; level=1)
@@ -396,6 +418,31 @@ end
 # special "canonicalised" output
 spf(x::SurrealFinite) = print("{ ", canonicalise.(x.L), " | ", canonicalise.(x.R), " }")
 
+""" 
+    surreal2dag(x::SurrealFinite)
+    surreal2dag(io::IO, x::SurrealFinite)
+
+ Writes a surreal representation as a DAG out in DOT format for drawing using GraphVis,
+ and returns the number of nodes in the graph.
+
+## Arguments
+* `io::IO`: output stream, default is STDOUT
+* `x::SurrealFinite`: the number to write out
+    
+## Examples
+```jldoctest
+julia> surreal2dag(convert(SurrealFinite, 0))
+digraph "0.0" {
+   node_1 [shape=none,margin=0,label=
+         <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
+         <TR><TD COLSPAN="2">0</TD></TR>
+         <TR><TD PORT="L"> ϕ </TD><TD PORT="R"> ϕ </TD></TR>
+         </TABLE>>,
+         ];
+}
+1
+```
+"""
 function surreal2dag(io::IO, x::SurrealFinite)
     println(io, "digraph \"", float(x), "\" {")
     k = 1
@@ -442,6 +489,33 @@ end
 surreal2dag(x::SurrealFinite) = surreal2dag(STDOUT, x)
 
 
+""" 
+    surreal2dot(x::SurrealFinite)
+    surreal2dot(io::IO, x::SurrealFinite)
+
+ Writes a surreal representation as a tree out in DOT format for drawing using GraphVis,
+ and returns the number of nodes in the graph.
+
+## Arguments
+* `io::IO`: output stream, default is STDOUT
+* `x::SurrealFinite`: the number to write out
+    
+## Examples
+```jldoctest
+julia> surreal2dot(convert(SurrealFinite, 1))
+digraph "1.0" {
+   node_1 [shape=none,margin=0,label=
+         <<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0" CELLPADDING="4">
+         <TR><TD COLSPAN="2">1</TD></TR>
+         <TR><TD PORT="L"> <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0"><TR><TD PORT="0,1"> 0 </TD> &nbsp; </TR></TABLE> </TD><TD PORT="R"> ϕ </TD></TR>
+         </TABLE>>,
+         ];
+   node_1:"0,1" -> node_2;
+   node_2 [shape=none,margin=0,label=<<B>0</B>>]
+}
+2
+```
+"""
 function surreal2dot(io::IO, x::SurrealFinite)
     println(io, "digraph \"", float(x), "\" {")
     k = 1
@@ -525,7 +599,20 @@ surreal2dot(x::SurrealFinite) = surreal2dot(STDOUT, x)
 
 #######################################################
 
-# generation or birth day calculation
+""" 
+    generation(x::SurrealFinite)
+
+ Finds the birthday of a surreal number, which is 1 + the max of any of its components.
+
+## Arguments
+* `x::SurrealFinite`: the number to operate on
+     
+## Examples
+```jldoctest
+julia> generation( convert(SurrealFinite, 1) )
+1
+``` 
+"""
 function generation(x::SurrealFinite)
     if x==zero(x)
         return 0
@@ -536,6 +623,22 @@ function generation(x::SurrealFinite)
 end 
 
 # this is a bit of a cheat, but I'm not smart enough to work out how to do it otherwise
+""" 
+    canonicalise(s::SurrealFinite)
+
+ Convert a surreal number form into its equivalent canonical form.
+
+## Arguments
+* `x::SurrealFinite`: the number to operate on
+     
+## Examples
+```jldoctest
+julia> convert(SurrealFinite, 1) - convert(SurrealFinite, 1)
+{ { ϕ | { ϕ | ϕ } } | { { ϕ | ϕ } | ϕ } }
+julia> pf( canonicalise( convert(SurrealFinite, 1) - convert(SurrealFinite, 1) ) )
+{ ϕ | ϕ }
+``` 
+"""
 canonicalise(s::SurrealFinite) = convert(SurrealFinite, convert(Rational, s))
 iscanonical(s::SurrealFinite) = canonicalise(s) == s
 
@@ -553,7 +656,6 @@ end
 
 ###### standard math routines ##############################
 
-
 sign(x::SurrealFinite) = x<zero(x) ? -one(x) : x>zero(x) ? one(x) : zero(x)
 # abs(x::SurrealFinite) = x<zero(x) ? -x : x
 

src/SurrealNumbers.jl

@@ -9,7 +9,7 @@ export Surreal, SurrealFinite, Dyadic
 export ExistingSurreals
 export <=, zero, one, ==, ≅, ≇, <, -, +, *, ϕ, ≀, ↑, ↓, 
     convert, promote, hash,
-    pf, pff, spf, show, surreal2dot, surreal2dag, surreal2node, surreal2tex, read, expand,
+    pf, pff, spf, show, surreal2dot, surreal2dag, surreal2tex, read, expand,
     generation, canonicalise, iscanonical,
     unique2!, size, size_u, n_zeros, depth_max, depth_av, list_n, count_n, depth, 
     sign, round, floor, ceil, trunc, mod, 

src/todo.txt

@@ -1,4 +1,7 @@
 
+create an examples directory instead of putting all code in the test, plus a doc directory
+   tidy up and add the "old" code to the timing files, so that it isn't in the main source
+
 make round(0.5) match julias behaviour, or better yet implement the different rounding types
        and then precision, which is a whole nother issue
 
@@ -30,21 +33,24 @@ functions
 	gcd
 	lcm
 
-	abs2 -- free
-
 	math functions -- this is hard without cheating by converting to real, and finding canonical equivalent
 	     log
 	     exp
 	     powers
 	     trig
-
+         require infinite series, so not valid for finite surreals 
+
 add some automatically generated random tests
 
 "Practically Surreal"
 
 "The Graphical Structure of the Surreal Numbers Examined Through the
  Lens on an Implementation in Julia"
 
+(1) one paper on CodeX, with general stuff on code and algorithms
+(2) one recreational maths paper on the structure and nature of surreal arithmetic
+
+