[Axiom-developer] 20080817.03.tpd.patch (exported function documentation)

[daly]

The following exposed functions now have )display op documentation:

CartesianTensor: ravel, leviCivitaSymbol, *, kroneckerDelta, reindex,
                 transpose, contract, product, elt, rank, coerce
CardinalNumber: -, **, generalizedContinuumHypothesisAssumed,
                generalizedContinuumHypothesisAssumed?, countable?
                finite, Aleph
BinaryExpansion: binary
InputForm: binary
ExtensibleLinearAggregate: delete!
TableAggregate: table

=======================================================================
diff --git a/changelog b/changelog
index ea20f30..f2bd54b 100644
--- a/changelog
+++ b/changelog
@@ -1,3 +1,25 @@
+20080817 tpd src/algebra/vector.spad doc ravel from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc leviCivitaSymbol from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc * from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc kroneckerDelta from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc reindex from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc transpose from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc contract from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc product from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc elt from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc rank from CartesianTensor
+20080817 tpd src/algebra/vector.spad doc coerce from CartesianTensor
+20080817 tpd src/algebra/card.spad doc - from CardinalNumber
+20080817 tpd src/algebra/card.spad doc ** from CardinalNumber
+20080817 tpd src/algebra/card.spad doc generalizedContinuumHypothesisAssumed
+20080817 tpd src/algebra/card.spad doc generalizedContinuumHypothesisAssumed?
+20080817 tpd src/algebra/card.spad doc countable? from CardinalNumber
+20080817 tpd src/algebra/card.spad doc finite? from CardinalNumber
+20080817 tpd src/algebra/card.spad doc Aleph from CardinalNumber
+20080817 tpd src/algebra/radix.spad doc binary from BinaryExpansion
+20080817 tpd src/algebra/mkfunc.spad doc binary from InputForm
+20080817 tpd src/algebra/aggcat.spad doc delete! ExtensibleLinearAggregate
+20080817 tpd src/algebra/aggcat.spad doc table from TableAggregate
 20080817 tpd src/input/Makefile add function.regress
 20080817 tpd src/input/function.input fix problems with input file
 20080817 tpd books/bookvol7.1 fix uncompress
diff --git a/src/algebra/aggcat.spad.pamphlet b/src/algebra/aggcat.spad.pamphlet
index ae221f4..0719be4 100644
--- a/src/algebra/aggcat.spad.pamphlet
+++ b/src/algebra/aggcat.spad.pamphlet
@@ -1218,6 +1218,11 @@ TableAggregate(Key:SetCategory, Entry:SetCategory): 
Category ==
      ++ to \axiom{(insert([k,e],t); e)}.
    table: () -> %
      ++ table()$T creates an empty table of type T.
+     ++
+     ++E Data:=Record(age:Integer,gender:String)
+     ++E a1:AssociationList(String,Data):=table()
+     ++E a1."tim":=[55,"male"]$Data
+
    table: List Record(key:Key,entry:Entry) -> %
      ++ table([x,y,...,z]) creates a table consisting of entries
      ++ \axiom{x,y,...,z}.
@@ -2604,6 +2609,12 @@ ExtensibleLinearAggregate(S:Type):Category == 
LinearAggregate S with
      ++ v is unchanged
    delete_!: (%,Integer) -> %
      ++ delete!(u,i) destructively deletes the \axiom{i}th element of u.
+     ++
+     ++E Data:=Record(age:Integer,gender:String)
+     ++E a1:AssociationList(String,Data):=table()
+     ++E a1."tim":=[55,"male"]$Data
+     ++E delete!(a1,1)
+
    delete_!: (%,UniversalSegment(Integer)) -> %
      ++ delete!(u,i..j) destructively deletes elements u.i through u.j.
    remove_!: (S->Boolean,%) -> %
