#############################################################################
##
##  This file is part of GAP, a system for computational discrete algebra.
##
##  SPDX-License-Identifier: GPL## For example,accessing Qrows/> of <>M</M> via <Ref Oper"[]/>
#
##  Copyright of ## different numbers ofrowsorcolumns is not defined.
# refer to the  filefor .
##


############################################################################
##
##  This file together with 'matobj2.gd' formally define the interface to
##  those vector and matrix objects in GAP that are not represented
##  by plain lists.
##  In this file the categories are defined, it is read earlier in the
##  GAP library reading process.
##


# This is an internal filter mostly meant for declarations of methods that
# are meant to apply to both VectorObj and MatrixObj implementations;
# and possibly even old-style vector and matrix objects. We need this
# because if we defined e.g. BaseDomain twice for IsVectorObj and for
# IsMatrixObj, then the first definition incurs a "hidden implication"
# which then later leads to "method matches more than one declaration" messages.
# The proper fix is to remove hidden implication
DeclareCategory( #  P>


##   multiplication from theleft  defined   elements from
#
##  <#GAPDoc#  /
##  <ManSection# It is not  that the multiplication <><M associative,
##  <#and we not  what the <M>k<M>-hpower of a matrix object is
##
##  <Description>
##  The idea behind <E>vector objects</E> is that one wants to deal with
##  objects like coefficient lists of fixed length#  in this case for positive integers<>k/>
# <><M,say,which be  andcan be  from left
##  with elements from <M># </java.lang.StringIndexOutOfBoundsException: Index 8 out of bounds for length 8
##   multiplicationcanbe defined via the 
##  (see <# RefFilt="sOrdinaryMatrix>
##  which knowstogether with the associativity of the java.lang.StringIndexOutOfBoundsException: Range [60, 59) out of bounds for length 66
#<""Label" avector object/>
##  (with value <M>R</M>) and
##  <Ref Attr="Length"/>,
##  where <M>R</M> is a domain (see Chapter <Ref Chap="Domains"/>)
##  that has methods for
##  <Ref Attr="Zero"/>,
##  <Ref Attr="One"/>,
## <ef =IsOrdinaryMatrix>
##  <Ref java.lang.StringIndexOutOfBoundsException: Index 11 out of bounds for length 8
##  <Ref Prop="IsFinite"/>.
##  We say#collections (<ef =CollectionsFamily"/>) of its
##  Typically, <M>R</M> will be at least a semiring.
#  P>
##  For #  Howeveris <>ot<E>required  the entrieslie in<><Mjava.lang.StringIndexOutOfBoundsException: Index 71 out of bounds for length 71
##  <Ref Oper="#  also values may   be  embedded  <R/>
#  <Attr=ConstructingFilterLabel=  vector ">
##  is known for <M>v</M>.
##  <P/>
##  Further, entry access <M>v[i]</M> is expected to returnMR/>
# i \leq<M>C </>M>  )/M>,
##  and that these entries of <M>java.lang.StringIndexOutOfBoundsException: Range [0, 34) out of bounds for length 17
#</
##  Note 
##  of <
##  in ######################################################
##  (see #
##  and < #GAPDocLabel==IsRowListMatrix>
##  need <E# <anSection>
###<N="IsRowListMatrix Arg=obj'Type=Category">
##  defined over different base domains is not defined,
##  and a plain list of vector objects is#
##  Also unbinding entries of vector objects is not 
#  </java.lang.StringIndexOutOfBoundsException: Index 8 out of bounds for length 8
#    from the left  defined only with elements from
##  <M>R</M>.
##  <P/>
##  The family of <M>v</M> (see <Ref Func="FamilyObj"/#  that ,listaccess <>[]/M>(see<ef Oper=\\"> 
##  familyofits  domain<><M>
##  However, it is <E>##  for <M>1 \leq i \leq> \leq i\/><>NumberRows /C>M>M/>C <C.
##  in the sense of <Ref Oper="\in" Label="for a collection"/>,## </
## alsovaluesmay occur java.lang.StringIndexOutOfBoundsException: Range [31, 30) out of bounds for length 71
For , if <MR</M   java.lang.StringIndexOutOfBoundsException: Range [45, 44) out of bounds for length 67
# be elements of the coefficient ring of <M>R</M>.
##  </Description>
##  </ManSection>
##  <#/##  and differ   matrices may  rows.
##
DeclareCategory("sVectorObj,IsVector and IsVecOrMatObj and IsRowVectorOrVectorObj );


######################################  the row.
##
##  #</
##  <#  Matrix objecin <ef Filt="IsRowListMatrix"/> are <E>not</E>
##  <Filt Name="##  necessarily in <Ref"IsList",
##
##  <Description>
##  Several functions are defined for objects #  and then neednot  the rules  lists.
##  objects in <Ref Filt="IsMatrixObj"/>.
##  All these #  <Description>
##  It #  </ManSection
##  lists #  #GAPDoc>
##  <Ref Filt="IsMatrixObj"/>,
##  for example as a requirement in the installation of 
#
##  <P/>
##  <Example><!java.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
#gap m=IdentityMat,GF());
##  gap> IsMatrix( m );  IsMatrixObj( m ); java.lang.StringIndexOutOfBoundsException: Index 55 out of bounds for length 2
##  true
##  false
#  
##  gap> m:= java.lang.StringIndexOutOfBoundsException: Index 21 out of bounds for length 16
##  gap>  =BaseDomain"Arg=v'Label=for vector object"/java.lang.StringIndexOutOfBoundsException: Index 70 out of bounds for length 70
##  false
##  true
##  true
##  ]]></Example>
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
#FIXME whyis thisinthe `sVector ? makes perhapssense
ow matrices, notin general?   moveit to IsRowListMatrix
DeclareCategory(# The object <v<A or  Am/>java.lang.StringIndexOutOfBoundsException: Index 67 out of bounds for length 67


##############<ef AttrBaseDomain =fora vector object/> alue.
#java.lang.StringIndexOutOfBoundsException: Index 2 out of bounds for length 2
##Notethat we cannot get this implication already in the declaration of
##  'IsMatrix' because both 'IsVector' and 'IsMatrix' are declared #  its  domainwith respect to
##  '/rith.d'
##  and #  < Sect= and Rules forVectorand  /.
##  is declared in '#<Descriptionjava.lang.StringIndexOutOfBoundsException: Index 18 out of bounds for length 18
##
#T Do we DeclareAttribute( BaseDomain, IsVecOrMatObj );
#T plain lists) and objects in 'IsVectorObj'?
#T (For some operations, such as 'WeightOfVector'#eclareAttribute(""  );
T implicationwould make sense,,but  fact defaultmethods for
#T 'WeightVecFFE' and 'java.lang.StringIndexOutOfBoundsException: Index 36 out of bounds for length 2
#'')
##
InstallTrueMethod( IsMatrixOrMatrixObj, IsMatrix );


###############################NrCols(M>java.lang.StringIndexOutOfBoundsException: Index 17 out of bounds for length 17
#<anSectionjava.lang.StringIndexOutOfBoundsException: Index 16 out of bounds for length 16
##  <#GAPDoc Label="IsMatrixObj"#  <AttrName="Arg' Label"  matrix object/java.lang.StringIndexOutOfBoundsException: Index 65 out of bounds for length 65
##  <ManSection>
##  <Filt Name## <ttr Name"''Label a matrix">
##
##  <Description>
##  The idea behind <E>matrix objects</E> is that one wants to java.lang.StringIndexOutOfBoundsException: Index 67 out of bounds for length 61
##  objects# Description>
##  <M>R#For   object AM/>java.lang.StringIndexOutOfBoundsException: Index 33 out of bounds for length 33
##  and can be multiplied from the #  <Ref Attr="NumberColumns" Label="forobject/>store the
##  Amatrixobject<><M> say always copyable object
##  (see <Ref Filt="IsCopyable
##  <Ref##<Ref Attr=NrRows"=for   object">and
##   thevalues of
##  <Ref#< Attr=NumberRows =for  java.lang.StringIndexOutOfBoundsException: Range [47, 46) out of bounds for length 60
#  (with value<>/M>,
##  <Ref Attr="NumberRows" Label=#  </escriptionjava.lang.StringIndexOutOfBoundsException: Index 18 out of bounds for length 18
##  (with value <#
##  <Ref Attr="DeclareAttribute( "NumberRows", IsMatrixOrMatrixObj );
##  (with value <M>n</M>),
##  where <M>R</M> is a domain (see java.lang.StringIndexOutOfBoundsException: Index 43 out of bounds for length 43
# thathas  
##  <( ""  )
##  <Refjava.lang.StringIndexOutOfBoundsException: Index 0 out of bounds for length 0
#  Ref Oper=\n"Label= a collection/,
##  <java.lang.StringIndexOutOfBoundsException: Index 6 out of bounds for length 2
##  #  ( <>)
##  A (<>)
##  Typically, <M>R</M> will be at least a semiring.
##  <P/>
##  For creating #A  ZeroOfBaseDomainM 
##  <Ref#
##  <Ref Attr="ConstructingFilter" Label="for a matrix object"/>
##  is known for <M>M</M>.
##  <P/>
##  Further, entry access <M
#M>\eqi \leq m</M> and <M>1 \leq j \leq n</M>,
##  and that ##  <Attr Name="OnAttrName=""Arg=v Label"a  object/java.lang.StringIndexOutOfBoundsException: Index 70 out of bounds for length 70
##  <P/>
#   that we do Enot<>require<></>is list in thesense
##  #<Name=ZeroOfBaseDomain =M =fora "/java.lang.StringIndexOutOfBoundsException: Index 71 out of bounds for length 71
# of listarithmetic
##  (see the sections <Ref #ofthe <RefAttrBaseDomain" Label=for vector object">value
#  and<ef Sect="ultiplicativeArithmetic Lists/)
##  need <E>## respectively.
##  For example, accessing <Q>##  (see <Ref Filt="IsPlistRep"/>)RFilt==IsPlistRep/>   its
#   general not possible, andthe sumof two matrix objects with
##  different numbers of rows or columns is not defined.
##  Also unbinding entries of matrix objects#regarded  expensive,
##  <P/>
##  Scalar multiplication from the left is defined only with elements from
##  <M>R</M>.
##  <P/>
##  It is not assumed that the multiplication in <  beregarded as cheap.
##and  do not define  the Mk/>th power ofa matrix java.lang.StringIndexOutOfBoundsException: Range [71, 70) out of bounds for length 73
##  in this case, for positive #  first, without loss of performance lossof.
##  (However, a default powering method is available.)
## </
##  The# <ManSection>
##  java.lang.StringIndexOutOfBoundsException: Index 15 out of bounds for length 14
##  This DeclareAttribute( "OneOfBaseDomain", IsVectorObj );
##  <Ref Filt="IsOrdinaryMatrix"/>;
###( "neOfBaseDomain",IsMatrixOrMatrixObj;
##  also implies the associativity of matrix multiplication.
##  For example,
##   matrix algebras (ee<Attr=LieObject/)
##  lie in <Ref Filt="DeclareAttribute( "ZeroOfBaseDomain", IsVectorObj );
##  <Ref Filt="IsOrdinaryMatrix"/>.
###eclareAttribute("eroOfBaseDomain" IsMatrixOrMatrixObj );
##  The family of <M>M</M> (see <Ref Func="FamilyObj"/>) is the
##  collections family (see <Ref Attr="CollectionsFamily"/>) of its
##  base domain <M>R</M>.
##  However, it is <E>not</E> required that the entries lie in <M>R</M>
##  in the sense of <Ref Oper="\in" Label="for a collection"/>,
##  also values may occur that can be naturally embedded into <M>R</M>.
##  For example, if <M>R</M> is a polynomial ring then some entries
##  in <M>M</M> may be elements of the coefficient ring of <M>R</M>.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareCategory( "IsMatrixObj", IsMatrixOrMatrixObj );


#############################################################################
##
##  <#GAPDoc Label="IsRowListMatrix">
##  <ManSection>
##  <Filt Name="IsRowListMatrix" Arg='obj' Type="Category"/>
##
##  <Description>
##  A <E>row list matrix object</E> is a matrix object
##  (see <Ref Filt="IsMatrixObj"/>) <M>M</M> which admits access to its rows,
##  that is, list access <M>M[i]</M> (see <Ref Oper="\[\]"/>) yields
##  the <M>i</M>-th row of <M>M</M>,
##  for <M>1 \leq i \leq</M> <C>NumberRows( </C><M>M</M><C> )</C>.
##  <P/>
##  All rows are <Ref Filt="IsVectorObj"/> objects in the same
##  representation.
##  Several rows of a row list matrix object can be identical objects,
##  and different row list matrices may share rows.
##  Row access just gives a reference to the row object, without copying
##  the row.
##  <P/>
##  Matrix objects in <Ref Filt="IsRowListMatrix"/> are <E>not</E>
##  necessarily in <Ref Filt="IsList"/>,
##  and then they need not obey the general rules for lists.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareCategory( "IsRowListMatrix", IsMatrixObj );


#############################################################################
##
#A  BaseDomain( <vector> )
#A  BaseDomain( <matrix> )
##
##  <#GAPDoc Label="BaseDomain">
##  <ManSection>
##  <Heading>BaseDomain</Heading>
##  <Attr Name="BaseDomain" Arg='vector' Label="for a vector object"/>
##  <Attr Name="BaseDomain" Arg='matrix' Label="for a matrix object"/>
##
##  <Description>
##  The vector object <A>vector</A> or matrix object <A>matrix</A>,
##  respectively, is defined over the domain given by its
##  <Ref Attr="BaseDomain" Label="for a vector object"/> value.
##  <P/>
##  Note that not all entries of the object necessarily lie in
##  its base domain with respect to
##  <Ref Oper="\in" Label="for a collection"/>, see Section
##  <Ref Sect="Concepts and Rules for Vector and Matrix Objects"/>.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareAttribute( "BaseDomain", IsVecOrMatObj );
#DeclareAttribute( "BaseDomain", IsVectorObj );
#DeclareAttribute( "BaseDomain", IsMatrixOrMatrixObj );


#############################################################################
##
#A  NumberRows( <M> )
#A  NrRows( <M> )
#A  NumberColumns( <M> )
#A  NrCols( <M> )
##
##  <#GAPDoc Label="NumberRowsNumberColumns">
##  <ManSection>
##  <Heading>NumberRows and NumberColumns</Heading>
##  <Attr Name="NumberRows" Arg='M' Label="for a matrix object"/>
##  <Attr Name="NrRows" Arg='M' Label="for a matrix object"/>
##  <Attr Name="NumberColumns" Arg='M' Label="for a matrix object"/>
##  <Attr Name="NrCols" Arg='M' Label="for a matrix object"/>
##
##  <Description>
##  For a matrix object <A>M</A>,
##  <Ref Attr="NumberRows" Label="for a matrix object"/> and
##  <Ref Attr="NumberColumns" Label="for a matrix object"/> store the
##  number of rows and columns of <A>M</A>, respectively.
##  <P/>
##  <Ref Attr="NrRows" Label="for a matrix object"/> and
##  <Ref Attr="NrCols" Label="for a matrix object"/> are synonyms of
##  <Ref Attr="NumberRows" Label="for a matrix object"/> and
##  <Ref Attr="NumberColumns" Label="for a matrix object"/>, respectively.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareAttribute( "NumberRows", IsMatrixOrMatrixObj );
DeclareSynonymAttr( "NrRows", NumberRows );

DeclareAttribute( "NumberColumns", IsMatrixOrMatrixObj );
DeclareSynonymAttr( "NrCols", NumberColumns );


#############################################################################
##
#A  OneOfBaseDomain( <v> )
#A  OneOfBaseDomain( <M> )
#A  ZeroOfBaseDomain( <v> )
#A  ZeroOfBaseDomain( <M> )
##
##  <#GAPDoc Label="OneOfBaseDomain">
##  <ManSection>
##  <Heading>OneOfBaseDomain and ZeroOfBaseDomain</Heading>
##  <Attr Name="OneOfBaseDomain" Arg='v' Label="for a vector object"/>
##  <Attr Name="OneOfBaseDomain" Arg='M' Label="for a matrix object"/>
##  <Attr Name="ZeroOfBaseDomain" Arg='v' Label="for a vector object"/>
##  <Attr Name="ZeroOfBaseDomain" Arg='M' Label="for a matrix object"/>
##
##  <Description>
##  These attributes return the identity element and the zero element
##  of the <Ref Attr="BaseDomain" Label="for a vector object"/> value
##  of the vector object <A>v</A> or the matrix object <A>M</A>,
##  respectively.
##  <P/>
##  If <A>v</A> or <A>M</A>, respectively, is a plain list
##  (see <Ref Filt="IsPlistRep"/>) then computing its
##  <Ref Attr="BaseDomain" Label="for a vector object"/> value can be
##  regarded as expensive,
##  whereas calling <Ref Attr="OneOfBaseDomain" Label="for a vector object"/>
##  or <Ref Attr="ZeroOfBaseDomain" Label="for a vector object"/>
##  can be regarded as cheap.
##  If <A>v</A> or <A>M</A>, respectively, is not a plain list then
##  one can also call <Ref Attr="BaseDomain" Label="for a vector object"/>
##  first, without loss of performance.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareAttribute( "OneOfBaseDomain", IsVecOrMatObj );
#DeclareAttribute( "OneOfBaseDomain", IsVectorObj );
#DeclareAttribute( "OneOfBaseDomain", IsMatrixOrMatrixObj );

DeclareAttribute( "ZeroOfBaseDomain", IsVecOrMatObj );
#DeclareAttribute( "ZeroOfBaseDomain", IsVectorObj );
#DeclareAttribute( "ZeroOfBaseDomain", IsMatrixOrMatrixObj );