Package: arithmat
ArithmatSageMath implementation of arithmetic matroids and toric arrangements.Authors: Roberto Pagaria and Giovanni PaoliniRequirementsInstallationOverviewCiting ArithmatDocumentationImportAvailable classes for arithmetic matroidsAvailable methodsBibliographyLicenseRequirementsPython2.7 or 3.xSageMath>= 8InstallationFrom PyPIThe easiest way to start using Arithmat is to installthe latest release from PyPI:sage-pipinstall--upgradearithmatFrom sourceDownload source code from the git repository:gitclonehttps://github.com/giove91/arithmat.gitChange to the root directory and run:sage-pipinstall--upgrade--no-index-v.OverviewArithmat is a SageMath package that implements arithmetic matroids and toric arrangements.At its core there is the classArithmeticMatroidMixin, which is intended to be used in combination withany existing matroid class of SageMath(e.g.RankMatroid,BasisMatroid,LinearMatroid) via multiple inheritance.
The most common combinations are already defined:ArithmeticMatroid(deriving fromRankMatroid),BasisArithmeticMatroid(deriving fromBasisMatroid), andLinearArithmeticMatroid(deriving fromLinearMatroid).An additional classToricArithmeticMatroidis implemented, for arithmetic matroids constructed from a fixed given representation.Citing ArithmatTo cite Arithmat, you can use (some variant of) the following BibTeX code:@misc{arithmat,
  author ={Pagaria, Roberto and Paolini, Giovanni},
  title ={{Arithmat}:{SageMath}implementation of arithmetic matroids and toric arrangements},
  year ={2019},
  publisher ={GitHub},
  journal ={GitHub repository},
  howpublished ={\url{https://github.com/giove91/arithmat"}},}DocumentationImportAll defined classes and functions can be imported at once:fromarithmatimport*Alternatively, it is possible to import only specific classes and/or functions. For example:fromarithmatimportArithmeticMatroid,ToricArithmeticMatroidAvailable classes for arithmetic matroidsAll classes for arithmetic matroids derive fromArithmeticMatroidMixinand from some subclass of SageMath'sMatroid.
The classArithmeticMatroidMixinis not intended to be used by itself, but it is possible to subclass it in order to create new classes for arithmetic matroids.The classes which are already provided inarithmatare the following.ArithmeticMatroid(groundset, rank_function, multiplicity_function)This is the simplest arithmetic matroid class, and derives fromArithmeticMatroidMixinandRankMatroid.E=[1,2,3,4,5]defrk(X):returnmin(2,len(X))defm(X):iflen(X)==2andall(xin[3,4,5]forxinX):return2else:return1M=ArithmeticMatroid(E,rk,m)print(M)# Arithmetic matroid of rank 2 on 5 elementsprint(M.arithmetic_tutte_polynomial())# y^3 + x^2 + 2*y^2 + 3*x + 3*y + 3print(M.representation())# None (this arithmetic matroid is not representable)ToricArithmeticMatroid(arrangement_matrix, torus_matrix=None, ordered_groundset=None)Arithmetic matroid associated with a given toric arrangement. This class derives fromArithmeticMatroidMixinandMatroid.The constructor requires an integer matrixarrangement_matrixrepresenting the toric arrangement. Optionally it accepts another integer matrixtorus_matrix(whose cokernel describes the ambient torus, and defaults tomatrix(ZZ, arrangement_matrix.nrows(), 0)) and/or an ordered copyordered_groundsetof the groundset (defaults torange(matrix.ncols())). The number of rows ofarrangement_matrixmust be equal to the numer of rows oftorus_matrix.The two matrices are not guaranteed to remain unchanged: internally,torus_matrixis kept in Smith normal form (this also affectsarrangement_matrix).A=matrix(ZZ,[[-1,1,0,2],[3,1,-1,-2]])M=ToricArithmeticMatroid(A)print(M)# Toric arithmetic matroid of rank 2 on 4 elementsprint(M.arrangement_matrix())# [-1  1  0  2]# [ 3  1 -1 -2]print(M.torus_matrix())# []P=M.poset_of_layers()print(P)# Finite poset containing 11 elementsP.show(label_elements=False)A=matrix(ZZ,[[-1,1,0,2],[3,1,-1,-2]])Q=matrix(ZZ,[[5],[1]])N=ToricArithmeticMatroid(A,Q)print(N)# Toric arithmetic matroid of rank 1 on 4 elementsprint(N.arrangement_matrix())# [-16  -4   5  12]print(N.torus_matrix())# []The classesBasisArithmeticMatroidandLinearArithmeticMatroidderive from the SageMath classesBasisMatroidandLinearMatroid, respectively.
An instance ofXxxArithmeticMatroidcan be constructed withXxxArithmeticMatroid(..., multiplicity_function=m), where...should be replaced by arguments to construct an instance ofXxxMatroid, andmis the multiplicity function.
The multiplicity function needs to be passed as a keyword argument (and not as a positional argument).BasisArithmeticMatroid(M=None, groundset=None, bases=None, ..., multiplicity_function)defm(X):iflen(X)==2andall(xin['b','c','d']forxinX):return2else:return1M=BasisArithmeticMatroid(groundset='abcd',bases=['ab','ac','ad','bc','bd','cd'],multiplicity_function=m)print(M)# Basis arithmetic matroid of rank 2 on 4 elementsprint(M.is_valid())# TrueIt is possible to cast any arithmetic matroid to aBasisArithmeticMatroid:M1=ToricArithmeticMatroid(matrix(ZZ,[[-1,1,0,7],[6,1,-1,-2]]))M2=BasisArithmeticMatroid(M1)print(M1)# Toric arithmetic matroid of rank 2 on 4 elementsprint(M2)# Basis arithmetic matroid of rank 2 on 4 elementsprint(M2.full_multiplicity()==M1.full_multiplicity())# TrueLinearArithmeticMatroid(matrix=None, groundset=None, ..., multiplicity_function)A=matrix(GF(2),[[1,0,0,1,1],[0,1,0,1,0],[0,0,1,0,1]])defm(X):return1M=LinearArithmeticMatroid(A,multiplicity_function=m)print(M)# Linear arithmetic matroid of rank 3 on 5 elementsprint(M.is_valid())# TrueFinally,MinorArithmeticMatroidandDualArithmeticMatroidare the analogs ofMinorMatroidandDualMatroid.
They are used when callingcontract(X),delete(X),dual()(see below).Available methodsAll classes for arithmetic matroids must also derive from some subclass of SageMath'sMatroid.
In particular,Matroidmethods are still available. For example:M=ToricArithmeticMatroid(matrix(ZZ,[[1,2,3],[0,1,1]]))print(list(M.bases()))# [frozenset([0, 1]), frozenset([0, 2]), frozenset([1, 2])]All subclasses ofArithmeticMatroidMixinalso (re-)implement the following methods.multiplicity(X)Return the multiplicity of the setX.full_multiplicity()Return the multiplicity of the groundset.is_valid()Check if the arithmetic matroid axioms are satisfied.
This method overwritesMatroid.is_valid.is_torsion_free()Check if the matroid is torsion-free, i.e. the multiplicity of the empty set is equal to 1.is_surjective()Check if the matroid is surjective, i.e. the multiplicity of the groundset is equal to 1.is_gcd()Check if the matroid satisfies the gcd property, defined in [DM13, Section 3].is_strong_gcd()Check if the matroid satisfies the strong gcd property, defined in [PP19, Section 3].is_isomorphic(other, morphism)Check if the two arithmetic matroids are isomorphic.
This method overwritesMatroid.is_isomorphic.is_isomorphism(other, morphism)Check if the given morphism of groundsets is an isomorphism of arithmetic matroids.
It works also when comparing instances of different subclasses ofArithmeticMatroid.
This method overwritesMatroid.is_isomorphism.contract(X)Contract elements.
This method overwritesMatroid.contract.delete(X)Delete elements.
This method overwritesMatroid.delete.minor(contractions=None, deletions=None)Contract some elements and delete some other elements.
This method overwritesMatroid.minor.dual()Return the dual of the matroid.
This method overwritesMatroid.dual.arithmetic_tutte_polynomial(x=None, y=None)Return the arithmetic Tutte polynomial of the matroid.reduction()Return the reduction of the matroid, defined in [PP19, Section 4].check_representation(A, ordered_groundset=None)Check if the given integer matrixAis a representation of the matroid.
The optional parameterordered_groundsetspecifies the bijection between the columns of the matrix and the groundset.all_representations(ordered_groundset=None, shnf=True)Generator of all non-equivalent essential representations of the matroid, computed using the algorithm of [PP19, Section 5].
Ifshnf=True, the output matrices are guaranteed to be in signed Hermite normal form [PP19, Section 6].num_representations()Return the number of non-equivalent essential representations of the matroid.
This callsall_representations().representation(ordered_groundset=None, shnf=True)Return any essential representation of the matroid, orNoneif the matroid is not representable.is_representable()Check if the matroid is representable.
This callsrepresentation().is_orientable()Check if the matroid is orientable as an arithmetic matroid, as defined in [Pag18].In addition,ToricArithmeticMatroidhas the following methods.ordered_groundset()Return the groundset as a list, in the same order as the columns of the matrix of the defining toric arrangement.arrangement_matrix()Return the matrix of the defining toric arrangement.torus_matrix()Return the matrix describing the ambient torus.poset_of_layers()Return the poset of layers of the toric arrangement, computed using Lenz's algorithm [Len17a].arithmetic_independence_poset()Return the arithmetic independence poset of the toric arrangement, defined in [Len17b, Definition 5], [Mar18, Definitions 2.1 and 2.2], [DD18, Section 7].
Notice that it is not the same as the independence poset of the underlying matroid.decomposition()Return the partition of the groundset corresponding to the decomposition of the matroid as a direct sum of indecomposable matroids.
Uses the algorithm of [PP19, Section 7].is_decomposable()Check if the matroid is decomposable.is_indecomposable()Check if the matroid is not decomposable.is_equivalent(other, morphism=None)Check if the two ToricArithmeticMatroids are equivalent (i.e. the defining representations are equivalent; see [PP19, Section 2]).
If the morphism is not given, the two ordered groundsets are assumed to be the same.The following function is available outside of arithmetic matroid classes.signed_hermite_normal_form(A)Return the signed Hermite normal form of the integer matrixA, defined in [PP19, Section 6].fromarithmatimportsigned_hermite_normal_formprint(signed_hermite_normal_form(matrix([[3,2,1],[-1,1,3]])))# [  1   1  -3]# [  0   5 -10]More examples can be found in thetest file.Bibliography[BM14] P. Brändén and L. Moci,The multivariate arithmetic Tutte polynomial, Transactions of the American Mathematical Society366(2014), no. 10, 5523-5540.[DM13] M. D'Adderio and L. Moci,Arithmetic matroids, the Tutte polynomial and toric arrangements, Advances in Mathematics232(2013), 335-367.[DD18] A. D'Alì and E. Delucchi,Stanley-Reisner rings for symmetric simplicial complexes, G-semimatroids and Abelian arrangements, ArXiv preprint 1804.07366 (2018).[DGP17] E. Delucchi, N. Girard, and G. Paolini,Shellability of posets of labeled partitions and arrangements defined by root systems, ArXiv preprint 1706.06360 (2017).[Len17a] M. Lenz,Computing the poset of layers of a toric arrangement, ArXiv preprint 1708.06646 (2017).[Len17b] M. Lenz,Stanley-Reisner rings for quasi-arithmetic matroids, ArXiv preprint 1709.03834 (2017).[Len19] M. Lenz,Representations of weakly multiplicative arithmetic matroids are unique, Annals of Combinatorics23(2019), no. 2, 335-346.[Mar18] I. Martino,Face module for realizable Z-matroids, Contributions to Discrete Mathematics13(2018).[Pag17] R. Pagaria,Combinatorics of Toric Arrangements, ArXiv preprint 1710.00409 (2017).[Pag18] R. Pagaria,Orientable arithmetic matroids, ArXiv preprint 1805.11888 (2018).[Pag19] R. Pagaria,Two Examples of Toric Arrangements, Journal of Combinatorial Theory, Series A167(2019), 389-402.[PP19] R. Pagaria and G. Paolini,Representations of torsion-free arithmetic matroids, ArXiv preprint 1908.04137 (2019).LicenseThis project is licensed under theGNU General Public License v3.0.