Arithmat
SageMath implementation of arithmetic matroids and toric arrangements.
Authors: Roberto Pagaria and Giovanni Paolini
Requirements
Installation
From PyPI
The easiest way to start using Arithmat is to install the latest release from PyPI:
sage pip install upgrade arithmat
From source
Download source code from the git repository:
git clone https://github.com/giove91/arithmat.git
Change to the root directory and run:
sage pip install upgrade noindex v .
Overview
Arithmat is a SageMath package that implements arithmetic matroids and toric arrangements.
At its core there is the class ArithmeticMatroidMixin
, which is intended to be used in combination with any existing matroid class of SageMath (e.g. RankMatroid
, BasisMatroid
, LinearMatroid
) via multiple inheritance.
The most common combinations are already defined: ArithmeticMatroid
(deriving from RankMatroid
), BasisArithmeticMatroid
(deriving from BasisMatroid
), and LinearArithmeticMatroid
(deriving from LinearMatroid
).
An additional class ToricArithmeticMatroid
is implemented, for arithmetic matroids constructed from a fixed given representation.
Citing Arithmat
To 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"}},
}
Documentation
Import
All defined classes and functions can be imported at once:
from arithmat import *
Alternatively, it is possible to import only specific classes and/or functions. For example:
from arithmat import ArithmeticMatroid, ToricArithmeticMatroid
Available classes for arithmetic matroids
All classes for arithmetic matroids derive from ArithmeticMatroidMixin
and from some subclass of SageMath's Matroid
.
The class ArithmeticMatroidMixin
is 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 in arithmat
are the following.

ArithmeticMatroid(groundset, rank_function, multiplicity_function)
This is the simplest arithmetic matroid class, and derives from
ArithmeticMatroidMixin
andRankMatroid
.E = [1,2,3,4,5] def rk(X): return min(2, len(X)) def m(X): if len(X) == 2 and all(x in [3,4,5] for x in X): return 2 else: return 1 M = ArithmeticMatroid(E, rk, m) print(M) # Arithmetic matroid of rank 2 on 5 elements print(M.arithmetic_tutte_polynomial()) # y^3 + x^2 + 2*y^2 + 3*x + 3*y + 3 print(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 from
ArithmeticMatroidMixin
andMatroid
.The constructor requires an integer matrix
arrangement_matrix
representing 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_groundset
of the groundset (defaults torange(matrix.ncols())
). The number of rows ofarrangement_matrix
must be equal to the numer of rows oftorus_matrix
.The two matrices are not guaranteed to remain unchanged: internally,
torus_matrix
is 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 elements print(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 elements P.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 elements print(N.arrangement_matrix()) # [16 4 5 12] print(N.torus_matrix()) # []
The classes BasisArithmeticMatroid
and LinearArithmeticMatroid
derive from the SageMath classes BasisMatroid
and LinearMatroid
, respectively.
An instance of XxxArithmeticMatroid
can be constructed with XxxArithmeticMatroid(..., multiplicity_function=m)
, where ...
should be replaced by arguments to construct an instance of XxxMatroid
, and m
is 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)
def m(X): if len(X) == 2 and all(x in ['b','c','d'] for x in X): return 2 else: return 1 M = BasisArithmeticMatroid(groundset='abcd', bases=['ab', 'ac', 'ad', 'bc', 'bd', 'cd'], multiplicity_function=m) print(M) # Basis arithmetic matroid of rank 2 on 4 elements print(M.is_valid()) # True
It is possible to cast any arithmetic matroid to a
BasisArithmeticMatroid
: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 elements print(M2) # Basis arithmetic matroid of rank 2 on 4 elements print(M2.full_multiplicity() == M1.full_multiplicity()) # True

LinearArithmeticMatroid(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]]) def m(X): return 1 M = LinearArithmeticMatroid(A, multiplicity_function=m) print(M) # Linear arithmetic matroid of rank 3 on 5 elements print(M.is_valid()) # True
Finally, MinorArithmeticMatroid
and DualArithmeticMatroid
are the analogs of MinorMatroid
and DualMatroid
.
They are used when calling contract(X)
, delete(X)
, dual()
(see below).
Available methods
All classes for arithmetic matroids must also derive from some subclass of SageMath's Matroid
.
In particular, Matroid
methods 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 of ArithmeticMatroidMixin
also (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 torsionfree, 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 matrixA
is a representation of the matroid. The optional parameterordered_groundset
specifies the bijection between the columns of the matrix and the groundset. 
all_representations(ordered_groundset=None, shnf=True)
Generator of all nonequivalent 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 nonequivalent essential representations of the matroid. This callsall_representations()
. 
representation(ordered_groundset=None, shnf=True)
Return any essential representation of the matroid, orNone
if 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, ToricArithmeticMatroid
has 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].from arithmat import signed_hermite_normal_form print(signed_hermite_normal_form(matrix([[3, 2, 1], [1, 1, 3]]))) # [ 1 1 3] # [ 0 5 10]
More examples can be found in the test file.
Bibliography
[BM14] P. Brändén and L. Moci, The multivariate arithmetic Tutte polynomial, Transactions of the American Mathematical Society 366 (2014), no. 10, 55235540.
[DM13] M. D'Adderio and L. Moci, Arithmetic matroids, the Tutte polynomial and toric arrangements, Advances in Mathematics 232 (2013), 335367.
[DD18] A. D'Alì and E. Delucchi, StanleyReisner rings for symmetric simplicial complexes, Gsemimatroids 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, StanleyReisner rings for quasiarithmetic matroids, ArXiv preprint 1709.03834 (2017).
[Len19] M. Lenz, Representations of weakly multiplicative arithmetic matroids are unique, Annals of Combinatorics 23 (2019), no. 2, 335346.
[Mar18] I. Martino, Face module for realizable Zmatroids, Contributions to Discrete Mathematics 13 (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 A 167 (2019), 389402.
[PP19] R. Pagaria and G. Paolini, Representations of torsionfree arithmetic matroids, ArXiv preprint 1908.04137 (2019).
License
This project is licensed under the GNU General Public License v3.0.