#  Copyright (c) 1997-2015
#  Ewgenij Gawrilow, Michael Joswig (Technische Universitaet Berlin, Germany)
#  http://www.polymake.org
#
#  This program is free software; you can redistribute it and/or modify it
#  under the terms of the GNU General Public License as published by the
#  Free Software Foundation; either version 2, or (at your option) any
#  later version: http://www.gnu.org/licenses/gpl.txt.
#
#  This program is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
#  GNU General Public License for more details.
#-------------------------------------------------------------------------------


object Matroid {


## ENUMERATIVE PROPERTIES ###

# @category Enumerative properties
# Size of the ground set.  The ground set itself always consists of the first integers starting with zero.
property N_ELEMENTS : Int;

# @category Enumerative properties
# Rank of the matroid, i.e., number of elements in each basis.
property RANK : Int;

# @category Enumerative properties
# The number of [[BASES]].
property N_BASES : Int;

# @category Enumerative properties
# The number of [[CIRCUITS]].
property N_CIRCUITS : Int;

# @category Enumerative properties
# The number of [[MATROID_HYPERPLANES]]
property N_MATROID_HYPERPLANES : Int;

# @category Enumerative properties
# The number of [[LOOPS]].
property N_LOOPS : Int;

# @category Enumerative properties
# The number of flats, i.e. the number of nodes in [[LATTICE_OF_FLATS]].
property N_FLATS : Int;

# @category Enumerative properties
# The number of cyclic flats, i.e. the number of nodes in [[LATTICE_OF_CYCLIC_FLATS]].
property N_CYCLIC_FLATS : Int;

# @category Enumerative properties
# The order of the [[AUTOMORPHISM_GROUP]] of the matroid.
property N_AUTOMORPHISMS : Int;


## AXIOM SYSTEMS ###

# @category Axiom systems
# Subsets of the ground set which form the bases of the matroid.
# Note that if you want to define a matroid via its bases, you should also specify [[N_ELEMENTS]], because
# we allow matroids with loops.
property BASES : Array<Set>;

# permuting the [[BASES]]
permutation BasesPerm : PermBase;

rule BasesPerm.PERMUTATION : BasesPerm.BASES, BASES {
   $this->BasesPerm->PERMUTATION=find_permutation($this->BasesPerm->BASES, $this->BASES);
}

rule BASES : BasesPerm.BASES, BasesPerm.PERMUTATION {
   $this->BASES=permuted($this->BasesPerm->BASES, $this->BasesPerm->PERMUTATION);
}
weight 1.10;

# @category Axiom systems
# All subsets of the ground sets with cardinality [[RANK]] that are not bases.
property NON_BASES : Array<Set>;

# @category Axiom systems
# Circuits, i.e., minimal dependent sets.
property CIRCUITS : Array<Set>;

# @category Axiom systems
# Hyperplanes, i.e. flats of rank RANK-1.
property MATROID_HYPERPLANES : Array<Set>;

permutation HyperplanePerm : PermBase;

rule HyperplanePerm.PERMUTATION : HyperplanePerm.MATROID_HYPERPLANES, MATROID_HYPERPLANES {
   $this->HyperplanePerm->PERMUTATION = find_permutation( $this->HyperplanePerm->MATROID_HYPERPLANES,
      $this->MATROID_HYPERPLANES);
}
weight 2.10;

rule MATROID_HYPERPLANES : HyperplanePerm.MATROID_HYPERPLANES, HyperplanePerm.PERMUTATION {
   $this->MATROID_HYPERPLANES = permuted($this->HyperplanePerm->MATROID_HYPERPLANES, $this->HyperplanePerm->PERMUTATION);
}
weight 1.10;

# @category Axiom systems
# The lattice of flats, this is a graph with all closed sets as nodes
property LATTICE_OF_FLATS : Lattice<BasicDecoration, Sequential>;

# @category Axiom systems
# The lattice of cyclic flats of the matroid.
# A flat is a cyclic flat, if and only if it is a union of circuits.
# Their ranks can also be read off of this property using nodes_of_dim(..)
property LATTICE_OF_CYCLIC_FLATS : Lattice<BasicDecoration, Sequential>;


## ADVANCED PROPERTIES ###

# @category Advanced properties
# Loops
property LOOPS : Set;

# @category Advanced properties
# Polytope whose vertices are the characteristic vectors of the bases.
property POLYTOPE : polytope::Polytope;

# @category Advanced properties
# If the matroid is transversal,
# this is the unique maximal presentation. I.e. the set system consists of [[RANK]] many sets and none of the
# sets can be increased without changing the matroid.
property MAXIMAL_TRANSVERSAL_PRESENTATION : IncidenceMatrix;

# @category Advanced properties
# Whether the matroid is transversal, i.e. has a transversal presentation.
property TRANSVERSAL : Bool;

# @category Advanced properties
# Whether the matroid is nested, i.e. its [[LATTICE_OF_CYCLIC_FLATS]] is a chain.
property NESTED : Bool;

# @category Advanced properties
# Whether the matroid is paving
property PAVING : Bool;

# @category Advanced properties
# Whether the matroid is a uniform matroid
property UNIFORM : Bool;

# @category Advanced properties
# Whether the matroid is representable over GF(2)
property BINARY : Bool;

# @category Advanced properties
# Whether the matroid is isomorphic to its dual
# If you want to check whether it is actually equal (not just isomorphic), ask for
# [[IDENTICALLY_SELF_DUAL]].
property SELF_DUAL : Bool;

# @category Advanced properties
# Whether the matroid is equal to its dual. Note that this does not check for isomorphy,
# if you want to check whether the matroid is isomorphic to its dual, ask for
# [[SELF_DUAL]].
property IDENTICALLY_SELF_DUAL : Bool;

# @category Advanced properties
# If the matroid is realizable over the field GF(2) with two elements, this property contains
# coordinates for some realization.
property BINARY_VECTORS : Matrix<Int>;

# @category Advanced properties
# Whether the matroid is representable over GF(3)
# NOTE: the property may be 'undef' if the current implementation cannot decide.
property TERNARY : Bool;

# @category Advanced properties
# If the matroid is realizable over the field GF(3) with three elements, this property contains
# coordinates for some realization.
property TERNARY_VECTORS : Matrix<Int>;

# @category Advanced properties
# Whether the matroid is representable over every field, that is the repesentation is unimodular.
# NOTE: the property is 'undef' when its hard to decide, whether the matroid is ternary.
property REGULAR : Bool;

# @category Advanced properties
# The Tutte polynomial of a matroid.
# It is a polynomial in the two variables x and y, which are chosen such that the tutte polynomial
# of a single coloop is x and the tutte polynomial of a single loop is y.
property TUTTE_POLYNOMIAL : common::Polynomial;

# @category Advanced properties
# The G-invariant of the matroid (see [Derksen: Symmetric and quasi-symmetric functions associated to polymatroids, J. Algebr. Comb. 30 (2009), 43-86])
# We use the formulation by Bonin and Kung in [Bonin, Kung: The G-invariant and catenary data of a matroid (2015)]:
# The G-invariant is an element of the free abelian group over all (n,r)-sequences (where n = [[N_ELEMENTS]] and r = [[RANK]]), i.e. 0/1-sequences (r_1,...,r_n), where exactly r entries are 1. We identify each such sequence with its support, i.e. the set of entries equal to 1, so the G-invariant can be represented as a map which takes
# an r-set to the coefficient of the corresponding (n,r)-sequence.
# The formal definition goes as follows: For each permutation p on n, we define a sequence r(p) = (r_1,...,r_n)
# by r_1 = rank({p(1)}) and r_j = rank( {p(1),...,p(j)}) - rank( {p(1),...,p(j-1)}). Then
# G(M) := sum_p r(p), where the sum runs over all permutations p.
property G_INVARIANT : Map< Set<Int>, Integer>;

# @category Advanced properties
# This is an equivalent characterization of the [[G_INVARIANT]] given by Bonin and Kung ([Bonin, Kung: The G-invariant and catenary data of a matroid (2015)]).
# It lives in the free abelian group over all (n,r)-compositions (where n = [[N_ELEMENTS]] and r = [[RANK]]).
# Those are sequences (a0,...,ar) with a0 >= 0, a_j > 0 for j > 0 and sum a_i = n
# For each maximal chain of flats F0,...,Fr = E of M, the corresponding composition is a0 = |F0| and a_i = |Fi \ Fi-1| for i > 0.
# For a composition a, let v(M,a) be the number of maximal chains of flats with composition a. Then
# G(M) := sum_a v(M,a) * a, where the sum runs over all compositions a.
property CATENARY_G_INVARIANT : Map< Vector<Int>, Integer>;

# @category Advanced properties
# The coefficient of x of the Tutte polynomial
property BETA_INVARIANT : Integer;

# @category Advanced properties
# Whether the matroid is connected
property CONNECTED : Bool;

# @category Advanced properties
# The connected componets
property CONNECTED_COMPONENTS : Array<Set> {
   sub equal {
      defined(eval { find_permutation(@_) })
   }
}

# @category Advanced properties
# The number of [[CONNECTED_COMPONENTS]]
property N_CONNECTED_COMPONENTS : Int;

# @category Advanced properties
# Whether the matroid is series-parallel
property SERIES_PARALLEL : Bool;

# @category Advanced properties
# Whether the matroid is simple.
property SIMPLE : Bool;

# @category Advanced properties
# Whether the matroid is sparse_paving, i.e both the matroid and it's dual are paving
property SPARSE_PAVING : Bool;

# @category Advanced properties
# Whether the matroid is laminar. This is the case if and only if for any two circuits C1,C2 with
# non-empty intersection, their closures are comparable (i.e. one contains the other)
# see also [Fife, Oxley: Laminar matroids. arXiv: 1606.08354]
property LAMINAR : Bool;

# @category Advanced properties
# The flats that correspond to split facets of the matroid [[POLYTOPE]].
# The facets are either hypersimplex facets or splits
property SPLIT_FLACETS : Array<Array<Set>>;

# @category Advanced properties
# Whether all SPLIT_FLACETS in the matroid are compatible.
property SPLIT : Bool;

# @category Advanced properties
# The h-vector of a matroid
property H_VECTOR : Vector<Integer>;

# @category Advanced properties
# The f-vector of a matroid
property F_VECTOR : Vector<Integer>;

# @category Advanced properties
# A string listing the bases in revlex order. A '*' means the basis is present, a '0' that it is absent
property REVLEX_BASIS_ENCODING : String;

# @category Advanced properties
# The automorphism group of the matroid, operating on the ground set.
property AUTOMORPHISM_GROUP : group::Group;


## INPUT PROPERTIES AND OTHER STUFF ###

# @category Other
# Unique names assigned to the elements of the matroid.
#
# For a matroid build from scratch, you should create this property by yourself.
# If you build the matroid with a construction client, (e.g. [[matroid_from_graph]])
# the labels may be assigend for you in a meaningful way.
property LABELS : Array<String> : mutable;

# @category Input properties
# If the matroid is realizable over the rationals, this property contains
# coordinates for some realization. Specifying coordinates is one way
# to define a matroid.
property VECTORS : Matrix;

# @category Input properties
# A transversal matroid can be defined via a multiset of subsets of the ground set (0,...,n-1)
# (i.e. [[N_ELEMENTS]] needs to be specified).
# Its bases are the maximal matchings of the bipartite incidence graph.
property TRANSVERSAL_PRESENTATION : Array<Set<Int>>;

}

# Local Variables:
# mode: perl
# cperl-indent-level: 3
# indent-tabs-mode:nil
# End:
