Missing documentation nodes in Macaulay2Doc

[mahrud]

After #1666 is merged, there will be 214 warnings left, and 1370 node are not subnodes, which would be good to improve.

• missing nodes:

  • CC'
  • GCstats
  • RR'
  • SymbolBody
  • columnRankProfile
  • isWeylAlgebra
  • monomialCurveIdeal
  • nullSpace
  • rowRankProfile
  • symbolBody
  • utf8check

• missing methods:

  • (ambient,AffineVariety)
  • (ambient,CoherentSheaf)
  • (ambient,GradedModule)
  • (ambient,ProjectiveVariety)
  • (binomial,RingElement,ZZ)
  • (columnRankProfile,MutableMatrix)
  • (debug,ZZ)
  • (degree,ChainComplexMap)
  • (degree,GradedModuleMap)
  • (degree,Matrix)
  • (indices,HashTable)
  • (isHomogeneous,Number)
  • (isHomogeneous,PolynomialRing)
  • (isHomogeneous,QuotientRing)
  • (isWeylAlgebra,Ring)
  • (jacobian,RingElement)
  • (lift,Matrix,CC',CC')
  • (lift,Matrix,RR',RR')
  • (lift,Module,InexactNumber')
  • (lift,Module,InexactNumber)
  • (lift,Module,Number)
  • (lift,Module,RingElement)
  • (lift,MutableMatrix,InexactNumber')
  • (lift,MutableMatrix,InexactNumber)
  • (lift,MutableMatrix,Number)
  • (lift,MutableMatrix,RingElement)
  • (liftable,CC,RR')
  • (map,ChainComplex,ChainComplex,ChainComplexMap)
  • (map,GaloisField,GaloisField)
  • (module,Ideal)
  • (nullSpace,MutableMatrix)
  • (part,InfiniteNumber,InfiniteNumber,Number)
  • (part,InfiniteNumber,ZZ,Number)
  • (part,ZZ,InfiniteNumber,Number)
  • (part,ZZ,Number)
  • (part,ZZ,ZZ,Number)
  • (promote,Module,InexactNumber')
  • (promote,Module,InexactNumber)
  • (promote,Module,Number)
  • (promote,Module,RingElement)
  • (promote,MutableMatrix,InexactNumber')
  • (promote,MutableMatrix,InexactNumber)
  • (promote,MutableMatrix,Number)
  • (promote,MutableMatrix,RingElement)
  • (promote,Vector,InexactNumber')
  • (promote,Vector,InexactNumber)
  • (promote,Vector,Number)
  • (promote,Vector,RingElement)
  • (rowRankProfile,MutableMatrix)
  • (sort,List,Function)

• sources of missing citations:

  • \
  • ^
  • _
  • _*
  • %
  • *
  • **
  • +
  • -
  • ..
  • ..<
  • /
  • //
  • :
  • ==
  • ?
  • ChangeMatrix
  • Constants
  • Generic
  • GroebnerBasis
  • HH
  • HH^ZZ SumOfTwists
  • IndexedVariableTable
  • InexactNumber
  • Jacobian
  • Limit
  • Limit
  • List
  • Matrix
  • MethodFunction
  • MethodFunctionWithOptions
  • MonoidElement
  • OrderedMonoid
  • RingMap
  • Symbol
  • UserMode
  • Variable
  • ZZ
  • check
  • determinant(...,Strategy=>...)
  • gcd
  • getSymbol
  • loadDepth
  • not
  • solve
  • symmetricAlgebra
  • tensor(Ring,RingMap,Matrix)

[mahrud]

@DanGrayson could you document the 11 missing nodes at the top? I tried looking at a the source code for few of them, but I have no idea what most of them are intended to do.

[DanGrayson]

@DanGrayson could you document the 11 missing nodes at the top? I tried looking at a the source code for few of them, but I have no idea what most of them are intended to do.

Sure, but not soon.

[mahrud]

@DanGrayson when the items above are documented, we can switch to raising an error for items with missing documentation so that going forward pull requests are forced to document everything. Otherwise the list slowly grows.

[DanGrayson]

@DanGrayson when the items above are documented, we can switch to raising an error for items with missing documentation so that going forward pull requests are forced to document everything. Otherwise the list slowly grows.

Yes, indeed, we should do that.

[DanGrayson]

@mikestillman should document "columnRankProfile" -- I don't know anything about it.

[DanGrayson]

@mikestillman should document "rowRankProfile" -- I don't know anything about it.

[DanGrayson]

@mikestillman -- just tell me what those two functions do and I'll document them today.

[DanGrayson]

@mikestillman -- never mind, I found it online.

[DanGrayson]

@mikestillman -- shouldn't the row rank equal the column rank?

i30 : f = mutableMatrix {{1,2,3}, {3,4,5}, {4,6,8.} }

o30 = | 1 2 3 |
      | 3 4 5 |
      | 4 6 8 |

o30 : MutableMatrix

i31 : rowRankProfile f

o31 = {0, 1, 2}

o31 : List

i32 : columnRankProfile f

o32 = {0, 1}

o32 : List

[DanGrayson]

@antonleykin -- can you tell me what "toricIdealPartials" in Dmodules does? I'll document it for you today.

[DanGrayson]

@ggsmith @denham0 -- shall I rename "tolist" to "toList" for you in the package HyperplaneArrangements? And how shall we document its two methods?

[DanGrayson]

@mikestillman @luisgarciapuente -- if you tell me what globalMarkovStmts does in the package Markov, I can document it for you.

[luisgarciapuente]

The package Markov should no longer be used since GraphicalModels has superseded it for more than a decade. But in any case, globalMarkovStmts is now called globalMarkov which is documented

https://faculty.math.illinois.edu/Macaulay2/doc/Macaulay2/share/doc/Macaulay2/GraphicalModels/html/_global__Markov.html

[mikestillman]

Maybe we should move Markov to undistributedpackages? Or legacy packages? Or remove it entirely? I do have some old code that uses that package, so I might prefer one of the first 2 options, although I can try to get my old code working with the latest version (if all functionality appears in your "new" package. I checked at one point, but forget what I did, or noticed).

[luisgarciapuente]

In deed, even I have some old code that uses Markov that I have not taken the time to update to GraphicalModels. I also know that some people elsewhere still use it. So I also agree to move it to legacy packages but not to remove it.

But definitely at this point GraphicalModels has all the exported functionality of Markov and more. Also, through the years, we have fixed some bugs in GraphicalModels and some of those were legacy bugs from Markov.

Maybe we should add a note on Markov that users are strongly encouraged to use GraphicalModels instead?

[DanGrayson]

Well, if we're not going to remove the package "Markov", and we're going to keep distributing it, then we should at least make sure it works. (I'm working on making it an error for a package to have missing documentation nodes.) The symbol "globalMarkov" is in a different package, so even though it's documented, that doesn't help document globalMarkovStmts in this package.

We don't have a class of packages called "legacy packages". I think we don't need one, either. Just add a statement to the documentation of Markov that there is a modern replacement available.

[antonleykin]

@antonleykin -- can you tell me what "toricIdealPartials" in Dmodules does? I'll document it for you today.

This seems to create a toric ideal describing the image of the given monomial map.

i2 : examples gkz

o2 =
     A = matrix{{1,1,1},{0,1,2}}
     b = {3,4}
     I = gkz (A,b)
     describe ring I
     D = makeWA(QQ[x_1..x_3])
     gkz(A,b,D)
     toricIdealPartials(A,D)
     eulerOperators(A,b,D)

The exponents of the monomials in the monomial map here are the columns of A and the "partials" (differential variables) in D are used as variables in the polynomial ring that houses the output.

[ggsmith]

Since toList is a CompiledFunction rather than a method, it appeared (at least to us) that we could not overload it. The tolist method was created as a kludge. How does one overload a CompiledFunction?

We (Avi Steiner, @denham0 ,and @ggsmith) also anticipate making a pull request for a major revision of the HyperplaneArrangements package before the end of April. As a consequence, having you (@DanGrayson) edit the documentation for this particular method does not make much sense to me.

[DanGrayson]

@antonleykin -- thanks. I've added this:

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)
     ///
     }

[DanGrayson]

Since toList is a CompiledFunction rather than a method, it appeared (at least to us) that we could not overload it. The tolist method was created as a kludge. How does one overload a CompiledFunction?

Ah, I'll fix that by changing toList into a function with methods.

We (Avi Steiner, @denham0 ,and @ggsmith) also anticipate making a pull request for a major revision of the HyperplaneArrangements package before the end of April. As a consequence, having you (@DanGrayson) edit the documentation for this particular method does not make much sense to me.

Okay.

[DanGrayson]

Since toList is a CompiledFunction rather than a method, it appeared (at least to us) that we could not overload it. The tolist method was created as a kludge. How does one overload a CompiledFunction?

Ah, I'll fix that by changing toList into a function with methods.

That's been done in #2433 -- enjoy!

[mikestillman]

Ouch. Yes!

…

Sent from my iPhone

On Apr 12, 2022, at 4:24 PM, Daniel R. Grayson ***@***.***> wrote:  @mikestillman -- shouldn't the row rank equal the column rank? i30 : f = mutableMatrix {{1,2,3}, {3,4,5}, {4,6,8.} } o30 = | 1 2 3 | | 3 4 5 | | 4 6 8 | o30 : MutableMatrix i31 : rowRankProfile f o31 = {0, 1, 2} o31 : List i32 : columnRankProfile f o32 = {0, 1} o32 : List — Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you were mentioned.

[mahrud]

@pzinn can you think of a way to either automatically document these or mark them as undocumented?

o48 = {0 => (**, Expression, TensorProduct)   }
      {1 => (**, TensorProduct, Expression)   }
      {2 => (**, TensorProduct, TensorProduct)}
      {3 => (*, Expression, Product)          }
      {4 => (*, Product, Expression)          }
      {5 => (*, Product, Product)             }
      {6 => (++, DirectSum, DirectSum)        }
      {7 => (++, DirectSum, Expression)       }
      {8 => (++, Expression, DirectSum)       }
      {9 => (+, Expression, Sum)              }
      {10 => (+, Sum, Expression)             }
      {11 => (+, Sum, Sum)                    }
      {12 => (-, ZeroExpression)              }
      {13 => (==, Equation, Equation)         }
      {14 => (==, Equation, Expression)       }
      {15 => (==, Expression, Equation)       }
      {16 => (expression, Expression)         }
      {17 => (hold, Expression)               }

(The list is just everything without documentation that inherits from an Expression).

Currently some methods like this are manually marked as undocumented, e.g:

M2/M2/Macaulay2/packages/Macaulay2Doc/doc12.m2

Lines 284 to 291 in ec9e9ac

	undocumented {
	(symbol -, Thing, Minus),
	(symbol +, Sum, Sum),
	(symbol +, Sum, Holder),
	(symbol +, Holder, Sum),
	(symbol +, ZeroExpression, Expression),
	(symbol +, Expression, ZeroExpression),
	}

But maintaining this by hand is hard, and I want something straightforward like this:

M2/M2/Macaulay2/packages/Macaulay2Doc/doc12.m2

Lines 293 to 299 in ec9e9ac

	expressionMethodKeys := flatten apply(toList core "expressionBinaryOperators", op -> {
	(op, Expression, Expression),
	(op, Expression, Holder),
	(op, Expression, Thing),
	(op, Holder, Expression),
	(op, Holder, Holder),
	(op, Thing, Expression)})

[pzinn]

yeah that shouldn't be too hard.