plum module#

A sage module for analyzing manifolds plumbed along 2-spheres.

This module enables the user to enter a plumbing diagram and return basic information about the corresponding 3- and 4-dimensional manifolds, for example the intersection form, homology, etc.

For negative definite plumbing trees equipped with a spin^c structure, the program can also compute the weighted graded root [AJK21], \(\widehat{Z}\) invariant [GPPV20], and the \(\widehat{\widehat{Z}}\) invariant [AJK21].

[AJK21]

Rostislav Akhmechet, Peter K Johnson, and Vyacheslav Krushkal. Lattice cohomology and q-series invariants of 3-manifolds. arXiv preprint arXiv:2109.14139, 2021.

[BMM20]

Kathrin Bringmann, Karl Mahlburg, and Antun Milas. Quantum modular forms and plumbing graphs of 3-manifolds. J. Combin. Theory Ser. A, 170:105145, 32, 2020. doi:10.1016/j.jcta.2019.105145.

[CCF+19]

Miranda C.N. Cheng, Sungbong Chun, Francesca Ferrari, Sergei Gukov, and Sarah M. Harrison. 3d modularity. J. High Energy Phys., pages 010, 93, 2019. doi:10.1007/jhep10(2019)010.

[DM19]

Irving Dai and Ciprian Manolescu. Involutive Heegaard Floer homology and plumbed three-manifolds. J. Inst. Math. Jussieu, 18(6):1115–1155, 2019. doi:10.1017/s1474748017000329.

[Don83]

S. K. Donaldson. An application of gauge theory to four-dimensional topology. J. Differential Geom., 18(2):279–315, 1983.

[Flo88]

Andreas Floer. An instanton-invariant for 3-manifolds. Comm. Math. Phys., 118(2):215–240, 1988.

[GS99]

Robert E. Gompf and András I. Stipsicz. 4-manifolds and Kirby calculus. Volume 20 of Graduate Studies in Mathematics. American Mathematical Society, Providence, RI, 1999. ISBN 0-8218-0994-6. doi:10.1090/gsm/020.

[GM21]

Sergei Gukov and Ciprian Manolescu. A two-variable series for knot complements. Quantum Topol., 12(1):1–109, 2021. doi:10.4171/qt/145.

[GPP21]

Sergei Gukov, Sunghyuk Park, and Pavel Putrov. Cobordism invariants from BPS q-series. In Annales Henri Poincaré, 1–31. Springer, 2021.

[GPPV20]

Sergei Gukov, Du Pei, Pavel Putrov, and Cumrun Vafa. BPS spectra and 3-manifold invariants. J. Knot Theory Ramifications, 29(2):2040003, 85, 2020. doi:10.1142/S0218216520400039.

[GPV17]

Sergei Gukov, Pavel Putrov, and Cumrun Vafa. Fivebranes and 3-manifold homology. J. High Energy Phys., pages 071, front matter+80, 2017. doi:10.1007/JHEP07(2017)071.

[HM17]

Kristen Hendricks and Ciprian Manolescu. Involutive Heegaard Floer homology. Duke Math. J., 166(7):1211–1299, 2017. doi:10.1215/00127094-3793141.

[Jon85]

Vaughan F. R. Jones. A polynomial invariant for knots via von Neumann algebras. Bull. Amer. Math. Soc. (N.S.), 12(1):103–111, 1985. doi:10.1090/S0273-0979-1985-15304-2.

[LZ99]

Ruth Lawrence and Don Zagier. Modular forms and quantum invariants of 3-manifolds. Asian Journal of Mathematics, 3(1):93–108, 1999.

[Neu81]

Walter D. Neumann. A calculus for plumbing applied to the topology of complex surface singularities and degenerating complex curves. Trans. Amer. Math. Soc., 268(2):299–344, 1981. doi:10.2307/1999331.

[Nem05]

András Némethi. On the Ozsváth-Szabó invariant of negative definite plumbed 3-manifolds. Geom. Topol., 9:991–1042, 2005. doi:10.2140/gt.2005.9.991.

[Nem08]

András Némethi. Lattice cohomology of normal surface singularities. Publ. Res. Inst. Math. Sci., 44(2):507–543, 2008. doi:10.2977/prims/1210167336.

[OzsvathSSzabo14a]

Peter Ozsváth, András I. Stipsicz, and Zoltán Szabó. A spectral sequence on lattice homology. Quantum Topol., 5(4):487–521, 2014. doi:10.4171/QT/56.

