#  Copyright (c) 1997-2018
#  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.
#-------------------------------------------------------------------------------

# @topic application
# The application group provides basic functionality for working with permutation groups. 
#
# An object of type [[Group]] records the abstract properties of the groups 
# that do not depend on any particular representation, such as [[Group::ORDER|ORDER]],
# [[Group::CHARACTER_TABLE|CHARACTER_TABLE]] and [[Group::CONJUGACY_CLASS_SIZES|CONJUGACY_CLASS_SIZES]].
#
# Moreover, it can contain several subobjects of type [[PermutationAction]], [[PermutationActionOnSets]] 
# or [[ImplicitActionOnSets]] that encode representations of the group. (We use the terms //action//
# and //representation// interchangeably). 
#
# If the group object is not contained inside a [[polytope::Cone]] or [[polytope::Polytope]],
# the representation in question is encoded as a [[Group::PERMUTATION_ACTION]], [[Group::SET_ACTION]] or 
# [[Group::IMPLICIT_SET_ACTION]], otherwise it may be encoded more specifically as a RAY_ACTION, FACET_ACTION,
# COORDINATE_ACTION, etc. 
#
# Different representations of the same group are convertible among each other either via specific rules, 
# or by using the function [[induced_action]], for example.

IMPORT
  common

file_suffix grp

HELP
  help.rules

# Object encoding a finite group.
declare object Group;

# parametrized object used for encoding group actions (representations).
#
# //GeneratorType// is Array<Int>      for permutation groups,
#                   or Matrix<Scalar>  for matrix groups.
#
# //DomainType// is Int                for permutation groups,
#                   Vector<Scalar>     for matrix groups acting on facets or vertices,
#                   Set<Int> or Bitset for groups acting on simplices,
#                   IncidenceMatrix    for groups acting on (maximal) cones of a fan
#
# //OrbitGeneratorScalarType// is the type of the entries of vectors that generate a geometric orbit; default Rational
#
declare object Action<GeneratorType, DomainType, OrbitGeneratorScalarType=Rational>;

# derived objects for permutation representations
declare object PermutationAction<DomainType=Int, OrbitGeneratorScalarType=Rational> : Action<Array<Int>, DomainType, OrbitGeneratorScalarType>;

# derived object for permuting collections of sets
declare object PermutationActionOnSets : PermutationAction<Set<Int>>;

# derived object encoding an action of a permutation group on a collection of sets,
# but where only one representative of each orbit is stored explicitly
declare object ImplicitActionOnSets : PermutationAction<Bitset>;

# derived object for matrix groups
declare object MatrixActionOnVectors<Scalar=Rational> : Action<Matrix<Scalar>, Vector<Scalar>, Scalar>;

# object for encoding the separate actions of a group on a collection of sets, induced by the same generators
declare object LayeredPermutationAction<DomainType=IncidenceMatrix>;

# A template parameter used by [[action]] and [[orbit]] specifying that
# the permutation acts on the given container. It will permute the order of
# the elements
declare property_type on_container : c++ (special => 'on_container', include => "polymake/group/orbit.h");

# A template parameter used by [[action]] and [[orbit]] specifying that
# the permutation acts on the given container. It will permute the order of
# the elements, leaving the '0'-th one fixed and adjusting the indices of the permutation
declare property_type on_nonhomog_container : c++ (special => 'on_nonhomog_container', include => "polymake/group/orbit.h");

# A template parameter used by [[action]] and [[orbit]] specifying that
# the permutation acts on the deepest elements inside a given container,
# which should be of type [[Int]].
declare property_type on_elements: c++ (special => 'on_elements', include => "polymake/group/orbit.h");

# A template parameter used by [[action]] and [[orbit]] specifying that
# the permutation acts on the rows of a matrix.
declare property_type on_rows: c++ (special => 'on_rows', include => "polymake/group/orbit.h");

# A template parameter used by [[action]] and [[orbit]] specifying that
# the permutation acts on the columns of a matrix.
declare property_type on_cols: c++ (special => 'on_cols', include => "polymake/group/orbit.h");

# A template parameter used by [[action]] and [[orbit]] specifying that
# the permutation acts on all columns of a matrix, except the '0'-th one,
# and adjusting the indices of the permutation
declare property_type on_nonhomog_cols: c++ (special => 'on_nonhomog_cols', include => "polymake/group/orbit.h");

INCLUDE
  group_properties.rules
  action_properties.rules
  action_functions
  action.rules
  group.rules
  permlib.rules
  group_helpers.rules

# Local Variables:
# mode: perl
# c-basic-offset:3
# End:
