% This file was created automatically from mapping.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%A  mapping.msk                  GAP documentation              Thomas Breuer
%%
%A  @(#)$Id: mapping.msk,v 1.20 2002/04/15 10:02:30 sal Exp $
%%
%Y  (C) 1998 School Math and Comp. Sci., University of St.  Andrews, Scotland
%Y  Copyright (C) 2002 The GAP Group
%%
\Chapter{Mappings}

\index{functions}
\index{relations}
A *mapping* in {\GAP} is what is called a ``function'' in mathematics.
{\GAP} also implements *generalized mappings* in which one element might
have several images, these can be imagined as subsets of the cartesian
product and are often called ``relations''.

Most operations are declared for general mappings and therefore this manual
often  refers to ``(general) mappings'', unless you deliberately need the
generalization you can ignore the ``general'' bit and just read
it as ``mappings''.

A *general mapping* $F$ in {\GAP} is described by
its source $S$, its range $R$, and a subset $Rel$ of the direct product
$S \times R$, which is called the underlying relation of $F$.
$S$, $R$, and $Rel$ are generalized domains (see Chapter~"Domains").
The corresponding attributes for general mappings are `Source', `Range',
and `UnderlyingRelation'.

Note that general mappings themselves are *not* domains.
One reason for this is that two general mappings with same underlying
relation are regarded as equal only if also the sources are equal and
the ranges are equal.
Other, more technical, reasons are that general mappings and domains
have different basic operations, and that general mappings are
arithmetic objects (see~"Arithmetic Operations for General Mappings");
both should not apply to domains.

Each element of an underlying relation of a general mapping lies in the
category of tuples (see~"IsTuple").

For each $s \in S$, the set $\{ r \in R | (s,r) \in Rel \}$
is called the set of *images* of $s$.
Analogously, for $r \in R$, the set $\{ s \in S | (s,r) \in Rel \}$
is called the set of *preimages* of $r$.

The *ordering* of general mappings via `\<' is defined by the ordering
of source, range, and underlying relation. Specifically, if the Source
and Range domains of <map1> and <map2> are the same, then one considers 
the union of the preimages of <map1> and <map2> as a strictly ordered set.
The smaller of <map1> and <map2> is the one whose image is smaller on the 
first point of this sequence where they differ.



For mappings which preserve an algebraic structure a *kernel* is defined.
Depending on the structure preserved the operation to compute this kernel is
called differently, see section~"Mappings which are Compatible with Algebraic
Structures".

Some technical details of general mappings are described in section~"General
Mappings".

\>IsTuple( <obj> ) C

`IsTuple' is a subcategory of the meet of `IsDenseList'
(see~"IsDenseList"), `IsMultiplicativeElementWithInverse'
(see~"IsMultiplicativeElementWithInverse"),
and `IsAdditiveElementWithInverse' (see~"IsAdditiveElementWithInverse"),
where the arithmetic operations (addition, zero, additive inverse,
multiplication, powering, one, inverse) are defined componentwise.

Note that each of these operations will cause an error message if
its result for at least one component cannot be formed.

The sum and the product of a tuple and a list in `IsListDefault' is the
list of sums and products, respectively.
The sum and the product of a tuple and a non-list is the tuple of
componentwise sums and products, respectively.



%%  The general support for mappings is due to Thomas Breuer.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Creating Mappings}

\>GeneralMappingByElements( <S>, <R>, <elms> ) F

is the general mapping with source <S> and range <R>,
and with underlying relation consisting of the tuples collection <elms>.


\>MappingByFunction( <S>, <R>, <fun> ) F
\>MappingByFunction( <S>, <R>, <fun>, <invfun> ) F
\>MappingByFunction( <S>, <R>, <fun>, `false', <prefun> ) F

`MappingByFunction' returns a mapping <map> with source <S> and range
<R>, such that each element <s> of <S> is mapped to the element
`<fun>( <s> )', where <fun> is a {\GAP} function.

If the argument <invfun> is bound then <map> is a bijection between <S>
and <R>, and the preimage of each element <r> of <R> is given by
`<invfun>( <r> )', where <invfun> is a {\GAP}  function.

In the third variant, a function <prefun> is given that can be used to
compute a single preimage. In this case, the third entry must be
`false'.

`MappingByFunction' creates a mapping which `IsNonSPGeneralMapping'
            


\>InverseGeneralMapping( <map> ) A

The *inverse general mapping* of a general mapping <map> is the general
mapping whose underlying relation (see~"UnderlyingRelation") contains a
pair $(r,s)$ if and only if the underlying relation of <map> contains
the pair $(s,r)$.

See the introduction to Chapter~"Mappings" for the subtleties concerning
the difference between `InverseGeneralMapping' and `Inverse'.

Note that the inverse general mapping of a mapping <map> is in general
only a general mapping.
If <map> knows to be bijective its inverse general mapping will know to
be a mapping.
In this case also `Inverse( <map> )' works.



\>CompositionMapping( <map1>, <map2>, ... ) F

`CompositionMapping' allows one to compose arbitrarily many general
mappings, and delegates each step to `CompositionMapping2'.

Additionally, the properties `IsInjective' and `IsSingleValued' are
maintained; if the source of the $i+1$-th general mapping is identical to
the range of the $i$-th general mapping, also `IsTotal' and
`IsSurjective' are maintained.
(So one should not call `CompositionMapping2' directly if one wants to
maintain these properties.)

Depending on the types of <map1> and <map2>, the returned mapping might
be constructed completely new (for example by giving domain generators
and their images, this is for example the case if both mappings preserve
the same alagebraic structures and {\GAP} can decompose elements of the
source of <map2> into generators) or as an (iterated) composition
(see~"IsCompositionMappingRep").

\>CompositionMapping2( <map2>, <map1> ) O

`CompositionMapping2' returns the composition of <map2> and <map1>,
this is the general mapping that maps an element first under <map1>,
and then maps the images under <map2>.

(Note the reverse ordering of arguments in the composition via `\*'.


\>IsCompositionMappingRep( <map> ) R

Mappings in this representation are stored as composition of two
mappings, (pre)images of elements are computed in a two-step process.
The constituent mappings of the composition can be obtained via
`ConstituentsCompositionMapping'.

\>ConstituentsCompositionMapping( <map> ) F

If <map> is stored in the representation `IsCompositionMappingRep' as
composition of two mappings <map1> and <map2>, this function returns the
two constituent mappings in a list [<map1>,<map2>].


\>ZeroMapping( <S>, <R> ) O

A zero mapping is a total general mapping that maps each element of its
source to the zero element of its range.

(Each mapping with empty source is a zero mapping.)


\>IdentityMapping( <D> ) A

is the bijective mapping with source and range equal to the collection
<D>, which maps each element of <D> to itself.


\>Embedding( <S>, <T> ) O
\>Embedding( <S>, <i> ) O

returns the embedding of the domain <S> in the  domain  <T>,  or  in  the
second form, some domain indexed by the positive integer <i>. The precise
natures of the various methods are described elsewhere: for Lie algebras,
see~`LieFamily' ("LieFamily"); for group  products,  see~"Embeddings  and
Projections for  Group  Products"  for  a  general  description,  or  for
examples see~"Direct Products" for direct products, "Semidirect Products"
for semidirect products, or~"Wreath Products" for wreath products; or for
magma rings see~"Natural Embeddings related to Magma Rings".


\>Projection( <S>, <T> ) O
\>Projection( <S>, <i> ) O
\>Projection( <S> ) O

returns the projection of the domain <S> onto the domain <T>, or  in  the
second form, some domain indexed by the positive integer <i>, or  in  the
third form some natural subdomain of <S>. Various methods are defined for
group products; see~"Embeddings and Projections for Group Products" for a
general description, or for examples  see~"Direct  Products"  for  direct
products,  "Semidirect  Products"  for  semidirect  products,  "Subdirect
Products"  for  subdirect  products,  or~"Wreath  Products"  for   wreath
products.



\>RestrictedMapping( <map>, <subdom> ) O

If <subdom> is a subdomain of the source of the general mapping <map>,
this operation returns the restriction of <map> to <subdom>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Properties and Attributes of (General) Mappings}

\>IsTotal( <map> ) P

is `true' if each element in the source $S$ of the general mapping <map>
has images, i.e.,
$s^{<map>} \not= \emptyset$ for all $s\in S$,
and `false' otherwise.


\>IsSingleValued( <map> ) P

is `true' if each element in the source $S$ of the general mapping <map>
has at most one image, i.e.,
$|s^{<map>}| \leq 1$ for all $s\in S$,
and `false' otherwise.

Equivalently, `IsSingleValued( <map> )' is `true' if and only if
the preimages of different elements in $R$ are disjoint.


\>IsMapping( <map> ) P

A *mapping* <map> is a general mapping that assigns to each element `elm'
of its source a unique element `Image( <map>, <elm> )' of its range.

Equivalently, the general mapping <map> is a mapping if and only if it is
total and single-valued (see~"IsTotal", "IsSingleValued").


\>IsInjective( <map> ) P

is `true' if the images of different elements in the source $S$ of the
general mapping <map> are disjoint, i.e.,
$x^{<map>} \cap y^{<map>} = \emptyset$ for $x\not= y\in S$,
and `false' otherwise.

Equivalently, `IsInjective( <map> )' is `true' if and only if each
element in the range of <map> has at most one preimage in $S$.


\>IsSurjective( <map> ) P

is `true' if each element in the range $R$ of the general mapping <map>
has preimages in the source $S$ of <map>, i.e.,
$\{ s\in S \mid x\in s^{<map>} \} \not= \emptyset$ for all $x\in R$,
and `false' otherwise.


\>IsBijective( <map> ) P

A general mapping <map> is *bijective* if and only if it is an injective
and surjective mapping (see~"IsMapping", "IsInjective", "IsSurjective").



\>Range( <map> ) A


\>Source( <map> ) A


\>UnderlyingRelation( <map> ) A

The *underlying relation* of a general mapping <map> is the domain
of pairs $(s,r)$, with $s$ in the source and $r$ in the range of <map>
(see~"Source", "Range"), and $r\in$`ImagesElm( <map>, $s$ )'.

Each element of the underlying relation is a tuple (see~"IsTuple").


\>UnderlyingGeneralMapping( <map> ) A

attribute for underlying relations of general mappings




%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Images under Mappings}

\>ImagesSource( <map> ) A

is the set of images of the source of the general mapping <map>.

`ImagesSource' delegates to `ImagesSet',
it is introduced only to store the image of <map> as attribute value.


\>ImagesRepresentative( <map>, <elm> ) O

If <elm> is an element of the source of the general mapping <map> then
`ImagesRepresentative' returns either a representative of the set of
images of <elm> under <map> or `fail', the latter if and only if <elm>
has no images under <map>.

Anything may happen if <elm> is not an element of the source of <map>.


\>ImagesElm( <map>, <elm> ) O

If <elm> is an element of the source of the general mapping <map> then
`ImagesElm' returns the set of all images of <elm> under <map>.

Anything may happen if <elm> is not an element of the source of <map>.


\>ImagesSet( <map>, <elms> ) O

If <elms> is a subset of the source of the general mapping <map> then
`ImagesSet' returns the set of all images of <elms> under <map>.

Anything may happen if <elms> is not a subset of the source of <map>.


\>ImageElm( <map>, <elm> ) O

If <elm> is an element of the source of the total and single-valued
mapping <map> then
`ImageElm' returns the unique image of <elm> under <map>.

Anything may happen if <elm> is not an element of the source of <map>.


\>Image( <map> ) F
\>Image( <map>, <elm> ) F
\>Image( <map>, <coll> ) F

`Image( <map> )' is the image of the general mapping <map>, i.e.,
the subset of elements of the range of <map> that are actually values of
<map>.
Note that in this case the argument may also be multi-valued.

`Image( <map>, <elm> )' is the image of the element <elm> of the source
of the mapping <map> under <map>, i.e., the unique element of the range
to which <map> maps <elm>.
This can also be expressed as `<elm> ^ <map>'.
Note that <map> must be total and single valued, a multi valued general
mapping is not allowed (see~"Images").

`Image( <map>, <coll> )' is the image of the subset <coll> of the source
of the mapping <map> under <map>, i.e., the subset of the range
to which <map> maps elements of <coll>.
<coll> may be a proper set or a domain.
The result will be either a proper set or a domain.
Note that in this case <map> may also be multi-valued.
(If <coll> and the result are lists then the positions of
entries do in general *not* correspond.)

`Image' delegates to `ImagesSource' when called with one argument,
and to `ImageElm' resp. `ImagesSet' when called with two arguments.

If the second argument is not an element or a subset of the source of
the first argument, an error is signalled.


\>Images( <map> ) F
\>Images( <map>, <elm> ) F
\>Images( <map>, <coll> ) F

`Images( <map> )' is the image of the general mapping <map>, i.e.,
the subset of elements of the range of <map> that are actually values of
<map>.

`Images( <map>, <elm> )' is the set of images of the element <elm> of
the source of the general mapping <map> under <map>, i.e., the set of
elements of the range to which <map> maps <elm>.

`Images( <map>, <coll> )' is the set of images of the subset <coll> of
the source of the general mapping <map> under <map>, i.e., the subset
of the range to which <map> maps elements of <coll>.
<coll> may be a proper set or a domain.
The result will be either a proper set or a domain.
(If <coll> and the result are lists then the positions of
entries do in general *not* correspond.)

`Images' delegates to `ImagesSource' when called with one argument,
and to `ImagesElm' resp. `ImagesSet' when called with two arguments.

If the second argument is not an element or a subset of the source of
the first argument, an error is signalled.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Preimages under Mappings}

\>PreImagesRange( <map> ) A

is the set of preimages of the range of the general mapping <map>.

`PreImagesRange' delegates to `PreImagesSet',
it is introduced only to store the preimage of <map> as attribute value.


\>PreImagesElm( <map>, <elm> ) O

If <elm> is an element of the range of the general mapping <map> then
`PreImagesElm' returns the set of all preimages of <elm> under <map>.

Anything may happen if <elm> is not an element of the range of <map>.


\>PreImageElm( <map>, <elm> ) O

If <elm> is an element of the range of the injective and surjective
general mapping <map> then
`PreImageElm' returns the unique preimage of <elm> under <map>.

Anything may happen if <elm> is not an element of the range of <map>.


\>PreImagesRepresentative( <map>, <elm> ) O


If <elm> is an element of the range of the general mapping <map> then
`PreImagesRepresentative' returns either a representative of the set of
preimages of <elm> under <map> or `fail', the latter if and only if <elm>
has no preimages under <map>.

Anything may happen if <elm> is not an element of the range of <map>.


\>PreImagesSet( <map>, <elms> ) O

If <elms> is a subset of the range of the general mapping <map> then
`PreImagesSet' returns the set of all preimages of <elms> under <map>.

Anything may happen if <elms> is not a subset of the range of <map>.


\>PreImage( <map> ) F
\>PreImage( <map>, <elm> ) F
\>PreImage( <map>, <coll> ) F

`PreImage( <map> )' is the preimage of the general mapping <map>, i.e.,
the subset of elements of the source of <map> that actually have values
under <map>.
Note that in this case the argument may also be non-injective or
non-surjective.

`PreImage( <map>, <elm> )' is the preimage of the element <elm> of the
range of the injective and surjective mapping <map> under <map>, i.e.,
the unique element of the source which is mapped under <map> to <elm>.
Note that <map> must be injective and surjective (see~"PreImages").

`PreImage( <map>, <coll> )' is the preimage of the subset <coll> of the
range of the general mapping <map> under <map>, i.e., the subset of the
source which is mapped under <map> to elements of <coll>.
<coll> may be a proper set or a domain.
The result will be either a proper set or a domain.
Note that in this case <map> may also be non-injective or
non-surjective.
(If <coll> and the result are lists then the positions of
entries do in general *not* correspond.)

`PreImage' delegates to `PreImagesRange' when called with one argument,
and to `PreImageElm' resp. `PreImagesSet' when called with two arguments.

If the second argument is not an element or a subset of the range of
the first argument, an error is signalled.


\>PreImages( <map> ) F
\>PreImages( <map>, <elm> ) F
\>PreImages( <map>, <coll> ) F

`PreImages( <map> )' is the preimage of the general mapping <map>, i.e.,
the subset of elements of the source of <map> that have actually values
under <map>.

`PreImages( <map>, <elm> )' is the set of preimages of the element <elm>
of the range of the general mapping <map> under <map>, i.e., the set of
elements of the source which <map> maps to <elm>.

`PreImages( <map>, <coll> )' is the set of images of the subset <coll> of
the range of the general mapping <map> under <map>, i.e., the subset
of the source which <map> maps to elements of <coll>.
<coll> may be a proper set or a domain.
The result will be either a proper set or a domain.
(If <coll> and the result are lists then the positions of
entries do in general *not* correspond.)

`PreImages' delegates to `PreImagesRange' when called with one argument,
and to `PreImagesElm' resp. `PreImagesSet' when called with two
arguments.

If the second argument is not an element or a subset of the range of
the first argument, an error is signalled.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Arithmetic Operations for General Mappings}

General mappings are arithmetic objects.
One can form groups and vector spaces of general mappings provided
that they are invertible or can be added and admit scalar multiplication,
respectively.

For two general mappings with same source, range, preimage, and image,
the *sum* is defined pointwise, i.e., the images of a point under the sum
is the set of all sums with first summand in the images of the first
general mapping and second summand in the images of the second general
mapping.

*Scalar multiplication* of general mappings is defined likewise.

The *product* of two general mappings is defined as the composition.
This multiplication is always associative.
In addition to the composition via `\*', general mappings can be composed
--in reversed order-- via `CompositionMapping'.

General mappings are in the category of multiplicative elements with
inverses.
Similar to matrices, not every general mapping has an inverse or an
identity, and we define the behaviour of `One' and `Inverse' for
general mappings as follows.
`One' returns `fail' when called for a general mapping whose source and
range differ, otherwise `One' returns the identity mapping of the source.
(Note that the source may differ from the preimage).
`Inverse' returns `fail' when called for a non-bijective general mapping
or for a general mapping whose source and range differ; otherwise
`Inverse' returns the inverse mapping.

Besides the usual inverse of multiplicative elements, which means that
`Inverse( <g> ) \* <g> = <g> \* Inverse( <g> ) = One( <g> )',
for general mappings we have the attribute `InverseGeneralMapping'.
If <F> is a general mapping with source $S$, range $R$, and underlying
relation $Rel$ then `InverseGeneralMapping( <F> )' has source $R$,
range $S$, and underlying relation $\{ (r,s) \mid (s,r) \in Rel \}$.
For a general mapping that has an inverse in the usual sense,
i.e., for a bijection of the source, of course both concepts coincide.

