Improving documentation

README.md

@@ -1,57 +1,145 @@
 # Hodge diamond cutter
 
-A collection of Python classes and functions to deal with Hodge diamonds (and Hochschild homology) of smooth projective varieties, together with many constructions.
+A collection of Python classes and functions in Sage to deal with Hodge diamonds (and Hochschild homology) of smooth projective varieties, together with many constructions.
+
 
 ## Getting started
 
-It suffices to load ``diamond.sage`` in Sage to get started. It was written using Sage 8.3, but presumably it works without modification in more recent and not too old versions, as nothing fancy is used.
+It suffices to load ``diamond.sage`` in Sage to get started.
 
-## Examples
 
-1. As a first example, let us consider the cubic fourfold. There is an intricate connection to K3 surfaces. To see the Hodge diamond of a K3 surface, it suffices to do
+# Functionality
+
+## Varieties and constructions
+
+Below is the list of currently implemented constructions. See their respective documentation if their usage is not clear. They are roughly grouped into themes.
+```
+zero
+point
+lefschetz
+Pn(n)
+
+curve(genus)
+symmetric_power(n, genus)
+jacobian(genus)
+abelian(dimension)
+moduli_vector_bundles(rank, degree, genus)
+quot_scheme_curve(genus, length, rank)
+
+fano_variety_intersection_quadrics(g, i)
+fano_variety_lines_cubic(n)
+
+hilbtwo(X)
+hilbthree(X)
 
-   ```
-   print K3
-   ```
+generalisedkummer(n)
+ogrady6
+ogrady10
 
-   because K3 surfaces are hardcoded (well, all of them have the same Hodge diamond, which is just that of a quartic surface), which is
+surface(genus, irregularity, h11)
+hilbn(surface, n)
+nestedhilbn(surface, n)
 
-   ```
-             1
-         0        0
-     1       20       1
-         0        0
-             1
-   ```
+complete_intersection(degrees, dimension)
+hypersurface(degree, dimension)
 
-   Now for the cubic fourfold we do
+weighted_hypersurface(degree, weights)
+cyclic_cover(ramification, cover, weights)
 
-   ```
-   print complete_intersection(3, 4)
-   ```
+partial_flag_variety(D, I)
+grassmannian(k, n)
+orthogonal_grassmannian(k, n)
+symplectic_grassmannian(k, n)
 
-   which gives
+gushel_mukai(n)
+```
 
-   ```
-                     1
-                 0        0
-             0       1        0
-         0       0        0       0
-     0       1       21       1       0
-         0       0        0       0
-             0       1        0
-                 0        0
-                     1
-   ```
 
-   Removing the primitive part of the cohomology gives you back the Hodge diamond of a K3 surface, and this is the first glimpse at a very interesting story relating the two.
+## The library
+Of course, Hodge diamonds are little more than collections of numbers. But to make manipulating them easy, there is a convenient `HodgeDiamond` class which has many convenient methods, so that manipulating them becomes easy. Describing the whole interface is a bit tedious, let me just give the ones which are not obvious operations.
+
+The `HodgeDiamond` class:
+```
+HodgeDiamond.betti()
+HodgeDiamond.middle()
+HodgeDiamond.euler
+HodgeDiamond.hirzebruch
+HodgeDiamond.homological_unit()
+HodgeDiamond.hochschild()
+
+HodgeDiamond.level()
+
+HodgeDiamond.blowup(other, codim)
+HodgeDiamond.bundle(rank)
+```
+
+The `HochschildHomology` class:
+```
+HochschildHomology.symmetric_power(k)
+```
+
+
+## Examples
 
