Merge pull request #2433 from DanGrayson/core-documentation

Core documentation

M2/Macaulay2/d/actors2.dd

@@ -64,7 +64,7 @@ toList(e:Expr):Expr := (
 	       	    false)))
      is s:stringCell do list(strtoseq(s))
      else WrongArg("list, sequence, set, or string"));
-setupfun("toList",toList);
+setupfun("toList1",toList);
 values(e:Expr):Expr := (
      when e
      is oc:DictionaryClosure do (

M2/Macaulay2/m2/basictests/A01.m2

@@ -33,13 +33,13 @@ assert( bb#1 === 44 )
 assert( aa#1 === 2 )
 
 -- test list
-assert( toList (1,2,3) === {1,2,3} )
-assert( toList () === {} )
-assert( toList {} === {} )
-assert( toList {1} === {1} )
-assert( toList {1,2} === {1,2} )
+assert( toList1 (1,2,3) === {1,2,3} )
+assert( toList1 () === {} )
+assert( toList1 {} === {} )
+assert( toList1 {1} === {1} )
+assert( toList1 {1,2} === {1,2} )
 aa = newClass(MutableList, {1,2,3})
-bb = toList aa
+bb = toList1 aa
 aa#2 = 444
 assert( not  mutable bb )
 assert( aa#2 === 444 )

M2/Macaulay2/m2/basictests/D01.m2

@@ -3,7 +3,7 @@ assert = x -> if not x then error "assertion failed "
 -- an error here would mean a symbol got stored in the wrong bucket
 scan(dictionaryPath, d -> scan(pairs d, (nam,sym) -> assert ( d#nam === sym ) ) )
 -- try to defeat any caching of hash code
-scan(dictionaryPath, d -> scan(pairs d, (nam,sym) -> assert ( d#(concatenate toList nam) === sym ) ) )
+scan(dictionaryPath, d -> scan(pairs d, (nam,sym) -> assert ( d#(concatenate toList1 nam) === sym ) ) )
 
 -- Local Variables:
 -- compile-command: "make -C $M2BUILDDIR/Macaulay2/basictests D01.okay"

M2/Macaulay2/m2/methods.m2

@@ -419,6 +419,11 @@ depth String := s -> 0
 
 -----------------------------------------------------------------------------
 
+toList = method(Dispatch => Thing)
+toList BasicList := toList Set := toList String := List => toList1
+
+-----------------------------------------------------------------------------
+
 oldflatten := flatten
 erase symbol flatten
 flatten = method(Dispatch => Thing)

M2/Macaulay2/m2/nets.m2

@@ -279,7 +279,7 @@ netList VisibleList := o -> (x) -> (
 	  ))
 
 characters = method()
-characters String := toList
+characters String := toList1
 
 -- TODO: move to debugging, except for Net?
 commentize = method(Dispatch => Thing)

M2/Macaulay2/m2/typicalvalues.m2

@@ -107,7 +107,6 @@ substring(String,ZZ,ZZ) := String => substring
 substring(ZZ,String) := String => substring
 substring(Sequence,String) := String => substring
 substring(ZZ,ZZ,String) := String => substring
-toList Set := toList BasicList := toList String := List => toList
 toSequence BasicList := toSequence String := Sequence => toSequence
 ascii String := List => ascii
 ascii List := String => ascii

M2/Macaulay2/packages/Dmodules/DMODdoc.m2

@@ -1888,6 +1888,25 @@ isInMultiplierIdeal(x_1*x_2, ideal {x_1^3 - x_2^2, x_2^3 - x_3^2}, 31/18)
      SeeAlso => { "multiplierIdeal", "jumpingCoefficients", "generalB" }
      }
 
+document {
+     Key => { toricIdealPartials, (toricIdealPartials, Matrix, PolynomialRing) },
+     Headline => "image of a monomial map",
+     Usage => "toricIdealPartials(A,D)",
+     Inputs => {
+	  "A" => Matrix => { "a matrix over ZZ whose columns give the coefficients of a monomial map" },
+	  "D" => PolynomialRing => { "the corresponding Weyl algebra" }
+	  },
+     Outputs => {
+	  Ideal => { "the toric ideal of the image the monomial map described by ", TT "A", " formed in the
+	       polynomial ring generated by the differential variables of ", TT "D", "." } 
+	  },
+     EXAMPLE lines ///
+	  A = matrix{{1,1,1},{0,1,2}}
+	  D = makeWA(QQ[x_1..x_3])
+	  toricIdealPartials(A,D)
+     ///
+     }
+
 
 end
 ------------------------------------------------------------------------------------------------------------

M2/Macaulay2/packages/Graphs.m2

@@ -24,15 +24,15 @@ of the License, or any later version.
 ------------------------------------------
 ------------------------------------------
 
-newPackage select((
+newPackage (
     "Graphs",
         Version => "0.3.4",
         Date => "May 15, 2021",
         Authors => {
             {Name => "Jack Burkart", Email => "[email protected]"},
-            {Name => "David Cook II", Email => "[email protected]", HomePage => "http://ux1.eiu.edu/~dwcook/"},
-            {Name => "Caroline Jansen", Email => "[email protected]"},
-            	{Name => "Amelia Taylor", Email => "[email protected]"},
+            {Name => "David Cook II", Email => "[email protected]", HomePage => "http://ux1.eiu.edu/~dwcook/"},
+            {Name => "Caroline Jansen", Email => "cjansen@alumni.nd.edu"},
+            {Name => "Amelia Taylor", Email => "[email protected]"},
             {Name => "Augustine O'Keefe", Email => "[email protected]"},
             {Name => "Contributors of note: Carlos Amendola, Alex Diaz, Luis David Garcia Puente, Roser Homs Pons, Olga Kuznetsova,  Shaowei Lin, Sonja Mapes, Harshit J Motwani, Mike Stillman, Doug Torrance"}
         },
@@ -45,8 +45,8 @@ newPackage select((
         PackageExports => {
             "SimplicialComplexes"
             },
-        DebuggingMode => false,
-        ), x -> x =!= null)
+        DebuggingMode => false
+        )
 
 -- Load configurations
 graphs'DotBinary = if instance((options Graphs).Configuration#"DotBinary", String) then (options Graphs).Configuration#"DotBinary" else "dot";
@@ -1826,6 +1826,7 @@ doc ///
         (graph, Matrix)
         [graph, Singletons]
         [graph, EntryMode]
+	EntryMode
     Headline
         Constructs a simple graph
     Usage
@@ -1874,7 +1875,7 @@ doc ///
             The hash table with a graph's vertices as keys and list of neighbors as values.
     Description
         Text
-            A graph consists of two sets, a vertex set and an edge set which is a subset of the collection of subsets of the vertex set. Edges in graphs are symmetric or two-way; if u and v are vertices then if {u,v} is an edge connecting them, {v,u} is also an edge (which is implicit in the definition, we will almost always just use one of the pairs). The options for EntryMode are "neighbors" (the default) and "edges."  This method returns a hash table where the keys are vertices of a given graph or digraph and the values are their children (or neighbors, in the case of undirected graphs).
+            A graph consists of two sets, a vertex set and an edge set which is a subset of the collection of subsets of the vertex set. Edges in graphs are symmetric or two-way; if u and v are vertices then if {u,v} is an edge connecting them, {v,u} is also an edge (which is implicit in the definition, we will almost always just use one of the pairs). The options for EntryMode are "neighbors" (the default) and "edges".  This method returns a hash table where the keys are vertices of a given graph or digraph and the values are their children (or neighbors, in the case of undirected graphs).
         Example
             G = graph digraph({{1,2},{2,1},{3,1}}, EntryMode => "edges")
             G = graph digraph(matrix {{0,1,1},{1,0,0},{1,0,0}})
@@ -3677,8 +3678,9 @@ doc ///
     Key
         forefathers
         (forefathers,Digraph,Thing)
+	symbol foreFathers
     Headline
-        returns the forefathers of a digrah
+        returns the forefathers of a digraph
     Usage
         L = forefathers (D, v)
     Inputs
@@ -4780,6 +4782,7 @@ doc ///
     Key
         directProduct
         (directProduct, Graph, Graph)
+	symbol tensorProduct
     Headline
         Computes the direct product of two graphs
     Usage
@@ -5366,9 +5369,33 @@ doc ///
    ///
 
 
-
-
-
+doc ///
+    Key
+        clusteringCoefficient
+        (clusteringCoefficient, Graph)  
+        (clusteringCoefficient, Graph, Thing)
+    Headline
+        a method for computing the clustering coefficient of a Graph
+    Usage
+        c = clusteringCoefficient(G, v)
+        g = clusteringCoefficient(G)
+    Inputs
+        G:Graph
+        v:Thing
+            v should be a member of the vertex set of G
+    Outputs
+        c:ZZ
+            The local clustering coefficient for G relative to v.
+        g:ZZ
+            The global clustering coefficient for G.
+    Description
+        Text
+            The clustering coefficient is a measure of the degree to which nodes in a graph tend to cluster together. The global clustering coefficient gives an overall
+            indication of the interconnectedness of the graph. The local clustering coefficient gives an indication of how embedded a single vertex is in the graph.
+        Example
+            clusteringCoefficient cycleGraph 4
+            clusteringCoefficient completeGraph 4
+///
 
 
 TEST ///

M2/Macaulay2/packages/Macaulay2Doc/doc12.m2

@@ -373,7 +373,7 @@ document {
      }
 
 document {
-     Key => MatrixExpression,
+     Key => {MatrixExpression, CompactMatrix, BlockMatrix},
      Headline => "the class of all matrix expressions",
      TT "MatrixExpression", " is a type of ", TO "Expression", " representing
      a matrix.",
@@ -384,6 +384,24 @@ document {
          ///MatrixExpression {applyTable({{x^2-y^2,x^3-y^3},{x^2-4*y^2,x^3+y^3}},factor),Degrees=>{{{-2},{-3}},{{0},{0}}}}///,
 	 ///value oo///
 	 },
+     PARA {
+	  "The optional argument ", TO "CompactMatrix", " may be used with ", TT "new MatrixExpression", " to specify
+	  whether the matrix should be displayed compactly."
+	  },
+     EXAMPLE lines ///
+     R = QQ[x];
+     f = {{x^2,x^3}}
+     new MatrixExpression from {f, CompactMatrix => false}
+     new MatrixExpression from {f, CompactMatrix => true}
+     ///,
+     PARA {
+	  "The optional argument ", TO "BlockMatrix", " may be used with ", TT "new MatrixExpression", " to specify
+	  the numbers of rows and columns to use when displaying the matrix as a block matrix."
+	  },
+     EXAMPLE lines ///
+     g = apply(4,i -> apply(4,j -> 10*i+j+10))
+     new MatrixExpression from { g, BlockMatrix => {{1,2},{3,1}}}
+     ///,
      SeeAlso => {"Table"}
      }
 

M2/Macaulay2/packages/Macaulay2Doc/doc4.m2

@@ -11,6 +11,44 @@ document {
      the exponent is negative."
      }
 
+document {
+     Key => { symbolBody, SymbolBody },
+     Headline => "symbol bodies",
+     PARA {
+	  "A Macaulay2 symbol is much like a function closure, in that it comes equipped with a pointer to a frame
+	  that contains a value for it.  That value can be recovered with the function ", TO "value", ", as follows."
+	  },
+     EXAMPLE lines ///
+     f = x -> symbol x
+     s = f 1
+     t = f 2
+     ///,
+     PARA {
+	  "The two symbols created in the example above have something in common -- they are created by the same bit
+	  of code (the function ", TT "f", "), but they have different values."
+	  },
+     EXAMPLE lines ///
+     value s
+     value t
+     ///,
+     PARA {
+	  "To allow the user to determine whether two symbols are created by the same bit of code, Macaulay2 has
+	  the notion of symbol body, which parallel to the notion of function body.  It's essentially the symbol, but
+	  without the pointer to the frame that contains the value."
+	  },
+     EXAMPLE lines ///
+     symbolBody s
+     symbolBody t
+     symbolBody s === symbolBody t
+     ///,
+     PARA {
+	  "All such symbol bodies are members of the class ", TT "SymbolBody", "."
+	  },
+     EXAMPLE lines ///
+     class symbolBody s
+     ///
+     }
+
 -- Local Variables:
 -- compile-command: "make -C $M2BUILDDIR/Macaulay2/m2 "
 -- End:

M2/Macaulay2/packages/Macaulay2Doc/doc_mutablematrices.m2

@@ -274,3 +274,48 @@ document {
 	  },
      SeeAlso => {"mutable matrices", "row and column operations"} 
      }
+
+document {
+     Key => { nullSpace, (nullSpace, MutableMatrix) },
+     Headline => "find the null space of a mutable matrix",
+     Usage => "nullSpace m",
+     Inputs => {
+	  "m" => MutableMatrix => { "over ", TO "RR", " or ", TO "CC" }
+	  },
+     Outputs => {
+	  MutableMatrix => {"a mutable matrix whose columns span the null space of ", TT "m"}
+	  },
+     EXAMPLE {
+	  "m = mutableMatrix {{1.p500,1},{-2,-2}}",
+	  "nullSpace m",
+	  "precision oo"
+	  }
+     }
+
+document {
+     Key => { rowRankProfile, (rowRankProfile, MutableMatrix)},
+     Headline => "find the row rank profile of a mutable matrix",
+     Usage => "rowRankProfile m",
+     Inputs => {
+	  "m" => MutableMatrix => { "over ", TO "RR", " or ", TO "CC" }
+	  },
+     Outputs => {
+	  List => {"the lexicographically smallest list of indices of linearly independent rows generating the row space of ", TT "m"}
+	  },
+     EXAMPLE "rowRankProfile mutableMatrix {{1,2,3}, {0,0,0.}, {3,4,5} }",
+     SeeAlso => { columnRankProfile }
+     }
+
+document {
+     Key => { columnRankProfile, (columnRankProfile, MutableMatrix)},
+     Headline => "find the column rank profile of a mutable matrix",
+     Usage => "columnRankProfile m",
+     Inputs => {
+	  "m" => MutableMatrix => { "over ", TO "RR", " or ", TO "CC" }
+	  },
+     Outputs => {
+	  List => {"the lexicographically smallest list of indices of linearly independent columns generating the column space of ", TT "m"}
+	  },
+     EXAMPLE "columnRankProfile transpose mutableMatrix {{1,2,3}, {0,0,0.}, {3,4,5} }",
+     SeeAlso => { rowRankProfile }
+     }

M2/Macaulay2/packages/Macaulay2Doc/doc_strings.m2

@@ -401,7 +401,7 @@ document {
 -- TODO: utf8check
 
 document {
-     Key => utf8,
+     Key => {utf8, utf8check},
      Headline => "encode and decode unicode utf-8-encoded strings",
      SYNOPSIS (
      	  Usage => "utf8 x",
@@ -430,6 +430,14 @@ document {
      PARA {
 	  "The two operations described above are inverse to each other."
 	  },
+     PARA {
+	  "The function ", TT "utf8check", " can be used to verify that a string contains a valid uft8-encoding of a sequence of
+	  unicode characters.  It returns ", TO "null", " upon success, and signals an error otherwise."
+	  },
+     EXAMPLE lines ///
+     try utf8check "你好" else "invalid"
+     try utf8check "\200\200" else "invalid"
+     ///,
      SeeAlso => {ascii},
      }
 

M2/Macaulay2/packages/Macaulay2Doc/functions/atan-doc.m2

@@ -48,3 +48,34 @@ document {
      	  "acot 2",
 	  }
      }
+
+document {
+     Key => {atanh, (atanh,Number), (atanh,Constant)},
+     Headline => "compute the hyperbolic arctangent of a number",
+     Usage => "atanh x",
+     Inputs => { "x" => { ofClass Number, " or ", ofClass Constant } },
+     Outputs => {
+	  Number => { "the hyperbolic arctangent of ", TT "x" }
+	  },
+     EXAMPLE {
+	  "atanh .4",
+	  "atanh 4."
+	  }
+     }
+
+document {
+     Key => {acoth, (acoth,Number), (acoth,Constant)},
+     Headline => "compute the hyperbolic arctangent of a number",
+     Usage => "acoth x",
+     Inputs => { "x" => { ofClass Number, " or ", ofClass Constant } },
+     Outputs => {
+	  Number => { "the hyperbolic arccotangent of ", TT "x" }
+	  },
+     EXAMPLE {
+	  "acoth .4",
+	  "acoth 4."
+	  }
+     }
+
+
+

M2/Macaulay2/packages/Macaulay2Doc/overview3.m2

@@ -284,7 +284,7 @@ document {
       sometimes one can just start Macaulay2 by setting the GC_INITIAL_HEAP_SIZE environment variable 
       to some larger value with an environment setting prefix on the M2 command line, e.g., ", TT "GC_INITIAL_HEAP_SIZE=20G M2", ".",
 	  },
-     SeeAlso => { collectGarbage }
+     SeeAlso => { collectGarbage, GCstats }
      }
 
 doc ///