`Inverse' may delegate to `InverseGeneralMapping'.
`InverseGeneralMapping' must not delegate to `Inverse', but a known
value of `Inverse' may be fetched.
So methods to compute the inverse of a general mapping should be
installed for `InverseGeneralMapping'.

(Note that in many respects, general mappings behave similar to matrices,
for example one can define left and right identities and inverses, which
do not fit into the current concepts of {\GAP}.)



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Mappings which are Compatible with Algebraic Structures}

From an algebraical point of view, the most important mappings are those
which are compatible with a structure. For Magmas, Groups and Rings, {\GAP}
supports the following four types of such mappings:

1. General mappings that respect multiplication

2. General mappings that respect addition

3. General mappings that respect scalar mult.

4. General mappings that respect multiplicative and additive structure

(Very technical note: GAP defines categories `IsSPGeneralMapping' and
`IsNonSPGeneralMapping'. The distinction between these is orthogonal to the
Structure Compatibility described here and should not be confused.)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Magma Homomorphisms}

\>IsMagmaHomomorphism( <mapp> ) P

A `MagmaHomomorphism' is a total single valued mapping which respects 
multiplication.


\>MagmaHomomorphismByFunctionNC( <G>, <H>, <fn> ) F

Creates the homomorphism from G to H without checking
that <fn> is a homomorphism.


\>NaturalHomomorphismByGenerators( <f>, <s> ) O

returns a mapping from the magma <f> with <n> generators to the
magma <s> with <n> generators, which maps the ith generator of <f> to the 
ith generator of <s>.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Mappings that Respect Multiplication}

\>RespectsMultiplication( <mapp> ) P

Let <mapp> be a general mapping with underlying relation
$F \subseteq S \times R$,
where $S$ and $R$ are the source and the range of <mapp>, respectively.
Then `RespectsMultiplication' returns `true' if
$S$ and $R$ are magmas such that
$(s_1,r_1), (s_2,r_2) \in F$ implies $(s_1 \* s_2,r_1 \* r_2) \in F$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsMultiplication' returns `true'
if and only if the equation
`<s1>^<mapp> * <s2>^<mapp> = (<s1>*<s2>)^<mapp>'
holds for all <s1>, <s2> in $S$.


\>RespectsOne( <mapp> ) P

Let <mapp> be a general mapping with underlying relation
$F \subseteq <S> \times <R>$,
where <S> and <R> are the source and the range of <mapp>, respectively.
Then `RespectsOne' returns `true' if
<S> and <R> are magmas-with-one such that
$( `One(<S>)', `One(<R>)' ) \in F$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsOne' returns `true'
if and only if the equation
`One( <S> )^<mapp> = One( <R> )'
holds.


\>RespectsInverses( <mapp> ) P

Let <mapp> be a general mapping with underlying relation
$F \subseteq <S> \times <R>$,
where <S> and <R> are the source and the range of <mapp>, respectively.
Then `RespectsInverses' returns `true' if
<S> and <R> are magmas-with-inverses such that,
for $s \in <S>$ and $r \in <R>$, 
$(s,r) \in F$ implies $(s^{-1},r^{-1}) \in F$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsInverses' returns `true'
if and only if the equation
`Inverse( <s> )^<mapp> = Inverse( <s>^<mapp> )'
holds for all <s> in $S$.


Mappings that are defined on a group and respect multiplication and inverses
are group homomorphisms. Chapter~"Group Homomorphisms" explains them in more
detail.

\>IsGroupGeneralMapping( <mapp> ) P
\>IsGroupHomomorphism( <mapp> ) P

A `GroupGeneralMapping' is a mapping which respects multiplication and
inverses. If it is total and single valued it is called a group
homomorphism.



\>KernelOfMultiplicativeGeneralMapping( <mapp> ) A

Let <mapp> be a general mapping.
Then `KernelOfMultiplicativeGeneralMapping' returns the set of all
elements in the source of <mapp> that have the identity of the range in
their set of images.

(This is a monoid if <mapp> respects multiplication and one,
and if the source of <mapp> is associative.)


\>CoKernelOfMultiplicativeGeneralMapping( <mapp> ) A

Let <mapp> be a general mapping.
Then `CoKernelOfMultiplicativeGeneralMapping' returns the set of all
elements in the range of <mapp> that have the identity of the source in
their set of preimages.

(This is a monoid if <mapp> respects multiplication and one,
and if the range of <mapp> is associative.)



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Mappings that Respect Addition}

