hilbertSeries documentation does not mention numerator or denominator
- Dominant language
- Macaulay2
- Stars
- 435
- Forks
- 297
- Avg merge
- 4d 20h
- Merged PRs (30d)
- 11
Description
This issue was triaged from [`bugs/dan/1-doc-hilbertSeries`](https://github.com/Macaulay2/M2/blob/388c1ff0ce30d83751dea7bc7eac77fdc1305dd7/bugs/dan/1-doc-hilbertSeries), one of the 857 files removed from the pre-GitHub `bugs/` tree by [`d2c8d27826`](https://github.com/Macaulay2/M2/commit/d2c8d27826) and catalogued in [#36](https://github.com/Macaulay2/M2/issues/36). **The commentary below was written by Claude (Claude Opus 5, via Claude Code)**, not by @d-torrance, whose account posted it -- please weigh it accordingly.
### The original file, verbatim
```text
improve the documentation of hilbertSeries:
R = kk[a..d]
phi = map(kk[s,t],R,{s^4, s^3*t, s*t^3, t^4})
I = ker phi
I = monomialCurveIdeal(R,{1,3,4})
dim I
codim I
degree I
hilbertPolynomial(R/I)
hilbertPolynomial(R/I, Projective => false)
hilbertPolynomial(R/I, Projective => true)
hilbertSeries (R/I)
reduceHilbert hilbertSeries (R/I)
-- It's possible to manipulate the numerator and denominator of this
-- expression; see
viewHelp hilbertSeries
{*
This is NOT in the documentation for hilbertSeries yet. Need to
add references to
"numerator", value denominator, etc.
*}
```
### Where it stands today
The specific documentation gap the file names is still there.
All three operations work. On `monomialCurveIdeal(QQ[a..d], {1,3,4})`:
```m2
i1 : hilbertSeries (R/I) -- returns a Divide
i2 : numerator oo -- 1-T^2-3T^3+4T^4-T^5
i3 : denominator hilbertSeries (R/I) -- (1-T)^4
i4 : value oo -- 1-4T+6T^2-4T^3+T^4
```
But `help hilbertSeries` mentions **none** of them. Its See-also list is `degreesRing`,
`reduceHilbert`, `poincare`, `poincareN`, `hilbertPolynomial`, `hilbertFunction`. The file's request is
*"Need to add references to numerator, value denominator, etc."*, and that is exactly what is absent.
### Why the current text is not enough
The prose does say the result is "a type of expression called a `Divide`", which is the hint — but a
reader then has to guess that `numerator`, `denominator` and `value` apply to it. Naming them is the
difference between knowing the type and being able to use the result.
### Neighbouring open issues, neither of them this
**#974** (`value` of a Hilbert series failing because the parts live in a Laurent ring) and **#1701**
(`hilbertSeries MonomialIdeal`).
`open` · disposition `issue` · source of truth: [`bug-triage/catalog.tsv`](https://github.com/d-torrance/M2/blob/bug-triage/bug-triage/catalog.tsv)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the `help hilbertSeries` entry and its current See-also list, then review the examples in the issue using `numerator`, `denominator`, and `value`. Done means the documentation explains how these operations apply to the `Divide` result and references them appropriately; verify the documented examples still work.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 82/100