README

README.md

@@ -133,27 +133,69 @@ putStrLn $ prettyNumSpray $ derivative 1 spray
 As of version 2.0.0, it is possible to compute a Gröbner basis of the ideal 
 generated by a list of spray polynomials.
 
+One of the numerous applications of Gröbner bases is the *implicitization* 
+of parametric surfaces. That means that they allow to get an implicit equation
+of a surface defined by parametric equations. Let us give an example of this 
+application for an *Enneper surface*. Here are the parametric equations of this
+surface:
+
 ```haskell
 import Math.Algebra.Hspray
-import Data.Ratio
--- define the elementary monomials
-o = lone 0 :: Spray Rational -- same as unitSpray
-x = lone 1 :: Spray Rational
-y = lone 2 :: Spray Rational
-z = lone 3 :: Spray Rational
--- define three polynomials
-p1 = x^**^2 ^+^ y ^+^ z ^-^ o -- X² + Y + Z - 1
-p2 = x ^+^ y^**^2 ^+^ z ^-^ o -- X + Y² + Z - 1
-p3 = x ^+^ y ^+^ z^**^2 ^-^ o -- X + Y + Z² - 1
--- compute the reduced Gröbner basis
-gbasis = groebner [p1, p2, p3] True
--- show result
-prettyResult = map prettyQSpray gbasis
-mapM_ print prettyResult
--- "x + y + z^2 - 1"
--- "y^2 - y - z^2 + z"
--- "y.z^2 + (1/2)*z^4 - (1/2)*z^2"
--- "z^6 - 4*z^4 + 4*z^3 - z^2"
+import Data.Ratio ( (%) )
+u = qlone 1
+v = qlone 2
+x = 3*^u ^+^ 3*^(u ^*^ v^**^2) ^-^ u^**^3
+y = 3*^v ^+^ 3*^(u^**^2 ^*^ v) ^-^ v^**^3
+z = 3*^u^**^2 ^-^ 3*^v^**^2
+```
+
+The first step of the implicitization is to compute a Gröbner basis of the 
+following list of polynomials:
+
+```haskell
+generators = [x ^-^ qlone 3, y ^-^ qlone 4, z ^-^ qlone 5]
+```
+
+Once the Gröbner basis is obtained, one has to identify which of its elements 
+do not involve the first two variables (`u` and `v`):
+
+```haskell
+gbasis = groebnerBasis generators True
+isFreeOfUV :: QSpray -> Bool
+isFreeOfUV p = not (involvesVariable p 1) && not (involvesVariable p 2)
+freeOfUV = filter isFreeOfUV gbasis
+```
+
+Then the implicit equations (there can be several ones) are obtained by 
+removing the first two variables from these elements:
+
+```haskell
+results = map (dropVariables 2) freeOfUV 
+```
+
+Here we find only one implicit equation (i.e. `length results` is `1`). 
+We only partially display it because it is long:
+
+```haskell
+implicitEquation = results !! 0
+putStrLn $ prettyQSpray implicitEquation
+-- x^6 - 3*x^4.y^2 + (5/9)*x^4.z^3 + 6*x^4.z^2 - 3*x^4.z + 3*x^2.y^4 + ...
+```
+
+Let us check it is correct. We take a point on the Enneper surface, for 
+example the point corresponding to $u=1/4$ and $v=2/3$ ($u$ and $v$ range 
+from $0$ to $1$):
+
+```haskell
+xyz = map (evaluateAt [1%4, 2%3]) [x, y, z]
+```
+
+If the implicitization is correct, then the polynomial `implicitEquation` 
+should be zero at any point on the Enneper surface. This is true for our point:
+
+```haskell
+evaluateAt xyz implicitEquation == 0
+-- True
 ```
 
 

scripts/groebner-Enneper.hs

@@ -7,10 +7,10 @@ x = 3*^u ^+^ 3*^(u ^*^ v^**^2) ^-^ u^**^3
 y = 3*^v ^+^ 3*^(u^**^2 ^*^ v) ^-^ v^**^3
 z = 3*^u^**^2 ^-^ 3*^v^**^2
 generators = [x ^-^ qlone 3, y ^-^ qlone 4, z ^-^ qlone 5]
-gb = groebnerBasis generators True
+gbasis = groebnerBasis generators True
 isfree :: QSpray -> Bool
 isfree spray = not (involvesVariable spray 1) && not (involvesVariable spray 2)
-results = filter isfree gb
+results = filter isfree gbasis
 results' = map (dropVariables 2) results 
 showResults = map prettyQSpray results'