\>RespectsAddition( <mapp> ) P

Let <mapp> be a general mapping with underlying relation
$F \subseteq S \times R$,
where $S$ and $R$ are the source and the range of <mapp>, respectively.
Then `RespectsAddition' returns `true' if
$S$ and $R$ are additive magmas such that
$(s_1,r_1), (s_2,r_2) \in F$ implies $(s_1 + s_2,r_1 + r_2) \in F$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsAddition' returns `true'
if and only if the equation
`<s1>^<mapp> + <s2>^<mapp> = (<s1>+<s2>)^<mapp>'
holds for all <s1>, <s2> in $S$.


\>RespectsAdditiveInverses( <mapp> ) P

Let <mapp> be a general mapping with underlying relation
$F \subseteq S \times R$,
where $S$ and $R$ are the source and the range of <mapp>, respectively.
Then `RespectsAdditiveInverses' returns `true' if
$S$ and $R$ are additive-magmas-with-inverses such that
$(s,r) \in F$ implies $(-s,-r) \in F$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsAdditiveInverses' returns `true'
if and only if the equation
`AdditiveInverse( <s> )^<mapp> = AdditiveInverse( <s>^<mapp> )'
holds for all <s> in $S$.


\>RespectsZero( <mapp> ) P

Let <mapp> be a general mapping with underlying relation
$F \subseteq <S> \times <R>$,
where <S> and <R> are the source and the range of <mapp>, respectively.
Then `RespectsZero' returns `true' if
<S> and <R> are additive-magmas-with-zero such that
$( `Zero(<S>)', `Zero(<R>)' ) \in F$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsZero' returns `true'
if and only if the equation
`Zero( <S> )^<mapp> = Zero( <R> )'
holds.


\>IsAdditiveGroupGeneralMapping( <mapp> ) P
\>IsAdditiveGroupHomomorphism( <mapp> ) P


\>KernelOfAdditiveGeneralMapping( <mapp> ) A

Let <mapp> be a general mapping.
Then `KernelOfAdditiveGeneralMapping' returns the set of all
elements in the source of <mapp> that have the zero of the range in
their set of images.


\>CoKernelOfAdditiveGeneralMapping( <mapp> ) A

Let <mapp> be a general mapping.
Then `CoKernelOfAdditiveGeneralMapping' returns the set of all
elements in the range of <mapp> that have the zero of the source in
their set of preimages.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Linear Mappings}

