# Hilbert Series

The following functions compute the Hilbert series information of graded or (homogeneous) modules. This depends on the column weights, just as in graded polynomial rings.

## `HilbertSeries(M): ModMPol -> FldFunElt`

Given a graded $R$-module $M$, return the Hilbert series $H_M(t)$ of $M$ (as an element of the univariate function field over the ring of integers). The $i$-th coefficient of the series gives the vector-space dimension of the degree-$i$ graded piece of $M$. The algorithm implemented is that given in [[Bayer and Stillman, 1992](../../references.md#cite-bayerstillman)]. Note that if $I$ is an ideal of the ring $R$, then the corresponding function for ideals [`HilbertSeries`](../PolynomialRingIdealOperations/hilbert.md#function-dpoly-ideal-hilbertseries) applied to $I$ gives the Hilbert series of the affine algebra (quotient) $R/I$, so this is equivalent to `HilbertSeries(QuotientModule(I))`.

## `HilbertSeries(M, p): ModMPol, RngIntElt -> RngSerLaurElt`

Given a graded $R$-module $M$, return the Hilbert series $H_M(t)$ of $M$ (as a Laurent series to precision $p$). (A Laurent series is required in general, since negative powers may occur when there are negative values in the grading of $M$.)

## `HilbertDenominator(M): ModMPol -> RngUPol`

Given a graded $R$-module $M$, return the unreduced Hilbert denominator $D$ of the Hilbert series $H_M(t)$ of $M$ (as a univariate polynomial over the ring of integers). The denominator $D$ equals [`HilbertDenominator`](../PolynomialRingIdealOperations/hilbert.md#function-dpoly-ideal-hilbertdenominator)`(R)` which is simply $\prod_{i=1}^n (1-t^{w_i}),$ where $n$ is the rank of $R$ and $w_i$ is the weight of the $i$-th variable (1 by default).

## `HilbertNumerator(M): ModMPol -> RngUPolElt, RngIntElt`

Given a graded $R$-module $M$, return the unreduced Hilbert numerator $N$ of the Hilbert series $H_M(t)$ of $M$ (as a univariate polynomial over the ring of integers) and a valuation shift $s$. The numerator $N$ equals $D\times t^s \times H_M(t)$, where $D$ is the unreduced Hilbert denominator above. Computing with the unreduced numerator is often more convenient. Note that $s$ will only be non-zero when $M$ has negative weights in its grading.

## `HilbertPolynomial(I): ModMPol -> RngUPolElt, RngIntElt`

Given a graded $R$-module $M$, return the Hilbert polynomial $H(d)$ of $M$ as an element of the univariate polynomial ring ${\mathbb{Q}}[d]$, together with the index of regularity of $M$ (the minimal integer $k \geq 0$ such that $H(d)$ agrees with the Hilbert function of $M$ at $d$ for all $d \geq k$).

## `Example: Hilbert (ex-ffdbad)`

We apply the Hilbert series functions to a simple quotient module.

```magma
> R<x,y,z> := PolynomialRing(RationalField(), 3);
> F := GradedModule(R, 3);
> M := quo<F | [x,0,0], [0,y^2,0]>;
> M;
Graded Module R^3/<relations>
Relations:
[  x,   0,   0],
[  0, y^2,   0]
> HilbertSeries(M);
(t^2 + t - 3)/(t^3 - 3*t^2 + 3*t - 1)
> HilbertSeries(M, 10);
3 + 8*s + 14*s^2 + 21*s^3 + 29*s^4 + 38*s^5 + 48*s^6 + 59*s^7 + 71*s^8 + 84*s^9
    + O(s^10)
> HilbertNumerator(M);
-x^2 - x + 3
0
> HilbertDenominator(M);
-x^3 + 3*x^2 - 3*x + 1
> HilbertPolynomial(M);
1/2*x^2 + 9/2*x + 3
0
> [Evaluate(HilbertPolynomial(F), i): i in [0..10]];
[ 3, 9, 18, 30, 45, 63, 84, 108, 135, 165, 198 ]

```

If the module has negative weights, then denominator may include extra powers of $t$, so the shift for the numerator will be non-zero.

```magma
> F := GradedModule(R, [-1]);
> F;
Free Graded Module R^1 with grading [-1]
> HilbertSeries(F);
-1/(t^4 - 3*t^3 + 3*t^2 - t)
> HilbertSeries(F, 10);
s^-1 + 3 + 6*s + 10*s^2 + 15*s^3 + 21*s^4 + 28*s^5 + 36*s^6 + 45*s^7 + O(s^8)
> HilbertNumerator(F);
1
1
> HilbertDenominator(F);
-x^3 + 3*x^2 - 3*x + 1
> HilbertPolynomial(F);
1/2*x^2 + 5/2*x + 3
-1
> [Evaluate(HilbertPolynomial(F), i): i in [-1..10]];
[ 1, 3, 6, 10, 15, 21, 28, 36, 45, 55, 66, 78 ]

```