:= PolynomialRing(R, 3);
> I := ideal;
> GroebnerBasis(I);
[
x^2 + 26*w*y,
3*x*y^3 + (6*w + 6)*y*z,
3*x*z + (15*w + 3)*y^3,
9*x + (9*w + 9)*y^3*z^4,
3*y^6 + (21*w + 15)*y*z^2,
9*z^5 + 18*w
]
```
Notice that the leading coefficients include 3 and 9, which are not units in the ring. See Chapter [Gröbner Bases](https://docs.magma-maths.org/CommutativeAlgebra/GrobnerBases/index-grobner-bases.md#chapgb) for much more information on such Gröbner bases.
## Newton Polygons
- [Introduction](https://docs.magma-maths.org/LocalFields/NewtonPolygons/introduction.md)
- [Newton Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md)
- [Creation of Newton Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#creation-of-newton-polygons)
- [`NewtonPolygon(f): RngMPolElt → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-rngmpolelt)
- [`NewtonPolygon(f): RngUPolElt → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-rngupolelt)
- [`NewtonPolygon(f, p): RngUPolElt, RngOrdIdl → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-rngupolelt-rngordidl)
- [`NewtonPolygon(f, p): RngUPolElt, RngFunOrdIdl → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-rngupolelt-rngfunordidl)
- [`NewtonPolygon(f, p): RngUPolElt, RngIntElt → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-rngupolelt-rngintelt)
- [`NewtonPolygon(f, p): RngUPolElt, PlcFunElt → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-rngupolelt-plcfunelt)
- [`NewtonPolygon(C): Crv → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-crv)
- [`NewtonPolygon(V): SeqEnum → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-seqenum)
- [`NewtonPolygon(V): SetEnum → NwtnPgon`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-newtonpolygon-setenum)
- [`DefiningPoints(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-definingpoints-nwtnpgon)
- [Example: Creating Newton Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#example-ex-4f67e3)
- [Vertices and Faces of Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#vertices-and-faces-of-polygons)
- [`Faces(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-faces-nwtnpgon)
- [`InnerFaces(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-innerfaces-nwtnpgon)
- [`LowerFaces(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-lowerfaces-nwtnpgon)
- [`OuterFaces(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-outerfaces-nwtnpgon)
- [`AllFaces(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-allfaces-nwtnpgon)
- [Example: Faces of a Newton Polygon](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#example-ex-a15e3f)
- [`Vertices(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-vertices-nwtnpgon)
- [`InnerVertices(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-innervertices-nwtnpgon)
- [`LowerVertices(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-lowervertices-nwtnpgon)
- [`OuterVertices(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-outervertices-nwtnpgon)
- [`AllVertices(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-allvertices-nwtnpgon)
- [Example: Vertices of a Newton Polygon](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#example-ex-534640)
- [`EndVertices(F): NwtnPgonFace → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-endvertices-nwtnpgonface)
- [`FacesContaining(N,p): NwtnPgon, Tup → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-facescontaining-nwtnpgon-tup)
- [Example: End Vertices and Containing Faces](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#example-ex-8ed2f7)
- [`GradientVector(F): NwtnPgonFace → Tup`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-gradientvector-nwtnpgonface)
- [`GradientVectors(N): NwtnPgon → [ Tup ]`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-gradientvectors-nwtnpgon)
- [`Weight(F): NwtnPgonFace → RngIntElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-weight-nwtnpgonface)
- [`Slopes(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-slopes-nwtnpgon)
- [`InnerSlopes(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-innerslopes-nwtnpgon)
- [`LowerSlopes(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-lowerslopes-nwtnpgon)
- [`AllSlopes(N): NwtnPgon → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-allslopes-nwtnpgon)
- [Example: Gradient Vector and Weight of a Face](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#example-ex-260949)
- [Tests for Points and Faces](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#tests-for-points-and-faces)
- [`IsFace(N, F): NwtnPgon, Tup → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-isface-nwtnpgon-tup)
- [`IsVertex(N, p): NwtnPgon, Tup → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-isvertex-nwtnpgon-tup)
- [`IsInterior(N,p): NwtnPgon, Tup → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-isinterior-nwtnpgon-tup)
- [`IsBoundary(N, p): NwtnPgon, Tup → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-isboundary-nwtnpgon-tup)
- [`IsPoint(N,p): NwtnPgon, Tup → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#function-ispoint-nwtnpgon-tup)
- [Polynomials Associated with Newton Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md)
- [`HasPolynomial(N): NwtnPgon → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-haspolynomial-nwtnpgon)
- [`Polynomial(N): NwtnPgon → RngElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-polynomial-nwtnpgon)
- [`ParentRing(N): NwtnPgon → Rng`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-parentring-nwtnpgon)
- [`IsNewtonPolygonOf(N, f): NwtnPgon, RngElt → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-isnewtonpolygonof-nwtnpgon-rngelt)
- [`FaceFunction(F): NwtnPgonFace → RngElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-facefunction-nwtnpgonface)
- [`IsDegenerate(F): NwtnPgonFace → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-isdegenerate-nwtnpgonface)
- [`IsDegenerate(N): NwtnPgon → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-isdegenerate-nwtnpgon)
- [`IsNondegenerate(F): NwtnPgonFace → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-isnondegenerate-nwtnpgonface)
- [`IsNondegenerate(N): NwtnPgon → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton-polynomials.md#function-isnondegenerate-nwtnpgon)
- [Finding Valuations of Roots of Polynomials from Newton Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/val.md)
- [`ValuationsOfRoots(f): RngUPolElt → [ < RngIntElt, RngIntElt > ]`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/val.md#function-valuationsofroots-rngupolelt)
- [`ValuationsOfRoots(f, p): RngUPolElt, RngIntElt → [ < RngIntElt, RngIntElt > ]`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/val.md#function-valuationsofroots-rngupolelt-rngintelt)
- [`ValuationsOfRoots(f, p): RngUPolElt, RngOrdIdl → [ < RngIntElt, RngIntElt > ]`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/val.md#function-valuationsofroots-rngupolelt-rngordidl)
- [`ValuationsOfRoots(f, p): RngUPolElt, PlcFunElt → [ < RngIntElt, RngIntElt > ]`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/val.md#function-valuationsofroots-rngupolelt-plcfunelt)
- [Using Newton Polygons to Find Roots of Polynomials over Series Rings](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md)
- [`SetVerbose("Newton", v): MonStgElt, RngIntElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#procedure-setverbose-monstgelt-rngintelt-newton)
- [Operations not associated with Duval’s Algorithm](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#operations-not-associated-with-duval-s-algorithm)
- [`PuiseuxExpansion(f, n): RngUPolElt, RngIntElt → SeqEnum[RngSerPuisElt]`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-newton-puiseuxexpansion)
- [`ExpandToPrecision(f, c, n): RngUPolElt, RngSerElt, RngIntElt → RngSerElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-expandtoprecision-rngupolelt-rngserelt-rngintelt)
- [`ImplicitFunction(f, d, n): RngUPolElt, RngIntElt, RngIntElt → RngSerElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-implicitfunction-rngupolelt-rngintelt-rngintelt)
- [Example: Puiseux Expansions to Higher Precision](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#example-ex-d1b398)
- [`IsPartialRoot(f, c): RngUPolElt, RngSerElt → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-ispartialroot-rngupolelt-rngserelt)
- [`IsUniquePartialRoot(f, c): RngUPolElt, RngSerElt → BoolElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-isuniquepartialroot-rngupolelt-rngserelt)
- [Example: Checking That a Partial Root Can Be Expanded](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#example-ex-5113cd)
- [`PuiseuxExponents(p): RngSerElt → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-puiseuxexponents-rngserelt)
- [`PuiseuxExponentsCommon(p, q): RngSerElt, RngSerElt → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-puiseuxexponentscommon-rngserelt-rngserelt)
- [Example: Exponents of Puiseux Expansions](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#example-ex-cc0585)
- [Operations associated with Duval’s algorithm](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#operations-associated-with-duval-s-algorithm)
- [`DuvalPuiseuxExpansion(f, n): RngUPolElt, RngIntElt → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-duvalpuiseuxexpansion-rngupolelt-rngintelt)
- [`ParametrizationToPuiseux(T): Tup → SeqEnum`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-parametrizationtopuiseux-tup)
- [`PuiseuxToParametrization(S): RngSerElt → Tup`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-puiseuxtoparametrization-rngserelt)
- [Example: Duval's Algorithm for Puiseux Expansions](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#example-ex-2dca42)
- [Roots of Polynomials](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#roots-of-polynomials)
- [`Roots(f): RngUPolElt → []`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-roots-rngupolelt)
- [`Roots(f, n): RngUPolElt, RngIntElt → []`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-roots-rngupolelt-rngintelt)
- [`HasRoot(f): RngUPolElt → BoolElt, RngSerElt`](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#function-hasroot-rngupolelt)
- [Example: Roots of Polynomials over Puiseux Series](https://docs.magma-maths.org/LocalFields/NewtonPolygons/poly-ops.md#example-ex-0c4847)
- [Bibliography](https://docs.magma-maths.org/LocalFields/NewtonPolygons/bibliography.md)
### Introduction
This chapter introduces functions which allow the construction and simple study of Newton polygons. It allows data from a number of different contexts to be used to construct the polygons. It also covers different interpretations of Newton polygons, and translation among these interpretations. Recall that a Newton polygon is the intersection of finitely many rational half spaces in the rational plane. An advantage of this definition is that it emphasizes that Newton polygons are often thought of as being noncompact. However, they are not implemented here in this way. Instead polygons are interpreted as the convex hull of finitely many points of the plane (possibly including some points at $+\infty$ along the axes).
Any Newton polygon is contained in some virtual cartesian product of the rational field with itself (virtual since this plane is not a structure that is intended to be accessible to the user or which is characteristic of the polygon). The first and second coordinate functions of this plane are referred to as the $x$ and $y$ coordinates respectively. Points of the plane will always be written $\left< a,b \right>$ while faces of polygons will be written $\left< a,b,c \right>$. Geometrically, a face $\left< a,b,c \right>$ is a one-dimensional boundary intersection of $N$ with the line $ax+by=c$.
The *standard Newton polygon* of a polynomial $f=f(u,v)$ is, by definition, the convex hull of the points $\left< a,b \right>$, so-called *Newton points*, ranging over monomials $u^av^b$ having nonzero coefficient in $f$ together with the points $+\infty$ on the two axes. The infinite points, however, are not listed among the vertices of the polygon; they are simply a convenient way of hiding all Newton points other than those on the ‘lower lefthand’ faces of the hull of those points. A similar definition applies to polynomials $f(y)$ whose coefficients lie in some field of fractional power series, or *Puiseux field*, $k\left<\!\left< x \right>\!\right>$. Newton Polygons can also be created for polynomials over local rings (and fields). The defining points are computed as $\langle i, v(a_i) \rangle$ where $a_i$ is the coefficient of the $i$-th power of the generator and $v$ denotes the valuation function on the ring. Infinite points arise only as the valuation of zero coefficients.
The main intended application of Newton polygons is to the Newton–Puiseux analysis of singular points of plane curves, or put another way, the factorization of polynomials defined over Puiseux fields.
The examples below should be thought of as running consecutively in a single Magma session.
```
> R := PolynomialRing(Rationals(),2);
> f := x^5 + x^2*y + x^2*y^3 + y^4 + x^3*y^5 + y^2*x^7;
> N := NewtonPolygon(f);
> N;
Newton Polygon of x^7*y^2 + x^5 + x^3*y^5 + x^2*y^3 + x^2*y + y^4 over
Rational Field
> Faces(N);
[ <3, 2, 8>, <1, 3, 5> ]
> Vertices(N);
[ <0, 4>, <2, 1>, <5, 0> ]
```
This is the standard Newton polygon associated with the polynomial $f$. Only those vertices and faces of the convex hull of points which correspond to the monomials appearing in $f$ which ‘face’ the origin are considered to be vertices and faces of the polygon. As already mentioned, one interpretation of this is to think of the points $+\infty$ on each axis as being included among the defining points of $N$, and then $N$ is the convex hull of its defining points.
To consider $N$ as the compact convex hull of only the monomials of $f$ simply use alternative vertex and face functions.
```
> AllVertices(N);
[ <0, 4>, <2, 1>, <5, 0>, <7, 2>, <3, 5> ]
> AllFaces(N);
[ <3, 2, 8>, <1, 3, 5>, <-1, 1, -5>, <-3, -4, -29>, <1, -3, -12> ]
```
However, where there is a choice of interpretation, Magma always interprets $N$ in the way it was defined. So for example, the functions which test for faces and vertices compare a given value with the sequence returned by the functions `Faces(N)` or `Vertices(N)`, which are fixed the first time they are calculated, rather than with any other collections of faces or vertices.
```
> IsFace(N,<3/4,3/6,2>);
true <3, 2, 8>
> IsFace(N,<-3,-4,-29>);
false
```
Notice that faces are reduced to normal integral form and that the correct form is returned as the second return value of the test function.
When a polygon is created using a polynomial, the restriction of the polynomial to faces is important characteristic data.
```
> FaceFunction(Faces(N)[1]);
x^2*y + y^4
```
The face function is simply the sum of those monomial terms of $f$ (they keep their coefficients) whose corresponding Newton point lies on the given face.
### Newton Polygons
All polygons are determined by a finite collection of points in the rational plane. For Magma, these points are the most basic attribute of any Newton polygon. They are always determined and recorded on creation of a polygon. Throughout this chapter, for a Newton polygon $N$, these points are denoted by $P_N$. As seen in the introduction, the main class of polygons is that comprising polygons in the first quadrant of the plane and including the points $+\infty$ on the two axes. But there are other useful types, especially when calculating factorizations of univariate polynomials over series rings. The data distinguishing the different flavours of Newton polygon is the collection of lines and points that are considered to be faces and vertices.
#### Creation of Newton Polygons
These are the functions available for constructing Newton polygons and retrieving the points which describe them.
##### `NewtonPolygon(f): RngMPolElt -> NwtnPgon`
```magma
Faces: MonStgElt Default: "Inner"
```
The standard Newton polygon of a polynomial $f$ in two variables. This is the hull of the Newton points of the polynomial together with the points $+\infty$ on each axis. The horizontal and vertical ‘end’ faces are not listed among the faces of the polygon; the points at infinity are not listed among the vertices of the polygon.
The parameter `Faces` can have the value `"Inner"`, `"Lower"`, or `"All"`. This determines which faces are returned by the intrinsic `Faces`.
##### `NewtonPolygon(f): RngUPolElt -> NwtnPgon`
```magma
SwapAxes: BoolElt Default: false
Faces : MonStgElt Default:
```
The standard Newton polygon of a polynomial in one variable defined over a series ring or a local ring or field. A value of `true` for `SwapAxes` is only valid if the polynomial is over a series ring. If `SwapAxes` is set to `true` then the exponents of the series variable will be plotted on the horizontal axis and the exponents of the polynomial on the vertical axis.
For a polynomial over a series ring, the hull includes the points $+\infty$ on each axis. For a polynomial over a local ring, the infinite points are not included.
The parameter `Faces` can have the value `"All"`, `"Inner"`, or `"Lower"`. This determines which faces are returned by the intrinsic `Faces`. The default for series rings is `"Inner"` and for local rings is `"Lower"`.
##### `NewtonPolygon(f, p): RngUPolElt, RngOrdIdl -> NwtnPgon`
##### `NewtonPolygon(f, p): RngUPolElt, RngFunOrdIdl -> NwtnPgon`
##### `NewtonPolygon(f, p): RngUPolElt, RngIntElt -> NwtnPgon`
```magma
Faces: MonStgElt Default: "Inner"
```
The newton polygon of $f$ where $p$ is a prime used for valuations of the coefficients of $f$. The polynomial $f$ may be over the integers or rationals or a number field or algebraic function field or an order thereof. The prime $p$ may be an integer or a prime ideal. The newton polygon will have points $(i, v_i)$ where $i$ is the exponent of a term of $f$ and $v_i$ is the valuation of the coefficient of the $i$th term. The points at $+\infty$ on each axis are included.
The parameter `Faces` can have the value `"Inner"`, `"Lower"`, or `"All"`. This determines which faces are returned by the intrinsic `Faces`.
##### `NewtonPolygon(f, p): RngUPolElt, PlcFunElt -> NwtnPgon`
```magma
Faces: MonStgElt Default: "Inner"
```
The newton polygon of the polynomial $f$ where the place $p$ of an algebraic function field is the prime used for determining the valuations of the coefficients of $f$. The points at $+\infty$ on each axis are included.
The parameter `Faces` can have the value `"Inner"`, `"Lower"`, or `"All"`. This determines which faces are returned by the intrinsic `Faces`.
##### `NewtonPolygon(C): Crv -> NwtnPgon`
The standard Newton polygon of the defining polynomial of the curve $C$.
##### `NewtonPolygon(V): SeqEnum -> NwtnPgon`
##### `NewtonPolygon(V): SetEnum -> NwtnPgon`
```magma
Faces: MonStgElt Default: "All"
```
The Newton polygon that is the compact convex hull of the set or sequence $V$ of points of the form $\left< a,b \right>$ where $a$, $b$ are integers or rational numbers.
The parameter `Faces` can have the value `"All"`, `"Lower"`, or `"Inner"`. This determines which faces are returned by the intrinsic `Faces`.
##### `DefiningPoints(N): NwtnPgon -> SeqEnum`
The points of the rational plane used in the initial creation of $N$. Applying this function to two polygons allows their defining points to be compared. No explicit function is provided for testing whether defining points of two polygons are equal.
##### `Example: Creating Newton Polygons (ex-4f67e3)`
Some ways of creating Newton Polygons from polynomials are shown below.
```magma
> P := PuiseuxSeriesRing(Rationals());
> R := PolynomialRing(P);
> f := 3*x^4 + (5*y^3 + 4*y^(1/4))*x^3 + (7*y^2 + 1/2*y^(1/3))*x^2 + 6*x + y^(
> 4/5);
> N := NewtonPolygon(f);
> N;
Newton Polygon of 3*x^4 + (4*y^(1/4) + 5*y^3)*x^3 + (1/2*y^(1/3) + 7*y^2)*x^2 +
6*x + y^(4/5) over Puiseux series field in y over Rational Field
> P := PolynomialRing(Integers());
> L := ext | x^2 + 5>;
> R := PolynomialRing(L);
> f := 3*x^4 + 75*x^3 + 78*x^2 + 10*x + 750;
> NR := NewtonPolygon(f);
> NR;
Newton Polygon of 3*x^4 + 75*x^3 + 78*x^2 + 10*x + 750 over L
```
Newton Polygons can also be created by specifying the defining points that the polygon must enclose.
```magma
> N2 := NewtonPolygon({<2, 0>, <0, 3>, <4, 1>});
> N2;
Newton Polygon with defining points {(0, 3), (2, 0), (4, 1)}
> N6 := NewtonPolygon({<1, 4>, <1, 6>, <2, 4>, <3, 1>, <6, 1>, <5, 2>, <4, 5>,
> <4, 7>, <6, 6>, <7, 7>, <2, 7>, <5, 9>, <8, 4>, <8, 6>, <8, 8>, <7, 9>});
> N6;
Newton Polygon with defining points {(1, 4), (1, 6), (2, 4), (2, 7), (3, 1), (4,
5), (4, 7), (5, 2), (5, 9), (6, 1), (6, 6), (7, 7), (7, 9), (8, 4), (8, 6), (8,
8)}
```
These polygons will be referred to in later examples.
#### Vertices and Faces of Polygons
Both the vertices $\left< a,b \right>$ and faces $\left< a,b,c \right>$ (representing $ax + by = c$) of a given polygon $N$ are computed as needed. As seen above, these will be a particular choice of possible faces and vertices determined by the data used to create the polygon. They can be recovered using the `Faces()` and `Vertices()` intrinsics. A different choice of faces and vertices, those faces and vertices of the compact convex hull of the defining points say, can be made using the other intrinsics below.
Recall that $P_N$ denotes the set of points used in the definition of the Newton polygon $N$ whether they arise as the powers of monomials appearing in a polynomial or have been given explicitly as a sequence of pairs.
##### `Faces(N): NwtnPgon -> SeqEnum`
The sequence of faces $\left< a, b, c \right>$ (representing $ax + by = c$) of $N$ listed anticlockwise. How this is interpreted in terms of the points used to create $N$ depends on the creation function used (see Section [Creation of Newton Polygons](https://docs.magma-maths.org/LocalFields/NewtonPolygons/newton.md#newton-pgon-creation)). The faces are listed anticlockwise starting with the face with its left endpoint being the lowest of the leftmost points.
##### `InnerFaces(N): NwtnPgon -> SeqEnum`
Those faces of the compact convex hull of $P_N$ starting at the lowest of the leftmost points which have strictly negative gradient.
##### `LowerFaces(N): NwtnPgon -> SeqEnum`
Those faces of the compact convex hull of $P_N$ which bound it below in the $y$ direction.
##### `OuterFaces(N): NwtnPgon -> SeqEnum`
The union of lower faces which aren’t inner faces and the faces which bound the compact convex hull of $P_N$ above in the $y$-direction (ignoring infinite points).
##### `AllFaces(N): NwtnPgon -> SeqEnum`
The faces of the compact convex hull of $P_N$.
##### `Example: Faces of a Newton Polygon (ex-a15e3f)`
Using some of the polygons defined before the different types of faces are illustrated.
```magma
> Faces(N);
[ <4, 5, 4> ]
> InnerFaces(N);
[ <4, 5, 4> ]
> OuterFaces(N);
[ <0, 1, 0>, <-1, -4, -4>, <-11, -60, -48> ]
> AllFaces(N);
[ <4, 5, 4>, <0, 1, 0>, <-1, -4, -4>, <-11, -60, -48> ]
> Faces(NR);
[ <4, 1, 6>, <2, 1, 4>, <0, 1, 0> ]
> InnerFaces(NR);
[ <4, 1, 6>, <2, 1, 4> ]
> LowerFaces(NR);
[ <4, 1, 6>, <2, 1, 4>, <0, 1, 0> ]
```
For the polynomial over the Puiseux Field it is no coincidence that `InnerFaces` and `Faces` return the same sequences. Similarly, for the polynomial over the local ring `Faces` is defined to be `LowerFaces`. For both, this is the category of faces that gives the most information for the purposes that the polygon is used. It can also be noted that combining `InnerFaces` and `OuterFaces` will give `AllFaces` with no repetitions (though repetitions will occur if the polygon has only one face and this face is an inner face).
##### `Vertices(N): NwtnPgon -> SeqEnum`
The sequence of vertices of $N$. The vertices will be listed anticlockwise from the lowest of the leftmost points.
##### `InnerVertices(N): NwtnPgon -> SeqEnum`
The sequence of vertices which arise as endpoints of inner faces.
##### `LowerVertices(N): NwtnPgon -> SeqEnum`
The sequence of vertices which arise as endpoints of lower faces.
##### `OuterVertices(N): NwtnPgon -> SeqEnum`
The sequence of vertices which arise as endpoints of outer faces.
##### `AllVertices(N): NwtnPgon -> SeqEnum`
The sequence of vertices of the compact convex hull of $P_N$.
##### `Example: Vertices of a Newton Polygon (ex-534640)`
This example illustrates the types of vertices that can be calculated. Note that the printing of these polygons, created from their defining points, changes as more information is calculated. This would occur in the same manner if faces were being calculated instead of vertices.
```magma
> InnerVertices(N2);
[ <0, 3>, <2, 0> ]
> N2;
Newton Polygon with vertices {(0, 3), (2, 0)} and defining points {(0, 3), (2,
0), (4, 1)}
> InnerVertices(N6);
[ <1, 4>, <3, 1> ]
> N6;
Newton Polygon with vertices {(1, 4), (3, 1)} and defining points {(1, 4), (1,
6), (2, 4), (2, 7), (3, 1), (4, 5), (4, 7), (5, 2), (5, 9), (6, 1), (6, 6), (7,
7), (7, 9), (8, 4), (8, 6), (8, 8)}
> Vertices(N2);
[ <0, 3>, <2, 0>, <4, 1> ]
> Vertices(N6);
[ <1, 4>, <3, 1>, <6, 1>, <8, 4>, <8, 8>, <7, 9>, <5, 9>, <2, 7>, <1, 6> ]
> AllVertices(N2);
[ <0, 3>, <2, 0>, <4, 1> ]
> N2;
Newton Polygon with vertices {(0, 3), (2, 0), (4, 1)} and defining points {(0,
3), (2, 0), (4, 1)}
> AllVertices(N6);
[ <1, 4>, <3, 1>, <6, 1>, <8, 4>, <8, 8>, <7, 9>, <5, 9>, <2, 7>, <1, 6> ]
> N6;
Newton Polygon with vertices {(1, 4), (3, 1), (6, 1), (8, 4), (8, 8), (7, 9),
(5, 9), (2, 7), (1, 6)} and defining points {(1, 4), (1, 6), (2, 4), (2, 7), (3,
1), (4, 5), (4, 7), (5, 2), (5, 9), (6, 1), (6, 6), (7, 7), (7, 9), (8, 4), (8,
6), (8, 8)}
```
Here `Vertices` has been defined to be `AllVertices`. All the known vertices of the polygon are printed when the polygon is printed. There is some overlap between the inner and outer vertices as is shown below. Every vertex is either an inner vertex or an outer vertex with some being both. Not all defining points are vertices.
```magma
> OuterVertices(N6);
[ <3, 1>, <6, 1>, <8, 4>, <8, 8>, <7, 9>, <5, 9>, <2, 7>, <1, 6>, <1, 4> ]
> OuterVertices(N2);
[ <2, 0>, <4, 1>, <0, 3> ]
```
##### `EndVertices(F): NwtnPgonFace -> SeqEnum`
A sequence containing the two end vertices of the face $F = \left< a,b,c \right>$.
##### `FacesContaining(N, p): NwtnPgon, Tup -> SeqEnum`
Those faces of the polygon $N$ returned by `Faces` on which the point $p = \langle a, b \rangle$ lies.
##### `Example: End Vertices and Containing Faces (ex-8ed2f7)`
Using some of the example polygons that have been created above, we illustrate the simple use of `EndVertices` and `FacesContaining`.
```magma
> AN := AllFaces(N);
> AN;
[ <4, 5, 4>, <0, 1, 0>, <-1, -4, -4>, <-11, -60, -48> ]
> A6 := AllFaces(N6);
> A6;
[ <3, 2, 11>, <0, 1, 1>, <-3, 2, -16>, <-1, 0, -8>, <-1, -1, -16>, <0, -1, -9>,
<2, -3, -17>, <1, -1, -5>, <1, 0, 1> ]
> AllVertices(N);
[ <0, 4/5>, <1, 0>, <4, 0>, <3, 1/4> ]
> AllVertices(N6);
[ <1, 4>, <3, 1>, <6, 1>, <8, 4>, <8, 8>, <7, 9>, <5, 9>, <2, 7>, <1, 6> ]
> EndVertices(AN[1]);
[ <0, 4/5>, <1, 0> ]
> EndVertices(AN[4]);
[ <0, 4/5>, <3, 1/4> ]
> EndVertices(A6[1]);
[ <1, 4>, <3, 1> ]
> EndVertices(A6[5]);
[ <7, 9>, <8, 8> ]
> EndVertices(A6[9]);
[ <1, 4>, <1, 6> ]
> FacesContaining(N, <1, 0>);
[ <4, 5, 4> ]
> FacesContaining(N6, <1, 0>);
[]
> FacesContaining(N6, <4, 1>);
[ <0, 1, 1> ]
> FacesContaining(N, <4, 1>);
[]
> FacesContaining(N6, <3, 1>);
[ <3, 2, 11>, <0, 1, 1> ]
```
##### `GradientVector(F): NwtnPgonFace -> Tup`
The $a$ and $b$ values of the line describing the face $F$ of the form $a*x + b*y = c$ where $a, b$ and $c$ are integers.
##### `GradientVectors(N): NwtnPgon -> [ Tup ]`
A sequence containing the gradient vectors of the faces of the newton polygon $N$.
##### `Weight(F): NwtnPgonFace -> RngIntElt`
The $c$ value of the line describing the face $F$ of the form $a*x + b*y = c$ where $a, b$ and $c$ are integers.
##### `Slopes(N): NwtnPgon -> SeqEnum`
The slopes of the faces of the newton polygon $N$.
##### `InnerSlopes(N): NwtnPgon -> SeqEnum`
##### `LowerSlopes(N): NwtnPgon -> SeqEnum`
##### `AllSlopes(N): NwtnPgon -> SeqEnum`
The slopes of the polygon $N$ corresponding of `InnerFaces`, `LowerFaces`, and `AllFaces` respectively.
##### `Example: Gradient Vector and Weight of a Face (ex-260949)`
In this example `GradientVector` and `Weight` can be seen to be access functions on the components of a face of a polygon.
```magma
> A := AllFaces(N);
> A;
[ <4, 5, 4>, <0, 1, 0>, <-1, -4, -4>, <-11, -60, -48> ]
> f := A[3];
> GradientVector(f);
<-1, -4>
> Weight(f);
-4
```
The gradient of the face can now be easily computed as shown.
```magma
> a := GradientVector(f)[1];
> b := GradientVector(f)[2];
> -a/b;
-1/4
```
#### Tests for Points and Faces
Once more, recall that $P_N$ denotes the finite set of points in the plane used to define the Newton polygon $N$. Whether or not a point is considered to lie in a polygon depends on what are considered to be its faces. Magma always uses the list of faces returned by `Faces(N)` when testing points. Of course, this is not always the case in applications. One must to perform other tests explicitly when there is doubt.
##### `IsFace(N, F): NwtnPgon, Tup -> BoolElt`
Return `true` if and only if the tuple $F = \langle a, b, c \rangle$ describes a line coinciding with a face of the polygon $N$ as returned by `Faces`.
##### `IsVertex(N, p): NwtnPgon, Tup -> BoolElt`
Return `true` if and only if the point $p = \left< a,b \right>$ of the rational plane (given as a tuple) is a vertex of the polygon $N$ as returned by `Vertices`.
##### `IsInterior(N, p): NwtnPgon, Tup -> BoolElt`
Return `true` if and only if the point $p = \left< a,b \right>$ given as a tuple lies strictly in the interior of the polygon $N$.
##### `IsBoundary(N, p): NwtnPgon, Tup -> BoolElt`
Return `true` if and only if the point $p = \left< a,b \right>$ given as a tuple lies on the boundary of the polygon $N$, that is, the point is contained in a face of $N$.
##### `IsPoint(N, p): NwtnPgon, Tup -> BoolElt`
Return `true` if and only if the point $p = \left< a,b \right>$ (given as a tuple) lies on the polygon $N$.
### Polynomials Associated with Newton Polygons
The polynomial used to define a polygon can be recovered, but more usefully so can those restrictions of that polynomial to parts of the polygon, the so-called face functions in particular.
Note that most of these functions will return an error if $N$ was not defined in terms of a polynomial.
#### `HasPolynomial(N): NwtnPgon -> BoolElt`
Return `true` if and only if the polygon $N$ was defined as the Newton polygon of some polynomial.
#### `Polynomial(N): NwtnPgon -> RngElt`
The polynomial used to define the polygon $N$.
#### `ParentRing(N): NwtnPgon -> Rng`
The parent ring of the polynomial of the polygon $N$.
#### `IsNewtonPolygonOf(N, f): NwtnPgon, RngElt -> BoolElt`
Return whether the newton polygon $N$ is defined by the polynomial $f$.
#### `FaceFunction(F): NwtnPgonFace -> RngElt`
If the polygon $N$ is defined by a polynomial in two variables $f$ this returns those monomial terms of $f$ whose corresponding Newton points lie on the face $F$. On the other hand, if $N$ is determined by a univariate polynomial over a series ring, this returns the univariate polynomial supported on the face $F$.
#### `IsDegenerate(F): NwtnPgonFace -> BoolElt`
Return `true` if the face function along $F$ is not squarefree.
#### `IsDegenerate(N): NwtnPgon -> BoolElt`
Return `true` if a face function on some face of $N$ is degenerate.
#### `IsNondegenerate(F): NwtnPgonFace -> BoolElt`
Return `false` if the face function along $F$ is not squarefree.
#### `IsNondegenerate(N): NwtnPgon -> BoolElt`
Return `false` if a face function on some face of $N$ is degenerate.
### Finding Valuations of Roots of Polynomials from Newton Polygons
Newton polygons can be used to find the valuations of roots of the polynomial from which the polygon was created at the prime used in the creation (given implicitly or explicitly). The following functions use Newton polygons to calculate the valuations of the roots of the polynomial paired with the number of roots with that valuation.
#### `ValuationsOfRoots(f): RngUPolElt -> [ < RngIntElt, RngIntElt > ]`
The valuations of the roots of $f$, where $f$ is a polynomial over a local ring or a series ring.
#### `ValuationsOfRoots(f, p): RngUPolElt, RngIntElt -> [ < RngIntElt, RngIntElt > ]`
#### `ValuationsOfRoots(f, p): RngUPolElt, RngOrdIdl -> [ < RngIntElt, RngIntElt > ]`
#### `ValuationsOfRoots(f, p): RngUPolElt, PlcFunElt -> [ < RngIntElt, RngIntElt > ]`
The valuations of the roots of $f$ with respect to $p$ where $p$ may be either a prime integer, a prime ideal of a number field or a place of a function field.
### Using Newton Polygons to Find Roots of Polynomials over Series Rings
The operations described in this section are relevant for polynomials over series rings. There are two main algorithms involved.
#### `SetVerbose("Newton", v): MonStgElt, RngIntElt`
Set the verbose printing to level $v$ for `PuiseuxExpansion`, `ExpandToPrecision`, `DuvalPuiseuxExpansion`, `Roots`, and `ImplicitFunction`. A level of $1$ will mean that any partial solutions that could not be expanded to the precision requested will be printed before an error is returned except for `Roots`. The polynomials used in forming extensions will also be printed before the extension is computed. In `Roots`, the algorithm used to compute the expansions will be printed. When Walker’s algorithm is being used the current value of the denominator will be printed. For `ImplicitFunction` a warning about a potentially bad value of $d$ will be printed if the value of $d$ given is not divisible by the exponent denominator of some coefficient of $f$. A level of $2$ will print the last polynomials calculated during the newton polygon part of `PuiseuxExpansion` and `DuvalPuiseuxExpansion` and some evaluated polynomials during `ImplicitFunction`.
#### Operations not associated with Duval’s Algorithm
##### `PuiseuxExpansion(f, n): RngUPolElt, RngIntElt -> SeqEnum[RngSerPuisElt]`
```magma
PreciseRoot : BoolElt Default: false
TestSquarefree: BoolElt Default: true
NoExtensions : BoolElt Default: false
LowerFaces : BoolElt Default: true
OneRoot : BoolElt Default: false
Newton : Verbose Default: 2
```
This function implements the algorithm described in [[Wal78](https://docs.magma-maths.org/references.md#cite-wa78)].
Return a sequence of partial expansions of the roots of the polynomial $f$ over a series ring as puiseux series. The roots are returned with relative precision at least $n/d$ where $d$ is the least common multiple of exponent denominator for the series expansion and the exponent denominators of the coefficients of the $f$. An input of $n = 0$ will return the expansions calculated by the newton polygon part of the algorithm and these will be to the precision of what is known. The coefficient ring of the series ring containing the coefficients of $f$ must always be a field and unless extensions are not required it must be able to be extended.
If the coefficient ring of the series ring is a finite field whose characteristic is less than or equal to the degree of the polynomial then the denominators computed in the newton polygon part of the algorithm may not be bounded and the function will return an error. However, it is possible for some polynomials that the denominators will be bounded. This is stated by [[Gri95](https://docs.magma-maths.org/references.md#cite-gr95)], pg 269 – 272.
Care needs to be taken with polynomials whose coefficients have low precision. The algorithm must extract from $f$ the squarefree part and in doing so lose even more precision. The result is that the algorithm may not have enough precision to calculate the expansions correctly. A solution is to set `TestSquarefree` to `false` if the polynomial is known to have no multiple roots. However this will not solve all precision problems and the answer is only as good as the precision allows it to be.
If `PreciseRoot` is set to `true` then the partial expansions to be returned are checked and if any are exact roots of $f$ they are returned with full precision. If `NoExtensions` is set to `true` then expansions are found within the puiseux series ring only. By default, the coefficient ring of the series ring is extended to find all the partial expansions. If `LowerFaces` is set to `false` then expansions with negative valuations will not be found. If `OneRoot` is set to true then representatives of conjugate roots only will be found instead of each of the roots individually.
Note that it may useful to define the polynomial over an algebraically closed field (via [`AlgebraicClosure`](https://docs.magma-maths.org/GlobalFields/AlgebraicallyClosedFields/structure.md#function-fldac-algebraicclosure)), so that all roots may be found.
##### `ExpandToPrecision(f, c, n): RngUPolElt, RngSerElt, RngIntElt -> RngSerElt`
```magma
PreciseRoot : BoolElt Default: false
TestSquarefree: BoolElt Default: true
Newton : Verbose Default: 2
```
Given a polynomial $f$ over a Puiseux series ring and a partial root $c$ of that polynomial (found by `PuiseuxExpansion` for example) continue to expand that root until it has relative precision $n/d$ where $d$ is the least common multiple of the exponent denominator of $c$ and the exponent denominators of the coefficients of $f$. If $c$ is given to greater precision (or length greater than $n$ if its precision is infinite), the relative precision of $c$ is reduced to $n/d$. An error results if $c$ is not a partial expansion to precision $n/d$. If `PreciseRoot` is true then the partial expansion to be returned is checked and if it is an exact root of $f$ it is returned with full precision. All input is checked for being an exact root regardless. If `TestSquarefree` is `false` the polynomial will not be made squarefree. This may avoid some loss of precision but may result in some unique partial roots not being recognized as unique partial roots and as such they cannot be expanded.
An error may result if $c$ is a partial root of $f$ but the exponent denominator of the full expansion is greater than that of $c$. Therefore for $c$ to be expanded it must have the same denominator as the expansion it is part of. This will rarely be an issue for those partial expansions resulting from `PusieuxExpansion` which did not encounter problems with precision in the newton polygon part since the algorithm for this will find at least as much of the expansion as necessary to compute the exponent denominator.
##### `ImplicitFunction(f, d, n): RngUPolElt, RngIntElt, RngIntElt -> RngSerElt`
```magma
Newton: Verbose Default: 2
```
Return a root of the polynomial $f$ over a series ring. The input $d$ is the denominator (or a multiple of) the exponent denominator of the root. The root is given to absolute precision $n/d$. The evaluation of $f$ at zero (polynomial) evaluated at zero (series) must be zero but that of its derivative must be nonzero.
##### `Example: Puiseux Expansions to Higher Precision (ex-d1b398)`
This example illustrates the joint use of `PuiseuxExpansion` and `ExpandToPrecision` which can be used together to gain and improve partial roots of a polynomial. The use of `ExpandToPrecision` following `PuiseuxExpansion` avoids the recalculation of information already known.
```magma
> P := PuiseuxSeriesRing(Rationals());
> R := PolynomialRing(P);
> f := y^3 + 2*x^-1*y^2 + 1*x^-2*y + 2*x;
> c := PuiseuxExpansion(f, 0);
> A := Parent(c[1]);
> N := CoefficientRing(A);
> Q := PolynomialRing(A);
> c;
[
-2*a^3 + O(a^4),
-a^-1 + n*a + O(a^2),
-a^-1 - n*a + O(a^2)
]
> [ExpandToPrecision(f, c[i], 10) : i in [1 .. #c]];
[
-2*a^3 - 8*a^7 - 56*a^11 + O(a^13),
-a^-1 + n*a + a^3 + 5/4*n*a^5 + 4*a^7 + O(a^9),
-a^-1 - n*a + a^3 - 5/4*n*a^5 + 4*a^7 + O(a^9)
]
```
The same results could have been gained using `PuiseuxExpansion` with the required precision in the first place.
```magma
> c := PuiseuxExpansion(f, 10);
> A := Parent(c[1]);
> N := CoefficientRing(A);
> c;
[
-2*a^3 - 8*a^7 - 56*a^11 + O(a^13),
-a^-1 + n*a + a^3 + 5/4*n*a^5 + 4*a^7 + O(a^9),
-a^-1 - n*a + a^3 - 5/4*n*a^5 + 4*a^7 + O(a^9)
]
```
However, asking for more precision requires time so that if it is not necessary the extra calculation can be avoided and if more precision happens to be required then it can be gained without recalculation. `ExpandToPrecision` is also called on only one root so that if only one expansion is required using `PusieuxExpansion` and then `ExpandToPrecision` will not calculate any unnecessary information.
```magma
> time c := PuiseuxExpansion(f, 100);
Time: 2.810
> time c := PuiseuxExpansion(f, 10);
Time: 0.060
> A := Parent(c[1]);
> N := CoefficientRing(A);
> time ExpandToPrecision(f, c[1], 100);
-2*a^3 - 8*a^7 - 56*a^11 - 480*a^15 - 4576*a^19 - 46592*a^23 -
496128*a^27 - 5457408*a^31 - 61529600*a^35 - 707266560*a^39 -
8257566720*a^43 - 97654702080*a^47 - 1167349284864*a^51 -
14082308833280*a^55 - 171221451538432*a^59 -
2096081963188224*a^63 - 25814314231136256*a^67 -
319605795242639360*a^71 - 3975750610806374400*a^75 -
49666299938073477120*a^79 - 622818862289639178240*a^83 -
7837247078959687925760*a^87 - 98931046460491133091840*a^91 -
1252424949872174982758400*a^95 - 15897106567806080658702336*a^99
+ O(a^103)
Time: 0.410
```
##### `IsPartialRoot(f, c): RngUPolElt, RngSerElt -> BoolElt`
Return `true` if the series $c$ can be expanded to at least one root of the polynomial $f$.
##### `IsUniquePartialRoot(f, c): RngUPolElt, RngSerElt -> BoolElt`
```magma
TestSquarefree: BoolElt Default: true
```
Return `true` if the series $c$ can be expanded to exactly one distinct root of the polynomial $f$. By default $f$ will have multiple factors removed to allow partial expansions of multiple roots to be recognized as being unique. If `TestSquarefree` is set to `false` then $f$ will be taken as given which may avoid errors due to lost precision but may not pick partial expansions of multiple roots as being unique and as such is best used when $f$ is squarefree or the expansion is known to be of a single root.
##### `Example: Checking That a Partial Root Can Be Expanded (ex-5113cd)`
The above $2$ functions can be used to reduce the occurrence of errors from `ExpandToPrecision` by checking that the input can be expanded. Errors resulting from a lack of precision which means that the expansion cannot be calculated to the requested precision are the only errors that cannot be removed. Only unique partial roots can be expanded. If a partial root is not unique then calling `PuiseuxExpansion` will provide several further partial expansions of the partial root that will themselves be unique and so can be used to calculate several expansions of the original.
```magma
> P := PuiseuxSeriesRing(Rationals());
> R := PolynomialRing(P);
> f := (y^2 - x^3)^2 - y*x^6;
> IsPartialRoot(f, x^(3/2));
true
> ExpandToPrecision(f, x^(3/2), 10);
>> ExpandToPrecision(f, x^(3/2), 10);
^
Runtime error in 'ExpandToPrecision': Element is not a unique partial
root of the polynomial
> IsUniquePartialRoot(f, x^(3/2));
false
> c := PuiseuxExpansion(f, 0);
> A := Parent(c[1]);
> N := CoefficientRing(A);
> Q := PolynomialRing(A);
> c;
[
a^(3/2) + 1/2*a^(9/4) + O(a^(5/2)),
a^(3/2) - 1/2*a^(9/4) + O(a^(5/2)),
-a^(3/2) + 1/2*n*a^(9/4) + O(a^(5/2)),
-a^(3/2) - 1/2*n*a^(9/4) + O(a^(5/2))
]
> IsUniquePartialRoot(f, x^(3/2) + 1/2*x^(9/4));
true
> ExpandToPrecision(f, x^(3/2) + 1/2*x^(9/4), 10);
x^(3/2) + 1/2*x^(9/4) - 1/64*x^(15/4) + O(x^4)
> ExpandToPrecision(f, x^(3/2) + x^2, 30);
>> ExpandToPrecision(f, x^(3/2) + x^2, 30);
^
Runtime error in 'ExpandToPrecision': Element is not a partial root of
the polynomial
> IsPartialRoot(f, x^(3/2) + x^2);
false
```
So if `IsPartialRoot` returns `false` then no expansion can be made. If `IsUniquePartialRoot` returns `false` (but `IsPartialRoot` returns `true`) then several expansions can be made after calling `PuiseuxExpansion`.
##### `PuiseuxExponents(p): RngSerElt -> SeqEnum`
Given a series expansion return the sequence of exponents $[a/b]$ of the non zero terms of the series $p$ up to and including the first one where $b$ is the global denominator for the series.
##### `PuiseuxExponentsCommon(p, q): RngSerElt, RngSerElt -> SeqEnum`
Given two series return the sequence of exponents $[a/b]$ of the non zero initial terms of the series $p$ and $q$ which are equal up to but not including the first unequal terms.
##### `Example: Exponents of Puiseux Expansions (ex-cc0585)`
This example illustrates how `PuiseuxExponents` and `PuiseuxExponentsCommon` can be used on output from `PusieuxExpansion`. (Similar can be done with related functions and general series).
```magma
> P := PuiseuxSeriesRing(FiniteField(5, 3));
> R := PolynomialRing(P);
> f := (1+x)*y^4 - x^(-1/3)*y^2 + y + x^(1/2);
> time c := PuiseuxExpansion(f, 5);
Time: 0.030
> c;
[
4*x^(1/2) + x^(2/3) + 3*x^(5/6) + x^(7/6) + O(x^(4/3)),
x^(1/3) + x^(1/2) + 4*x^(2/3) + 2*x^(5/6) + O(x^(7/6)),
4*x^(-1/6) + 2*x^(1/3) + O(x^(2/3)),
x^(-1/6) + 2*x^(1/3) + O(x^(2/3))
]
> PuiseuxExponents(c[1]);
[ 1/2, 2/3, 5/6 ]
> PuiseuxExponents(c[3]);
[ -1/6 ]
> P := PuiseuxSeriesRing(FiniteField(5, 3));
> R := PolynomialRing(P);
> f := ((y^2 - x^3)^2 - y*x^6)^2 - y*x^15;
> c := PuiseuxExpansion(f, 0);
> A := Parent(c[1]);
> N