Also see Sections~"Mappings that Respect Multiplication" and~"Mappings that
Respect Addition".

\>RespectsScalarMultiplication( <mapp> ) P

Let <mapp> be a general mapping, with underlying relation
$F \subseteq S \times R$,
where $S$ and $R$ are the source and the range of <mapp>, respectively.
Then `RespectsScalarMultiplication' returns `true' if
$S$ and $R$ are left modules with the left acting domain $D$ of $S$
contained in the left acting domain of $R$ and such that
$(s,r) \in F$ implies $(c \* s,c \* r) \in F$ for all $c \in D$,
and `false' otherwise.

If <mapp> is single-valued then `RespectsScalarMultiplication' returns
`true' if and only if the equation
`<c> \* <s>^<mapp> = (<c> \* <s>)^<mapp>'
holds for all <c> in $D$ and <s> in $S$.


\>IsLeftModuleGeneralMapping( <mapp> ) P
\>IsLeftModuleHomomorphism( <mapp> ) P


\>IsLinearMapping( <F>, <mapp> ) O

For a field <F> and a general mapping <mapp>, `IsLinearMapping' returns
`true' if <mapp> is an <F>-linear mapping, and `false' otherwise.

A mapping $f$ is a linear mapping (or vector space homomorphism) if
the source and range are vector spaces over the same division ring $D$,
and if $f( a + b ) = f(a) + f(b)$ and $f( s \* a ) = s \* f(a)$ hold
for all elements $a$, $b$ in the source of $f$ and $s \in D$.



See also `KernelOfMultiplicativeGeneralMapping'
("KernelOfMultiplicativeGeneralMapping") and
`CoKernelOfMultiplicativeGeneralMapping'
("CoKernelOfMultiplicativeGeneralMapping").

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Ring Homomorphisms}

\>IsRingGeneralMapping( <mapp> ) P
\>IsRingHomomorphism( <mapp> ) P


\>IsRingWithOneGeneralMapping( <mapp> ) P
\>IsRingWithOneHomomorphism( <mapp> ) P


\>IsAlgebraGeneralMapping( <mapp> ) P
\>IsAlgebraHomomorphism( <mapp> ) P


\>IsAlgebraWithOneGeneralMapping( <mapp> ) P
\>IsAlgebraWithOneHomomorphism( <mapp> ) P


\>IsFieldHomomorphism( <mapp> ) P

A general mapping is a field homomorphism if and only if it is
a ring homomorphism with source a field.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{General Mappings}

\>IsGeneralMapping( <map> ) C

Each general mapping lies in the category `IsGeneralMapping'.
It implies the categories `IsMultiplicativeElementWithInverse'
(see~"IsMultiplicativeElementWithInverse")
and `IsAssociativeElement' (see~"IsAssociativeElement");
for a discussion of these implications,
see~"Arithmetic Operations for General Mappings".


\>IsConstantTimeAccessGeneralMapping( <map> ) P

is `true' if the underlying relation of the general mapping <map>
knows its `AsList' value, and `false' otherwise.