diff --git a/src/algebra/card.spad.pamphlet b/src/algebra/card.spad.pamphlet
index 4d02a4d..14c1ae9 100644
--- a/src/algebra/card.spad.pamphlet
+++ b/src/algebra/card.spad.pamphlet
@@ -376,33 +376,67 @@ CardinalNumber: Join(OrderedSet, AbelianMonoid, Monoid,
         commutative "*"
             ++ a domain D has \spad{commutative("*")} if it has an operation
             ++ \spad{"*": (D,D) -> D} which is commutative.
+
         "-": (%,%) -> Union(%,"failed")
-           ++ \spad{x - y} returns an element z such that \spad{z+y=x} or 
"failed" 
-           ++ if no such element exists.
+            ++ \spad{x - y} returns an element z such that 
+            ++ \spad{z+y=x} or "failed" if no such element exists.
+            ++
+            ++E c2:=2::CardinalNumber
+            ++E c2-c2
+            ++E A1:=Aleph 1
+            ++E A1-c2
+
         "**": (%, %) -> %
             ++ \spad{x**y} returns \spad{#(X**Y)} where \spad{X**Y} is defined
             ++  as \spad{\{g| g:Y->X\}}.
+            ++
+            ++E c2:=2::CardinalNumber
+            ++E c2**c2
+            ++E A1:=Aleph 1
+            ++E A1**c2
+            ++E generalizedContinuumHypothesisAssumed true
+            ++E A1**A1
 
         Aleph: NonNegativeInteger -> %
             ++ Aleph(n) provides the named (infinite) cardinal number.
+            ++
+            ++E A0:=Aleph 0
 
         finite?: % -> Boolean
             ++ finite?(\spad{a}) determines whether 
-            ++ \spad{a} is a finite cardinal,
-            ++ i.e. an integer.
+            ++ \spad{a} is a finite cardinal, i.e. an integer.
+            ++
+            ++E c2:=2::CardinalNumber
+            ++E finite? c2
+            ++E A0:=Aleph 0
+            ++E finite? A0
 
         countable?: % -> Boolean
             ++ countable?(\spad{a}) determines 
             ++ whether \spad{a} is a countable cardinal,
             ++ i.e. an integer or \spad{Aleph 0}.
+            ++
+            ++E c2:=2::CardinalNumber
+            ++E countable? c2
+            ++E A0:=Aleph 0
+            ++E countable? A0
+            ++E A1:=Aleph 1
+            ++E countable? A1
 
         generalizedContinuumHypothesisAssumed?: () -> Boolean
             ++ generalizedContinuumHypothesisAssumed?()
             ++ tests if the hypothesis is currently assumed.
+            ++
+            ++E generalizedContinuumHypothesisAssumed?
 
         generalizedContinuumHypothesisAssumed:  Boolean -> Boolean
             ++ generalizedContinuumHypothesisAssumed(bool)
             ++ is used to dictate whether the hypothesis is to be assumed.
+            ++
+            ++E generalizedContinuumHypothesisAssumed true
+            ++E a:=Aleph 0
+            ++E c:=2**a
+            ++E f:=2**c
     == add
         NNI ==> NonNegativeInteger
         FINord   ==> -1
diff --git a/src/algebra/carten.spad.pamphlet b/src/algebra/carten.spad.pamphlet
index 5dfedb0..8d39805 100644
--- a/src/algebra/carten.spad.pamphlet
+++ b/src/algebra/carten.spad.pamphlet
@@ -1082,42 +1082,108 @@ CartesianTensor(minix, dim, R): Exports == 
Implementation where
 
         coerce: DP(dim, R) -> %
             ++ coerce(v) views a vector as a rank 1 tensor.
+            ++
+            ++E v:DirectProduct(2,Integer):=directProduct [3,4]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+
         coerce: SM(dim, R)  -> %
             ++ coerce(m) views a matrix as a rank 2 tensor.
+            ++
+            ++E v:SquareMatrix(2,Integer):=[[1,2],[3,4]]
+            ++E tv:CartesianTensor(1,2,Integer):=v
 
         coerce: List R -> %
             ++ coerce([r_1,...,r_dim]) allows tensors to be constructed
             ++ using lists.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
 
         coerce: List % -> %
             ++ coerce([t_1,...,t_dim]) allows tensors to be constructed
             ++ using lists.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+            ++E tm:CartesianTensor(1,2,Integer):=[tv,tv]
 
         rank: % -> NNI
             ++ rank(t) returns the tensorial rank of t (that is, the
             ++ number of indices).  This is the same as the graded module
             ++ degree.
+            ++
+            ++E CT:=CARTEN(1,2,Integer)
+            ++E t0:CT:=8
+            ++E rank t0
 
         elt: (%) -> R
             ++ elt(t) gives the component of a rank 0 tensor.
+            ++
+            ++E tv:CartesianTensor(1,2,Integer):=8
+            ++E elt(tv)
+            ++E tv[]
+
         elt: (%, I) -> R
             ++ elt(t,i) gives a component of a rank 1 tensor.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+            ++E elt(tv,2)
+            ++E tv[2]
+
         elt: (%, I, I) -> R
             ++ elt(t,i,j) gives a component of a rank 2 tensor.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+            ++E tm:CartesianTensor(1,2,Integer):=[tv,tv]
+            ++E elt(tm,2,2)
+            ++E tm[2,2]
+
         elt: (%, I, I, I) -> R
             ++ elt(t,i,j,k) gives a component of a rank 3 tensor.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+            ++E tm:CartesianTensor(1,2,Integer):=[tv,tv]
+            ++E tn:CartesianTensor(1,2,Integer):=[tm,tm]
+            ++E elt(tn,2,2,2)
+            ++E tn[2,2,2]
+
         elt: (%, I, I, I, I) -> R
             ++ elt(t,i,j,k,l) gives a component of a rank 4 tensor.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+            ++E tm:CartesianTensor(1,2,Integer):=[tv,tv]
+            ++E tn:CartesianTensor(1,2,Integer):=[tm,tm]
+            ++E tp:CartesianTensor(1,2,Integer):=[tn,tn]
+            ++E elt(tp,2,2,2,2)
+            ++E tp[2,2,2,2]
 
         elt: (%, List I) -> R
             ++ elt(t,[i1,...,iN]) gives a component of a rank \spad{N} tensor.
+            ++
+            ++E v:=[2,3]
+            ++E tv:CartesianTensor(1,2,Integer):=v
+            ++E tm:CartesianTensor(1,2,Integer):=[tv,tv]
+            ++E tn:CartesianTensor(1,2,Integer):=[tm,tm]
+            ++E tp:CartesianTensor(1,2,Integer):=[tn,tn]
+            ++E tq:CartesianTensor(1,2,Integer):=[tp,tp]
+            ++E elt(tq,[2,2,2,2,2])
 
         -- This specializes the documentation from GradedAlgebra.
         product: (%,%) -> %
             ++ product(s,t) is the outer product of the tensors s and t.
-            ++ For example, if \spad{r = product(s,t)} for rank 2 tensors s 
and t,
-            ++ then \spad{r} is a rank 4 tensor given by
+            ++ For example, if \spad{r = product(s,t)} for rank 2 tensors 
+            ++ s and t, then \spad{r} is a rank 4 tensor given by
             ++     \spad{r(i,j,k,l) = s(i,j)*t(k,l)}.
+            ++
+            ++E m:SquareMatrix(2,Integer):=matrix [[1,2],[4,5]]
+            ++E Tm:CartesianTensor(1,2,Integer):=m
+            ++E n:SquareMatrix(2,Integer):=matrix [[2,3],[0,1]]
+            ++E Tn:CartesianTensor(1,2,Integer):=n
+            ++E Tmn:=product(Tm,Tn)
 
         "*": (%, %) -> %
             ++ s*t is the inner product of the tensors s and t which contracts
@@ -1126,6 +1192,12 @@ CartesianTensor(minix, dim, R): Exports == 
Implementation where
             ++     \spad{t*s = sum(k=1..N, t[i1,..,iN,k]*s[k,j1,..,jM])}
             ++ This is compatible with the use of \spad{M*v} to denote
             ++ the matrix-vector inner product.
+            ++
+            ++E m:SquareMatrix(2,Integer):=matrix [[1,2],[4,5]]
+            ++E Tm:CartesianTensor(1,2,Integer):=m
+            ++E v:DirectProduct(2,Integer):=directProduct [3,4]
+            ++E Tv:CartesianTensor(1,2,Integer):=v
+            ++E Tm*Tv
 
         contract:  (%, Integer, %, Integer) -> %
             ++ contract(t,i,s,j) is the inner product of tenors s and t
@@ -1135,6 +1207,12 @@ CartesianTensor(minix, dim, R): Exports == 
Implementation where
             ++ rank 3 tensors \spad{s} and \spad{t}, then \spad{r} is
             ++ the rank 4 \spad{(= 3 + 3 - 2)} tensor  given by
             ++     \spad{r(i,j,k,l) = sum(h=1..dim,s(i,h,j)*t(h,k,l))}.
+            ++
+            ++E m:SquareMatrix(2,Integer):=matrix [[1,2],[4,5]]
+            ++E Tm:CartesianTensor(1,2,Integer):=m
+            ++E v:DirectProduct(2,Integer):=directProduct [3,4]
+            ++E Tv:CartesianTensor(1,2,Integer):=v
+            ++E Tmv:=contract(Tm,2,Tv,1)
 
         contract:  (%, Integer, Integer)    -> %
             ++ contract(t,i,j) is the contraction of tensor t which
@@ -1143,18 +1221,34 @@ CartesianTensor(minix, dim, R): Exports == 
Implementation where
             ++ \spad{r = contract(t,1,3)} for a rank 4 tensor t, then
             ++ \spad{r} is the rank 2 \spad{(= 4 - 2)} tensor given by
             ++     \spad{r(i,j) = sum(h=1..dim,t(h,i,h,j))}.
+            ++
+            ++E m:SquareMatrix(2,Integer):=matrix [[1,2],[4,5]]
+            ++E Tm:CartesianTensor(1,2,Integer):=m
+            ++E v:DirectProduct(2,Integer):=directProduct [3,4]
+            ++E Tv:CartesianTensor(1,2,Integer):=v
+            ++E Tmv:=contract(Tm,2,1)
 
         transpose: % -> %
             ++ transpose(t) exchanges the first and last indices of t.
-            ++ For example, if \spad{r = transpose(t)} for a rank 4 tensor t, 
then
-            ++ \spad{r} is the rank 4 tensor given by
+            ++ For example, if \spad{r = transpose(t)} for a rank 4 
+            ++ tensor t, then \spad{r} is the rank 4 tensor given by
             ++     \spad{r(i,j,k,l) = t(l,j,k,i)}.
+            ++
+            ++E m:SquareMatrix(2,Integer):=matrix [[1,2],[4,5]]
+            ++E Tm:CartesianTensor(1,2,Integer):=m
+            ++E transpose(Tm)
 
         transpose: (%, Integer, Integer) -> %
-            ++ transpose(t,i,j) exchanges the \spad{i}-th and \spad{j}-th 
indices of t.
-            ++ For example, if \spad{r = transpose(t,2,3)} for a rank 4 tensor 
t, then
-            ++ \spad{r} is the rank 4 tensor given by
+            ++ transpose(t,i,j) exchanges the \spad{i}-th and \spad{j}-th 
+            ++ indices of t. For example, if \spad{r = transpose(t,2,3)} 
+            ++ for a rank 4 tensor t, then \spad{r} is the rank 4 tensor 
+            ++ given by
             ++     \spad{r(i,j,k,l) = t(i,k,j,l)}.
+            ++
+            ++E m:SquareMatrix(2,Integer):=matrix [[1,2],[4,5]]
+            ++E tm:CartesianTensor(1,2,Integer):=m
+            ++E tn:CartesianTensor(1,2,Integer):=[tm,tm]
+            ++E transpose(tn,1,2)
 
         reindex: (%, List Integer) -> %
             ++ reindex(t,[i1,...,idim]) permutes the indices of t.
@@ -1162,21 +1256,35 @@ CartesianTensor(minix, dim, R): Exports == 
Implementation where
             ++ for a rank 4 tensor t,
             ++ then \spad{r} is the rank for tensor given by
             ++     \spad{r(i,j,k,l) = t(l,i,j,k)}.
-
+            ++ 
+            ++E n:SquareMatrix(2,Integer):=matrix [[2,3],[0,1]]
+            ++E tn:CartesianTensor(1,2,Integer):=n
+            ++E p:=product(tn,tn)
+            ++E reindex(p,[4,3,2,1])
+ 
         kroneckerDelta:  () -> %
             ++ kroneckerDelta() is the rank 2 tensor defined by
             ++    \spad{kroneckerDelta()(i,j)}
             ++       \spad{= 1  if i = j}
             ++       \spad{= 0 if  i \^= j}
+            ++ 
+            ++E delta:CartesianTensor(1,2,Integer):=kroneckerDelta()
 
         leviCivitaSymbol: () -> %
             ++ leviCivitaSymbol() is the rank \spad{dim} tensor defined by
             ++ \spad{leviCivitaSymbol()(i1,...idim) = +1/0/-1}
             ++ if \spad{i1,...,idim} is an even/is nota /is an odd permutation
             ++ of \spad{minix,...,minix+dim-1}.
+            ++ 
+            ++E lcs:CartesianTensor(1,2,Integer):=leviCivitaSymbol()
+
         ravel:     % -> List R
             ++ ravel(t) produces a list of components from a tensor such that
             ++   \spad{unravel(ravel(t)) = t}.
+            ++ 
+            ++E n:SquareMatrix(2,Integer):=matrix [[2,3],[0,1]]
+            ++E tn:CartesianTensor(1,2,Integer):=n
+            ++E ravel tn
 
         unravel:   List R -> %
             ++ unravel(t) produces a tensor from a list of
diff --git a/src/algebra/mkfunc.spad.pamphlet b/src/algebra/mkfunc.spad.pamphlet
index e6db6f4..840aa2e 100644
--- a/src/algebra/mkfunc.spad.pamphlet
+++ b/src/algebra/mkfunc.spad.pamphlet
@@ -33,6 +33,10 @@ InputForm():
     binary   : (%, List %) -> %
       ++ \spad{binary(op, [a1,...,an])} returns the input form
       ++ corresponding to  \spad{a1 op a2 op ... op an}.
+      ++
+      ++E a:=[1,2,3]::List(InputForm)
+      ++E binary(_+::InputForm,a)
+
     function : (%, List Symbol, Symbol) -> %
       ++ \spad{function(code, [x1,...,xn], f)} returns the input form
       ++ corresponding to \spad{f(x1,...,xn) == code}.
diff --git a/src/algebra/radix.spad.pamphlet b/src/algebra/radix.spad.pamphlet
index 1e76d86..28185f1 100644
--- a/src/algebra/radix.spad.pamphlet
+++ b/src/algebra/radix.spad.pamphlet
@@ -344,7 +344,7 @@ RadixExpansion(bb): Exports == Implementation where
     fractRadix: (List Integer, List Integer) -> %
       ++ fractRadix(pre,cyc) creates a fractional radix expansion
       ++ from a list of prefix ragits and a list of cyclic ragits.
-      ++ For example, \spad{fractRadix([1],[6])} will return 
\spad{0.16666666...}.
+      ++ e.g., \spad{fractRadix([1],[6])} will return \spad{0.16666666...}.
 
   Implementation ==> add
     -- The efficiency of arithmetic operations is poor.
@@ -723,6 +723,8 @@ BinaryExpansion(): Exports == Implementation where
       ++ fractionPart(b) returns the fractional part of a binary expansion.
     binary: Fraction Integer -> %
       ++ binary(r) converts a rational number to a binary expansion.
+      ++
+      ++E binary(22/7)
 
   Implementation ==> RadixExpansion(2) add
     binary r == r :: %