-2. As a second example, let us discuss a conjectural semiorthogonal decomposition for the moduli space of rank 2 bundles with fixed determinant of degree 1 on a curve $C$ of genus $g$. As observed by [Kyoung-Seog Lee](https://arxiv.org/abs/1806.11101) and [myself](https://www.mfo.de/document/1822/preliminary_OWR_2018_24.pdf) the Hodge diamond of this variety can be decomposed in terms of symmetric powers of the curve $C$, which can be checked as follows
+As an example of why it is interesting to consider Hodge diamonds and , let us consider the cubic fourfold. There is an intricate connection to K3 surfaces. Let us try and see this well-known connection.
+
+To see the Hodge diamond of a K3 surface, it suffices to do
+
+```
+print(K3)
+```
+
+because K3 surfaces are hardcoded (well, all of them have the same Hodge diamond, which is just that of a quartic surface), which is
+
+```
+          1
+      0        0
+  1       20       1
+      0        0
+          1
+```
+
+Now for the cubic fourfold we do
+
+```
+print(hypersurface(3, 4))
+```
+
+which gives
+
+```
+                  1
+              0        0
+          0       1        0
+      0       0        0       0
+  0       1       21       1       0
+      0       0        0       0
+          0       1        0
+              0        0
+                  1
+```
+
+Removing the primitive part of the middle cohomology gives you back the Hodge diamond of a K3 surface, and this is the first glimpse at a very interesting story relating the two.
+
+```
+print(hypersurface(3, 4) - K3(1))
+```
+
+gives
+
+```
+                  1
+              0       0
+          0       0       0
+      0       0       0       0
+  0       0       1       0       0
+      0       0       0       0
+          0       0       0
+              0       0
+                  1
+```
+suggesting that there is a "boring" and an "interesting" part of the cohomology of a cubic fourfold.
 
-   ```
-   for g in range(2, 10):
-     assert moduli_vector_bundles(2, 1, g) == sum([symmetric_power(i, g)(i) for i in range(g)]) + sum([symmetric_power(i, g)(3*g - 3 - 2*i) for i in range(g - 1)])
-   ```
 
 ## Contributing
 

diamond.sage

@@ -612,25 +612,29 @@ def Pn(n):
     return HodgeDiamond.from_matrix(matrix.identity(n + 1), from_variety=True)
 
 
-def curve(g):
+def curve(genus):
     """
-    Hodge diamond for a curve of genus ``g``
+    Hodge diamond for a curve of a given genus.
     """
+    g = genus
     return HodgeDiamond.from_matrix(matrix([[1, g], [g, 1]]), from_variety=True)
 
 
 
-def surface(pg, q, h11):
+def surface(genus, irregularity, h11):
     """
-    Hodge diamond for a surface with geometric genus ``pg``, irregularity ``q`` and middle Hodge numbers ``h11``
+    Hodge diamond for a surface with given geometric genus, irregularity and
+    middle Hodge numbers ``h11``
     """
+    pg = genus
+    q = irregularity
     return HodgeDiamond.from_matrix(matrix([[1, q, pg], [q, h11, q], [pg, q, 1]]), from_variety=True)
 
 
 
-def symmetric_power(n, g):
+def symmetric_power(n, genus):
     """
-    Hodge diamond for the ``n``th symmetric power of a genus ``g`` curve
+    Hodge diamond for the ``n``th symmetric power of a curve of given genus
 
     For the proof, see example 1.1(1) of [MR2777820]. An earlier reference, probably in Macdonald, should exist.
 
@@ -651,37 +655,38 @@ def symmetric_power(n, g):
         return zero
 
     M = matrix(n + 1)
-    for (i,j) in cartesian_product([range(n+1), range(n+1)]):
-        M[i,j] = hpq(g, n, i, j)
+    for (i, j) in cartesian_product([range(n + 1), range(n + 1)]):
+        M[i, j] = hpq(genus, n, i, j)
 
     return HodgeDiamond.from_matrix(M, from_variety=True)
 
 
-def jacobian(g):
+def jacobian(genus):
     """
     Hodge diamond for the Jacobian of a genus $g$ curve
 
     This description is standard, and follows from the fact that the cohomology is the exterior power of the H^1, as graded bialgebras. See e.g. proposition 7.27 in the Edixhoven--van der Geer--Moonen book in progress on abelian varieties.
     """
-    M = matrix(g + 1)
-    for (i,j) in cartesian_product([range(g+1), range(g+1)]):
-        M[i,j] = binomial(g, i) * binomial(g, j)
+    M = matrix(genus + 1)
+    for (i, j) in cartesian_product([range(g+1), range(g+1)]):
+        M[i, j] = binomial(g, i) * binomial(g, j)
 
     return HodgeDiamond.from_matrix(M, from_variety=True)
 
 
-def abelian(g):
+def abelian(dimension):
     """
-    Hodge diamond for an abelian variety of dimension $g$
+    Hodge diamond for an abelian variety of a given dimension.
 
     This is just an alias for ``jacobian(g)``.
     """
-    return jacobian(g, from_variety=True)
+    return jacobian(dimension)
 
 
-def moduli_vector_bundles(r, d, g):
+def moduli_vector_bundles(rank, degree, genus):
     """
-    Hodge diamond for the moduli space of vector bundles of rank ``r`` and fixed determinant of degree ``d`` on a curve of genus ``g``
+    Hodge diamond for the moduli space of vector bundles of given rank and
+    fixed determinant of given degree on a curve of a given genus.
 
     For the proof, see corollary 5.1 of [MR1817504].
 
@@ -692,6 +697,10 @@ def moduli_vector_bundles(r, d, g):
             sage: jacobian(g) * moduli_vector_bundles(r, d, g)
 
     """
+    r = rank
+    d = degree
+    g = genus
+
     assert g >= 2, "genus needs to be at least 2"
     assert gcd(r, d) == 1, "rank and degree need to be coprime"
 
@@ -757,11 +766,13 @@ def fano_variety_intersection_quadrics(g, i):
     return HodgeDiamond.from_polynomial(polynomial)
 
 
-def quot_scheme_curve(g, n, r):
+def quot_scheme_curve(genus, length, rank):
     """
-    Hodge diamond for the Quot scheme of zero-dimensional quotients of length ``r`` of a vector bundle of rank ``r`` on a curve of genus ``g``
+    Hodge diamond for the Quot scheme of zero-dimensional quotients of given
+    length of a vector bundle of given rank on a curve of given genus.
 
-    For the proof, see proposition 4.5 of [1907.00826] (or rather, the reference [Bif89] in there)
+    For the proof, see proposition 4.5 of [1907.00826] (or rather, the
+    reference [Bif89] in there)
 
     * [1907.00826] Bagnarol--Fantechi--Perroni, On the motive of zero-dimensional Quot schemes on a curve
     """
@@ -874,7 +885,7 @@ ogrady10 = HodgeDiamond.from_matrix(
         [1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1]], from_variety=True)
 
 
-def hilbn(S, n):
+def hilbn(surface, n):
     """
     Hodge diamond for Hilbert scheme of ``n`` points on a smooth projective surface ``S``
 
@@ -888,16 +899,16 @@ def hilbn(S, n):
 
     - ``n`` -- number of points
     """
-    assert S.arises_from_variety()
-    assert S.dimension() == 2
+    assert surface.arises_from_variety()
+    assert surface.dimension() == 2
 
     R.<a, b, t> = PowerSeriesRing(ZZ, default_prec = (3*n + 1))
     series = R(1)
 
     # theorem 2.3.14 of Göttsche's book
     for k in range(1, n+1):
         for (p,q) in cartesian_product([range(3), range(3)]):
-            series = series * (1 + (-1)**(p+q+1) * a**(p+k-1) * b**(q+k-1) * t**k)**((-1)**(p+q+1) * S[p,q])
+            series = series * (1 + (-1)**(p+q+1) * a**(p+k-1) * b**(q+k-1) * t**k)**((-1)**(p+q+1) * surface[p,q])
 
     # read off Hodge diamond from the (truncated) series
     M = matrix([[0 for _ in range(2*n + 1)] for _ in range(2*n + 1)])
@@ -909,14 +920,14 @@ def hilbn(S, n):
     return HodgeDiamond.from_matrix(M, from_variety=True)
 
 
-def nestedhilbn(S, n):
+def nestedhilbn(surface, n):
     """
     Hodge diamond for the nested Hilbert scheme ``S^[n-1,n]`` of a smooth projective surface ``S``
 
     This is a smooth projective variety of dimension 2n.
     """
-    assert S.arises_from_variety()
-    assert S.dimension() == 2
+    assert surface.arises_from_variety()
+    assert surface.dimension() == 2
 
     R.<x, y, t> = PowerSeriesRing(ZZ, default_prec = (5*n + 1)) # TODO lower this?
 
@@ -928,7 +939,7 @@ def nestedhilbn(S, n):
             else:
                 series = series * (1 - x**(p+k-1) * y^(q+k-1) * t^k)^(-S[p, q])
 
-    series = series * R(S.polynomial) * t / (1 - x*y*t)
+    series = series * R(surface.polynomial) * t / (1 - x*y*t)
 
     # read off Hodge diamond from the (truncated) series
     M = matrix(2*n + 1)
@@ -1051,9 +1062,9 @@ def cyclic_cover(ramification_degree, cover_degree, weights):
     if type(weights) == sage.rings.integer.Integer:
         weights = [1]*(weights + 1)
 
-    weights.append(ramification_degree // cover_degree)
+    weights.append(ramification // cover)
 
-    return weighted_hypersurface(ramification_degree, weights)
+    return weighted_hypersurface(ramification, weights)
 
 
 def partial_flag_variety(D, I):