In the former case, <map> is allowed to use this list for calls to
`ImagesElm' etc.


\>IsEndoGeneralMapping( <obj> ) P

If a general mapping has this property then its source and range are
equal.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Technical Matters Concerning General Mappings}

`Source' and `Range' are basic operations for general mappings.
`UnderlyingRelation' is secondary, its default method sets up a
domain that delegates tasks to the general mapping.
(Note that this allows one to handle also infinite relations by generic
methods if source or range of the general mapping is finite.)

The distinction between basic operations and secondary operations for
general mappings may be a little bit complicated.
Namely, each general mapping must be in one of the two categories
`IsNonSPGeneralMapping', `IsSPGeneralMapping'.
(The category `IsGeneralMapping' is defined as the disjoint union
of these two.)

For general mappings of the first category, `ImagesElm' and
`PreImagesElm' are basic operations.
(Note that in principle it is possible to delegate from `PreImagesElm'
to `ImagesElm'.)
Methods for the secondary operations `(Pre)ImageElm', `(Pre)ImagesSet',
and `(Pre)ImagesRepresentative' may use `(Pre)ImagesElm',
and methods for `(Pre)ImagesElm' must not call the secondary operations.
In particular, there are no generic methods for `(Pre)ImagesElm'.

Methods for `(Pre)ImagesSet' must *not* use `PreImagesRange' and
`ImagesSource', e.g., compute the intersection of the set in question
with the preimage of the range resp. the image of the source.

For general mappings of the second category (which means structure
preserving general mappings), the situation is different.
The set of preimages under a group homomorphism, for example, is either
empty or can be described as a coset of the (multiplicative) kernel.
So it is reasonable to have `(Pre)ImagesRepresentative' and
`Multplicative(Co)Kernel' as basic operations here,
and to make `(Pre)ImagesElm' secondary operations
that may delegate to these.

In order to avoid infinite recursions,
we must distinguish between the two different types of mappings.

(Note that the basic domain operations such as `AsList' for the
underlying relation of a general mapping may use either `ImagesElm'
or `ImagesRepresentative' and the appropriate cokernel.
Conversely, if `AsList' for the underlying relation is known then
`ImagesElm' resp. `ImagesRepresentative' may delegate to it, the general
mapping gets the property `IsConstantTimeAccessGeneralMapping' for this;
note that this is not allowed if only an enumerator of the underlying
relation is known.)

Secondary operations are
`IsInjective', `IsSingleValued', `IsSurjective', `IsTotal';
they may use the basic operations, and must not be used by them.



\>IsSPGeneralMapping( <map> ) C
\>IsNonSPGeneralMapping( <map> ) C




\>IsGeneralMappingFamily( <obj> ) C


\>FamilyRange( <Fam> ) A

is the elements family of the family of the range of each general
mapping in the family <Fam>.


\>FamilySource( <Fam> ) A

is the elements family of the family of the source of each general
mapping in the family <Fam>.


\>FamiliesOfGeneralMappingsAndRanges( <Fam> ) AM

is a list that stores at the odd positions the families of general
mappings with source in the family <Fam>, at the even positions the
families of ranges of the general mappings.


\>GeneralMappingsFamily( <sourcefam>, <rangefam> ) F

All general mappings with same source family <FS> and same range family
<FR> lie in the family `GeneralMappingsFamily( <FS>, <FR> )'.


\>TypeOfDefaultGeneralMapping( <source>, <range>, <filter> ) F

is the type of mappings with `IsDefaultGeneralMappingRep' with source
<source> and range <range> and additional categories <filter>.



Methods for the operations `ImagesElm', `ImagesRepresentative',
`ImagesSet', `ImageElm', `PreImagesElm', `PreImagesRepresentative',
`PreImagesSet', and `PreImageElm' take two arguments, a general mapping
<map> and an element or collection of elements <elm>.
These methods must *not* check whether <elm> lies in the source or the
range of <map>.
In the case that <elm> does not, `fail' may be returned as well as any
other {\GAP} object, and even an error message is allowed.
Checks of the arguments are done only by the functions `Image', `Images',
`PreImage', and `PreImages', which then delegate to the operations listed
above.



%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%E