This file is indexed.

/usr/share/gap/lib/basismut.gd is in gap-libs 4r6p5-3.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
#############################################################################
##
#W  basismut.gd                 GAP library                     Thomas Breuer
##
##
#Y  Copyright (C)  1996,  Lehrstuhl D für Mathematik,  RWTH Aachen,  Germany
#Y  (C) 1998 School Math and Comp. Sci., University of St Andrews, Scotland
#Y  Copyright (C) 2002 The GAP Group
##
##  This file declares the categories and operations for mutable bases.
##  <#GAPDoc Label="[1]{basismut}">
##  It is useful to have a <E>mutable basis</E> of a free module when successively
##  closures with new vectors are formed, since one does not want to create
##  a new module and a corresponding basis for each step.
##  <P/>
##  Note that the situation here is different from the situation with
##  stabilizer chains, which are (mutable or immutable) records that do not
##  need to know about the groups they describe,
##  whereas each (immutable) basis stores the underlying left module
##  (see&nbsp;<Ref Func="UnderlyingLeftModule"/>).
##  <P/>
##  So immutable bases and mutable bases are different categories of objects.
##  The only thing they have in common is that one can ask both for
##  their basis vectors and for the coefficients of a given vector.
##  <P/>
##  Since <C>Immutable</C> produces an immutable copy of any &GAP; object,
##  it would in principle be possible to construct a mutable basis that
##  is in fact immutable.
##  In the sequel, we will deal only with mutable bases that are in fact
##  <E>mutable</E> &GAP; objects,
##  hence these objects are unable to store attribute values.
##  <P/>
##  Basic operations for immutable bases are
##  <Ref Func="NrBasisVectors"/>, <Ref Func="IsContainedInSpan"/>,
##  <Ref Func="CloseMutableBasis"/>,
##  <Ref Func="ImmutableBasis"/>,
##  <Ref Func="Coefficients"/>, and <Ref Func="BasisVectors"/>.
##  <Ref Func="ShallowCopy"/> for a mutable basis returns a mutable
##  plain list containing the current basis vectors.
##  <!-- Also <Ref Attr="LeftActingDomain"/> (or the analogy for it) should be a basic-->
##  <!-- operation; up to now, apparantly one can avoid it,-->
##  <!-- but conceptually it should be available!-->
##  <P/>
##  Since mutable bases do not admit arbitrary changes of their lists of
##  basis vectors, a mutable basis is <E>not</E> a list.
##  It is, however, a collection, more precisely its family (see&nbsp;<Ref Sect="Families"/>)
##  equals the family of its collection of basis vectors.
##  <P/>
##  Mutable bases can be constructed with <C>MutableBasis</C>.
##  <P/>
##  Similar to the situation with bases (cf.&nbsp;<Ref Sect="Bases of Vector Spaces"/>),
##  &GAP; supports the following three kinds of mutable bases.
##  <P/>
##  The <E>generic method</E> of <C>MutableBasis</C> returns a mutable basis that
##  simply stores an immutable basis;
##  clearly one wants to avoid this whenever possible with reasonable effort.
##  <P/>
##  There are mutable bases that store a mutable basis for a nicer module.
##  <!--  This works if we have access to the mechanism of computing nice vectors,-->
##  <!--  and requires the construction with-->
##  <!--  <C>MutableBasisViaNiceMutableBasisMethod2</C> or-->
##  <!--  <C>MutableBasisViaNiceMutableBasisMethod3</C>!-->
##  Note that this is meaningful only if the mechanism of computing nice and
##  ugly vectors (see&nbsp;<Ref Sect="Vector Spaces Handled By Nice Bases"/>) is invariant
##  under closures of the basis;
##  this is the case for example if the vectors are matrices, Lie objects,
##  or elements of structure constants algebras. 
##  <P/>
##  There are mutable bases that use special information to perform their
##  tasks; examples are mutable bases of Gaussian row and matrix spaces.
##  <#/GAPDoc>
##


#############################################################################
##
#C  IsMutableBasis( <MB> )
##
##  <#GAPDoc Label="IsMutableBasis">
##  <ManSection>
##  <Filt Name="IsMutableBasis" Arg='MB' Type='Category'/>
##
##  <Description>
##  Every mutable basis lies in the category <C>IsMutableBasis</C>.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareCategory( "IsMutableBasis", IsObject );


#############################################################################
##
#O  MutableBasis( <R>, <vectors>[, <zero>] )
##
##  <#GAPDoc Label="MutableBasis">
##  <ManSection>
##  <Oper Name="MutableBasis" Arg='R, vectors[, zero]'/>
##
##  <Description>
##  <C>MutableBasis</C> returns a mutable basis for the <A>R</A>-free module generated
##  by the vectors in the list <A>vectors</A>.
##  The optional argument <A>zero</A> is the zero vector of the module;
##  it must be given if <A>vectors</A> is empty.
##  <P/>
##  <E>Note</E> that <A>vectors</A> will in general <E>not</E> be the basis vectors of the
##  mutable basis!
##  <!-- provide <C>AddBasisVector</C> to achieve this?-->
##  <Example><![CDATA[
##  gap> MB:= MutableBasis( Rationals, [ [ 1, 2, 3 ], [ 0, 1, 0 ] ] );
##  <mutable basis over Rationals, 2 vectors>
##  ]]></Example>
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareOperation( "MutableBasis", [ IsRing, IsCollection ] );


#############################################################################
##
#F  MutableBasisViaNiceMutableBasisMethod2( <R>, <vectors> )
#F  MutableBasisViaNiceMutableBasisMethod3( <R>, <vectors>, <zero> )
##
##  <ManSection>
##  <Func Name="MutableBasisViaNiceMutableBasisMethod2" Arg='R, vectors'/>
##  <Func Name="MutableBasisViaNiceMutableBasisMethod3" Arg='R, vectors, zero'/>
##
##  <Description>
##  Let <M>M</M> be the <A>R</A>-free left module generated by the vectors in the list
##  <A>vectors</A>, and assume that <M>M</M> is handled via nice bases.
##  <C>MutableBasisViaNiceMutableBasisMethod?</C> returns a mutable basis for <M>M</M>.
##  The optional argument <A>zero</A> is the zero vector of the module.
##  <P/>
##  <E>Note</E> that <M>M</M> is stored, and that it is used in calls to <C>NiceVector</C>
##  and <C>UglyVector</C>, and for accessing <A>R</A>.
##  (See the remark in the beginning of the file.)
##  </Description>
##  </ManSection>
##
DeclareGlobalFunction( "MutableBasisViaNiceMutableBasisMethod2" );

DeclareGlobalFunction( "MutableBasisViaNiceMutableBasisMethod3" );


#############################################################################
##
#O  NrBasisVectors( <MB> )
##
##  <#GAPDoc Label="NrBasisVectors">
##  <ManSection>
##  <Oper Name="NrBasisVectors" Arg='MB'/>
##
##  <Description>
##  For a mutable basis <A>MB</A>, <C>NrBasisVectors</C> returns the current number of
##  basis vectors of <A>MB</A>.
##  Note that this operation is <E>not</E> an attribute, as it makes no sense to
##  store the value.
##  <C>NrBasisVectors</C> is used mainly as an equivalent of <C>Dimension</C> for the
##  underlying left module in the case of immutable bases.
##  <Example><![CDATA[
##  gap> MB:= MutableBasis( Rationals, [ [ 1, 1], [ 2, 2 ] ] );;
##  gap> NrBasisVectors( MB );
##  1
##  ]]></Example>
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareOperation( "NrBasisVectors", [ IsMutableBasis ] );


#############################################################################
##
#O  ImmutableBasis( <MB>[, <V>] )
##
##  <#GAPDoc Label="ImmutableBasis">
##  <ManSection>
##  <Oper Name="ImmutableBasis" Arg='MB[, V]'/>
##
##  <Description>
##  <Ref Oper="ImmutableBasis"/> returns the immutable basis <M>B</M>, say,
##  with the same basis vectors as in the mutable basis <A>MB</A>.
##  <P/>
##  If the second argument <A>V</A> is present then <A>V</A> is the value of
##  <Ref Attr="UnderlyingLeftModule"/> for <M>B</M>.
##  The second variant is used mainly for the case that one knows the module
##  for the desired basis in advance, and if it has a nicer structure than
##  the module known to <A>MB</A>, for example if it is an algebra.
##  <!--  This happens for example if one constructs a basis of an ideal using-->
##  <!--  iterated closures of a mutable basis, and the final basis <M>B</M> shall-->
##  <!--  have the initial ideal as underlying module.-->
##  <Example><![CDATA[
##  gap> MB:= MutableBasis( Rationals, [ [ 1, 1 ], [ 2, 2 ] ] );;
##  gap> B:= ImmutableBasis( MB );
##  SemiEchelonBasis( <vector space of dimension 1 over Rationals>, 
##  [ [ 1, 1 ] ] )
##  gap> UnderlyingLeftModule( B );
##  <vector space of dimension 1 over Rationals>
##  ]]></Example>
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareOperation( "ImmutableBasis", [ IsMutableBasis ] );

DeclareOperation( "ImmutableBasis", [ IsMutableBasis, IsFreeLeftModule ] );


#############################################################################
##
#O  CloseMutableBasis( <MB>, <v> )
##
##  <#GAPDoc Label="CloseMutableBasis">
##  <ManSection>
##  <Oper Name="CloseMutableBasis" Arg='MB, v'/>
##
##  <Description>
##  For a mutable basis <A>MB</A> over the coefficient ring <M>R</M>, say,
##  and a vector <A>v</A>, <C>CloseMutableBasis</C> changes <A>MB</A> such that afterwards
##  it describes the <M>R</M>-span of the former basis vectors together with <A>v</A>.
##  <P/>
##  <E>Note</E> that if <A>v</A> enlarges the dimension then this does in general <E>not</E>
##  mean that <A>v</A> is simply added to the basis vectors of <A>MB</A>.
##  Usually a linear combination of <A>v</A> and the other basis vectors is added,
##  and also the old basis vectors may be modified, for example in order to
##  keep the list of basis vectors echelonized (see&nbsp;<Ref Func="IsSemiEchelonized"/>).
##  <Example><![CDATA[
##  gap> MB:= MutableBasis( Rationals, [ [ 1, 1, 3 ], [ 2, 2, 1 ] ] );
##  <mutable basis over Rationals, 2 vectors>
##  gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
##  false
##  gap> CloseMutableBasis( MB, [ 1, 0, 0 ] );
##  gap> MB;
##  <mutable basis over Rationals, 3 vectors>
##  gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
##  true
##  ]]></Example>
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareOperation( "CloseMutableBasis",
    [ IsMutableBasis and IsMutable, IsVector ] );


#############################################################################
##
#O  IsContainedInSpan( <MB>, <v> )
##
##  <#GAPDoc Label="IsContainedInSpan">
##  <ManSection>
##  <Oper Name="IsContainedInSpan" Arg='MB, v'/>
##
##  <Description>
##  For a mutable basis <A>MB</A> over the coefficient ring <M>R</M>, say,
##  and a vector <A>v</A>, <C>IsContainedInSpan</C> returns <K>true</K> is <A>v</A> lies in the
##  <M>R</M>-span of the current basis vectors of <A>MB</A>,
##  and <K>false</K> otherwise.
##  </Description>
##  </ManSection>
##  <#/GAPDoc>
##
DeclareOperation( "IsContainedInSpan", [ IsMutableBasis, IsVector ] );


#############################################################################
##
#E