Refactor and document operators and periods in sage module

sage/operators.sage

@@ -1,3 +1,24 @@
+"""
+Picard-Fuchs operators and ideals in the logarithmic derivatives theta_i = z_i * d/dz_i.
+
+Contents
+--------
+PFOperator
+    __init__                      Construct from a string in z- and theta-variables
+    simplify                      Group by z-monomials and factorise theta-polynomials
+    change_coordinates            Rewrite the operator in new coordinates
+    _operator_from_string         Parse a string into the operator polynomial
+
+PFOperatorAnsatz(PFOperator)
+    __init__                      Ansatz of given theta- and z-multi-degrees
+
+PFIdeal
+    __init__                      Construct from a list of PFOperators
+    add_operator                  Append a PFOperator
+    remove_operator               Remove a PFOperator
+    change_coordinates            Rewrite all operators in new coordinates
+    find_power_series_solution    Power series solutions at given indicials/order
+"""
 import copy
 import logging
 from sage.all import sage_eval, PolynomialRing, QQ, SR, function, prod, solve, var

sage/periods.sage

@@ -1,3 +1,23 @@
+"""
+Periods of Calabi-Yau manifolds as formal power series in z-variables and their logs.
+
+Contents
+--------
+Period
+    __init__                      Construct from a string or a coefficients dictionary
+    from_l_vectors (classmethod)  Holomorphic period from GLSM/Mori charge vectors
+    apply_operator                Apply a PFOperator, truncated to self.order
+    find_annihilating_operators   Find PFOperator Ansätze annihilating this period
+    _initialise_ring              Polynomial ring in z- and log-variables
+    _period_from_string           Parse a string into a coefficients dictionary
+    _period_to_string             Render the coefficients as a string
+    _max_z_degree                 Highest total z-degree among the coefficients
+    _truncate_coefficients        Drop terms above a given total z-degree
+    _apply_theta                  Apply theta_i = z_i * d/dz_i to a coefficients dictionary
+
+PeriodAnsatz(Period)
+    __init__                      Ansatz of given z- and log-multi-degrees
+"""
 import logging
 from sage.all import sage_eval, PolynomialRing, QQ, SR, ceil, factorial, floor, log, matrix, prod, var
 
@@ -244,24 +264,8 @@ class Period:
         hypergeometric-type sum
 
             varpi_0(z) = sum_{a in Z_{>=0}^m}
-                (prod_j Gamma(1 - l_num^(j).a)) / (prod_i Gamma(1 + l_den^(i).a)) * z^a,
-
-        see e.g. Hosono-Klemm-Theisen-Yau. l_vectors is a list of the m charge vectors, each
-        given as [numerator part, denominator part]: the components landing in the numerator
-        resp. denominator Gamma-functions (for a Calabi-Yau hypersurface/CICY, these are the
-        nef-partition weight(s) resp. the toric divisor charges). For m = 1 the outer list may
-        be dropped, e.g. the quintic is given by [[-5], [1, 1, 1, 1, 1]], while P^4_{1,1,2,2,6}[12]
-        is given by [[[-6], [3, 2, 1, 0, 0, 0]], [[0], [0, 0, -3, 1, 1, 1]]].
-
-        For a Calabi-Yau charge vector the numerator Gamma-functions never hit a pole, since
-        their argument only grows as a grows; only the denominator factors can vanish - at a
-        non-positive-integer argument - which is exactly what truncates each a_k to a finite
-        range once the others are fixed. This makes summing directly over that range far
-        cheaper than solving the full Picard-Fuchs system term by term.
-        """
-        # A single charge vector [numerator part, denominator part] has integer entries in its parts.
-        if l_vectors and l_vectors[0] and not isinstance(l_vectors[0][0], (list, tuple)):
-            l_vectors = [l_vectors]
+                (prod_j Gamma(1 - l_num^(j).a)) / (prod_i Gamma(1 + l_den^(i).a)) * z^a.
+       """
         if any(len(l_vector) != 2 for l_vector in l_vectors):
             raise ValueError("Each charge vector must be given as [numerator part, denominator part].")
         m = len(l_vectors)

sage/toric_topdata.sage

@@ -1,3 +1,48 @@
+"""
+Topological data of Calabi-Yau hypersurfaces and CICYs in toric ambient spaces.
+
+Contents
+--------
+Polytope
+    __init__                             Construct from a list of defining points
+    _validate_points_and_get_dimension   Check the points and return their dimension
+    _points_to_polytope                  Lattice points of the convex hull, minus codim-1 interiors
+
+ToricPolytope(Polytope)
+    __init__                             Construct with triangulation, nef partition and Mori cone
+    set_triangulation                    Select a fine star triangulation by index
+    set_nef_partition                    Set and validate the nef partition
+    set_Mori_cone                        Set the Mori cone (default or from given l-vectors)
+    disc                                 A-discriminant (singular loci in Batyrev coordinates)
+    topdata                              Compute topological data and write it to JSON
+    _set_fine_star_triangulations        Fine star triangulations of the polytope
+    _collect_linear_dependencies         Linear relations among points in all faces
+    _append_origin_weight                Add the origin weight to each relation
+    _setup_discriminant_symbols          Symbolic variables for the discriminant
+    _build_equation_system               Equation system for one block of relations
+    _eliminate_and_normalize             Eliminate lambda-variables and normalise
+    _append_unique_discriminants         Collect discriminant factors without duplicates
+    _compute_Kahler_generators           Kähler cone generators dual to the Mori cone
+    _compute_intersection_ring           Intersection ring polynomial of the CY
+    _intersection_substitution_rules     Kähler monomial -> intersection number rules
+    _replace_intersection_monomials      Substitute intersection numbers into an expression
+    _compute_Chern_character             Total Chern class via adjunction
+    _compute_Chern_polynomials           Chern polynomials with intersection numbers
+    _check_for_fibrations                Detect possible elliptic fibrations
+    _get_polytope_and_glsm_table         Table of polytope points and GLSM charges
+    _get_lvec_rows                       GLSM charge l-vectors as lists of ints
+    _get_output                          Dictionary of all topological data
+    _to_json_safe (staticmethod)         Convert values into JSON-safe primitives
+    _write_output_json                   Write the output dictionary to JSON
+
+ToricPolytopeCICY(ToricPolytope)
+    __init__                             Construct from a CICY configuration matrix
+    _CICY_to_points                      Configuration matrix -> points and nef partition
+
+ToricPolytopeProjectiveSpace(ToricPolytope)
+    __init__                             Construct from weighted projective space weights
+    _compute_points_from_weights         Weights -> polytope points
+"""
 import numpy as np
 import logging
 import os