[OzsvathSSzabo14b]

Peter Ozsváth, András I. Stipsicz, and Zoltán Szabó. Knots in lattice homology. Comment. Math. Helv., 89(4):783–818, 2014. doi:10.4171/CMH/334.

[OzsvathSzabo03]

Peter Ozsváth and Zoltán Szabó. On the Floer homology of plumbed three-manifolds. Geom. Topol., 7:185–224, 2003. doi:10.2140/gt.2003.7.185.

[OzsvathSzabo04a]

Peter Ozsváth and Zoltán Szabó. Holomorphic disks and three-manifold invariants: properties and applications. Ann. of Math. (2), 159(3):1159–1245, 2004. doi:10.4007/annals.2004.159.1159.

[OzsvathSzabo04b]

Peter Ozsváth and Zoltán Szabó. Holomorphic disks and topological invariants for closed three-manifolds. Ann. of Math. (2), 159(3):1027–1158, 2004. doi:10.4007/annals.2004.159.1027.

[RT91]

N. Reshetikhin and V. G. Turaev. Invariants of 3-manifolds via link polynomials and quantum groups. Invent. Math., 103(3):547–597, 1991. doi:10.1007/BF01239527.

[Wit89]

Edward Witten. Quantum field theory and the Jones polynomial. Comm. Math. Phys., 121(3):351–399, 1989.

class plum.AdmissibleFamily(values)#

Bases: object

A class to store and process a custom admissible family over the rationals. In general, an admissible family can be defined over any commutative ring with 1, however for now we only consider the rationals. See [AJK21] for more details.

An admissible family is completely determined by an infinite sequence in RxR, where R is the underlying ring (which in this setup we choose to be the rationals). To compute the weighted graded root, zhat, or zhat_hat, of a given plumbing with respect to some admissible family one really only needs a finite sequence in RxR. Specifically, one needs a list of max_degree - 2 elements of RxR where max_degree is the maximum degree over all vertices in the plumbing.

Parameters:

values: list: A list of the form [(a_i,b_i)] where a_i and b_i are rational numbers specifiying that F_{i+3}(0) = a_i and F_{i+3}(1) = b_i.

Attributes:

length

Methods

evaluation

evaluation(index, r)#

property length#

class plum.CustomVertex(v)#

Bases: tuple

A class to allow for non-unique vertex labels for a sage Graph() object.

A vertex will be specified by a tuple v whose last entry is it’s label. The subtuple v[:-1] must uniquely specify the vertex.

Methods

`count`(value, /)	Return number of occurrences of value.
`index`(value[, start, stop])	Return first index of value.

class plum.Plumbing(vertices_dict, edges)#

Bases: object

A class for analyzing 3-manifolds plumbed along 2-spheres.

Parameters:

vertices_dictdict: A dictionary of the form {a:b} where a is the index of a vertex of the plumbing and b is its corresponding weight.
edgesarray_like: A list of the form [(a,b)] where (a,b) represents an edge between the vertices of indicies a and b.

Attributes:

artin_fcycle: tuple: A tuple of the form (x, comp_seq) where x is the Artin
bad_vertices: tuple: A tuple of the form (bv, bv_count) where bv is a string
definiteness_type: str: The definiteness type of the intersection form of the plumbing.
degree_vector: Matrix: An sx1 matrix of the form [[d_1],…,[d_s]] where d_i is the degree (or valence) of vertex i and s is the number of vertices of the plumbing.
edge_count: int: The number of edges in the plumbing
homology: tuple: A tuple of the form (homology_group, homology_generators,
intersection_form: Matrix: A matrix representing the intersection form of the plumbing.
intersection_smith_form: array_like: A list of the form D, U, V, where D is the smith normal
is_intersection_form_non_singular: bool: True if the intersection form is non-singular, False otherwise.
is_rational: bool: True if the plumbing is rational, False or N/A otherwise.
is_tree: bool: True if the plumbing diagram is a finite tree, False
is_weakly_elliptic: bool: True if the plumbing is weakly elliptic, False or N/A
max_degree: int: the maximum degree over all vertices in the plumbing.
vertex_count: int: The number of vertices in the plumbing.
weight_vector: Matrix: An sx1 matrix of the form [[m_1],…,[m_s]] where m_i is the weight of vertex i and s is the number of vertices of the plumbing.

Methods

`F`(k, x[, A])	Given a vector k, lattice element x, and admissible family A, computes :math: F_{Gamma, k}(x).
`char_vector_properties`(k)	Given a characteristic vector k, compute some basic properties.
`chi`(k, x)	Given a vector k and a lattice point x (represented as a vector), compute chi_k(x) = -1/2(k(x) + (x,x)).
`chi_local_min_bounds`(k)	Given a vector k, computes two lists [-chi_k(-e_1), ..., -chi_k(-e_s)] and [chi_k(e_1), ..., chi_k(e_s)] where e_i = (0, ..., 0, 1, 0, ..., 0) is the ith standard basis vector and s is the number of vertices of the plumbing.
`chi_local_min_set`(k)	Given a vector k, computes the set of lattice points at which chi_k achieves a local min, when restricted to the lattice.
`chi_min`(k)	Given a vector k, computes the minimum of the function chi_k on Euclidean space and computes the vector which achieves this minimum.
`chi_sublevels`(k, n)	Given a characteristic vector k and a positive integer n, this function computes the lattice points in each of the first n non-empty sublevel sets of chi_k.
`display`()	Displays the plumbing graph.
`equiv_spinc_reps`(k1, k2)	Given two characteristic vectors, check if they represent the same spin^c structure.
`is_almost_rational`(test_threshold)	Tests if plumbing is almost rational.
`is_in_integer_image`(k)	Given a vector k, check if it is in the integer image of the intersection form.
`weighted_graded_root`(k, n[, A])	Given a characteristic vector k, a positive integer n, and an admissible family A, computes the first n levels of the weighted graded root corresponding to the admissible family.
`zhat`(s_rep, n, spinc_convention[, A])	Computes the generalized \(\widehat{Z}\) for the first n levels with respect to some admissible family A.
`zhat_hat`(s_rep, n, spinc_convention[, A])	Computes the generalized \(\widehat{\widehat{Z}}\) for the first n levels with respect to some admissible family A.

F(k, x, A=None)#

Given a vector k, lattice element x, and admissible family A, computes :math: F_{Gamma, k}(x). See [AJK21] for more details. If no admissible family is specified, then the admissible family used in the computation is \(\widehat{F}\).

Parameters:

k: list: A list of integers [a_1, …, a_s] where s is the number of vertices of the plumbing.
x: list: A list of integers [x_1, …, x_s] where s is the number of vertices of the plumbing.
A: AdmissibleFamily: An AdmissibleFamily object.

Returns:

int: The value :math: F_{Gamma, k}(x)

property artin_fcycle#: tuple: A tuple of the form (x, comp_seq) where x is the Artin fundamental cycle of the plumbing and comp_seq is the associated computation sequence used to compute x. The Artin fundamental cycle is used to determine the rationality of the plumbing graph. See [Nem05] for more details about the Artin fundamental cycle.

property bad_vertices#: tuple: A tuple of the form (bv, bv_count) where bv is a string listing the bad vertices, and bv_count is the number of bad vertices. Recall a bad vertex is a vertex whose weight is greater than the negative of its degree.

char_vector_properties(k)#

Given a characteristic vector k, compute some basic properties.

Parameters:

k: list: A list of integers [x_1, …, x_s] where s is the number of vertices of the plumbing.

Returns:

tuple: (a,b,c, d) where: a is a string which says if the associated spin^c structure on the plumbed 3-manifold is torsion or non-torsion, b is the order of the 1st Chern class of the associated spin^c structure on the plumbed 3-manifold, c is the square of the 1st Chern class of the associated spin^c structure on the plumbed 4-manifold (in other words, c = k^2), d is the t-variable normalization.

chi(k, x)#

Given a vector k and a lattice point x (represented as a vector), compute chi_k(x) = -1/2(k(x) + (x,x)).

Parameters:

k: list: A list of integers [a_1, …, a_s] where s is the number of vertices of the plumbing.
x: list: A list of integers [x_1, …, x_s] where s is the number of vertices of the plumbing.

Returns:

sage constant: The value of chi_k(x)

chi_local_min_bounds(k)#

Given a vector k, computes two lists [-chi_k(-e_1), …, -chi_k(-e_s)] and [chi_k(e_1), …, chi_k(e_s)] where e_i = (0, …, 0, 1, 0, …, 0) is the ith standard basis vector and s is the number of vertices of the plumbing. For the purpose of this function, see the function chi_local_min_set.

Parameters:

k: list: A list of integers [x_1, …, x_s].

Returns:

tuple: (a,b) where: a = [-chi_k(-e_1), …, -chi_k(-e_s)] and b = [chi_k(e_1), …, chi_k(e_s)]

chi_local_min_set(k)#

Given a vector k, computes the set of lattice points at which chi_k achieves a local min, when restricted to the lattice. In other words, it computes the lattice points x such that chi_k(x) <= chi_k(x +/- e_i) for all i where e_i = (0, …, 0, 1, 0, …, 0) is the ith standard basis vector. Note chi_k(x +/- e_i) = chi_k(x)+ chi_k(+/- e_i) -/+ (x, e_i). Hence, x is in the min set iff -chi_k(-e_i) <= (x, e_i) <= chi_k(e_i) for all i. This explains the reason for the helper function chi_local_min_bounds.

Parameters:

k: list: A list of integers [x_1, …, x_s] where s is the number of vertices of the plumbing.

Returns:

lists: Each element of the output list is a tuple (a, b, c) where a is an element of the local min set, b is chi_k(a), c = a dot (weight_vector + degree_vector).

chi_min(k)#

Given a vector k, computes the minimum of the function chi_k on Euclidean space and computes the vector which achieves this minimum. Note this vector, in general, need not be integral.

Parameters:

k: list: A list of integers [a_1, …, a_s] where s is the number of vertices of the plumbing.

Returns:

tuple: (a,b) where: a is the minimum value of chi_k over R^s and b is a list representing the unique vector which achieves this minimum.

chi_sublevels(k, n)#

Given a characteristic vector k and a positive integer n, this function computes the lattice points in each of the first n non-empty sublevel sets of chi_k. Also, computes chi_k(x) and x dot (weight_vector + degree_vector) associated to each lattice point x in each sublevel set.

Parameters:

k: list: A list of integers [x_1, …, x_s] where s is the number of vertices in the plumbing.
n: int: A positive integer.

Returns:

list: A list of the form [S_1, …, S_n] where S_i is the ith non-empty sublevel set. Each S_i is a set whose elements are tuples of the form (a, b, c) where a is a lattice point in S_i, b = chi_k(a), c = a dot (weight_vector + degree_vector).

property definiteness_type#: str: The definiteness type of the intersection form of the plumbing.

Warning

Since the eigenvalues are computed numerically, they may contain small error terms. Therefore, to check the sign of an eigenvalue, we have chosen a small error threshold (1e-8). This potentially could lead to incorrect answers in some edge cases when the true eigenvalues are very close to zero, but non-zero.

property degree_vector#: Matrix: An sx1 matrix of the form [[d_1],…,[d_s]] where d_i is the degree (or valence) of vertex i and s is the number of vertices of the plumbing.

display()#: Displays the plumbing graph.

property edge_count#: int: The number of edges in the plumbing

equiv_spinc_reps(k1, k2)#

Given two characteristic vectors, check if they represent the same spin^c structure.

Parameters:

k1: list: A list of integers [x_1, …, x_s] where s is the number of vertices of the plumbing.
k2: list: A list of integers [y_1, …, y_s] where s is the number of vertices of the plumbing.

Returns:

bool: True if k1 and k2 represent the same spinc structure on the plumbed 3-manifold, False otherwise.

property homology#: tuple: A tuple of the form (homology_group, homology_generators, rank) where homology_group is the first homology of the plumbed 3-manifold, homology generators are the corresponding generators of homology_group, and rank is the Z-rank of the homology.

property intersection_form#: Matrix: A matrix representing the intersection form of the plumbing.

property intersection_smith_form#: array_like: A list of the form D, U, V, where D is the smith normal form of the intersection form and where U and V are matrices such that U*intersection_form*V = D.

is_almost_rational(test_threshold)#

Tests if plumbing is almost rational.

Parameters:

test_threshold: int: A non-negative integer which is the amount by which framings are decreased to test for rationality. See [Nem05] for the definition of almost rational.

Returns:

bool/str: True if plumbing is verfied to be almost rational given the test threshold. False if determined to be not almost rational. Otherwise, inconclusive given the choice of test threshold, or not applicable if plumbing is not a negative definite tree.

is_in_integer_image(k)#

Given a vector k, check if it is in the integer image of the intersection form.

Parameters:

k: list: A list of integers of length = self.vertex_count.

Returns:

bool: True if k is in the integer image of the intersection form, False otherwise.

property is_intersection_form_non_singular#: bool: True if the intersection form is non-singular, False otherwise.

property is_rational#: bool: True if the plumbing is rational, False or N/A otherwise.

property is_tree#: bool: True if the plumbing diagram is a finite tree, False otherwise.

property is_weakly_elliptic#: bool: True if the plumbing is weakly elliptic, False or N/A otherwise.

property max_degree#: int: the maximum degree over all vertices in the plumbing.

property vertex_count#: int: The number of vertices in the plumbing.

property weight_vector#: Matrix: An sx1 matrix of the form [[m_1],…,[m_s]] where m_i is the weight of vertex i and s is the number of vertices of the plumbing.

weighted_graded_root(k, n, A=None)#

Given a characteristic vector k, a positive integer n, and an admissible family A, computes the first n levels of the weighted graded root corresponding to the admissible family. If no admissible family is specified, then the admissible family used in the computation is \(\widehat{F}\). See [AJK21] for details.

Parameters:

k: list: A list of integers [x_1, …, x_s] where s is the number of vertices in the plumbing. k should be a characteristic vector.
n: int: A positive integer.
A: AdmissibleFamily: An AdmissibleFamily object.

Returns:

tuple: A tuple of the form (a, b) where a is a GraphPlot object representing the weighted graded root and b is a list of the two-variable weights of the vertices of the weighted graded root.

zhat(s_rep, n, spinc_convention, A=None)#

Computes the generalized \(\widehat{Z}\) for the first n levels with respect to some admissible family A. If no admissible family A is specified then, it computes the usual zhat with respect to the admissible family \(\widehat{F}\). See [AJK21] or [GPPV20] for more details.

Parameters:

s_rep: list: A list of integers [x_1, …, x_s] where s is the number of vertices in the plumbing.
n: int: A positive integer.
spinc_convention: int: Either 0 or 1. If 0, then the vector s_rep should be congruent to the weight vector mod 2. If 1, then the vector s_rep should be congruent to the degree vector mod 2. The spinc_conventions 0 and 1 correspond to conventions (2) and (3) respectively in section 2 of [AJK21] for representing spin^c structures.
A: AdmissibleFamily: An AdmissibleFamily object.

Returns:

Laurent polynomial:

A Laurent polynomial in q (except with the q variable possibly assuming powers shifted by some overall rational number). If \(\widehat{Z} = a_{1}q^{\Delta + m} + a_{2}q^{\Delta + m +1} + \cdots + a_{n}q^{\Delta + m+n-1} + \cdots\)

where m is the minimum of \(\chi_{k}\) over the lattice, then the output of this function is \(a_{1}q^{\Delta + m} + a_{2}q^{\Delta + m +1} + \cdots + a_{n}q^{\Delta + m+n-1}\)

Note, some \(a_{i}\) coefficients may be zero, in which case it may appear that there are less than n terms.

zhat_hat(s_rep, n, spinc_convention, A=None)#

Computes the generalized \(\widehat{\widehat{Z}}\) for the first n levels with respect to some admissible family A. If no admissible family A is specified then, it computes the usual zhat with respect to the admissible family \(\widehat{F}\).

Parameters:

s_rep: list: A list of integers [x_1, …, x_s] where s is the number of vertices in the plumbing.
n: int: A positive integer.
spinc_convention: int: Either 0 or 1. If 0, then the vector s_rep should be congruent to the weight vector mod 2. If 1, then the vector s_rep should be congruent to the degree vector mod 2. The spinc_conventions 0 and 1 correspond to conventions (2) and (3) respectively in section 2 of [AJK21] for representing spin^c structures.
A: AdmissibleFamily: An AdmissibleFamily object.

Returns:

two-variable laurent polynomial:

A Laurent polynomial in q with coefficients in Laurent polynomials in t (except with the q variable possibly assuming powers shifted by some overall rational number). If \(\widehat{\widehat{Z}} = p_{1}(t)q^{\Delta + m} + p_{2}(t)q^{\Delta + m +1} + \cdots + p_{n}(t)q^{\Delta + m+n-1} + \cdots\)

where m is the minimum of \(\chi_{k}\) over the lattice, then, the output of this function is \(p_{1}(t)q^{\Delta + m} + p_{2}(t)q^{\Delta + m +1} + \cdots + p_{n}(t)q^{\Delta + m+n-1}\)

Note, some \(p_{i}(t)\) coefficients may be zero, in which case it may appear that there are less than n terms.