This is SwitchingFields.info, produced by Macaulay2, version 1.20

SwitchingFields -- Switch base fields and obtain natural maps for rings over finite fields
******************************************************************************************

Description
===========

SwitchingFields is a package that helps to switch the (finite) field of
coefficients of a given ring, to another given (finite) field via the natural
map between these fields.

Authors
=======

  * Zhan Jiang (see http://www-personal.umich.edu/~zoeng/ ) <zoeng@umich.edu>
  * Sarasij Maitra (see https://people.virginia.edu/~sm3vg )
    <sm3vg@virginia.edu>

Version
=======

This documentation describes version 1.0 of SwitchingFields.

Source code
===========

The source code from which this documentation is derived is in the file
SwitchingFields.m2 (see common/share/Macaulay2/SwitchingFields.m2 ).

Exports
=======

  * Functions and commands
      * extendFieldByDegree (missing documentation)
      * fieldBaseChange -- a function to compute the
        base change between GaloisFields
      * fieldExtension -- a fix to the failure of
        map(GaloisField,GaloisField) function when Variable option is used
      * switchFieldMap -- a function to provide correct
        map between rings with different finite coefficient field
  * Methods
      * "fieldBaseChange(Ring,GaloisField)" -- see fieldBaseChange,
        -- a function to compute the base change between
        GaloisFields
      * "fieldExtension(GaloisField,GaloisField)" -- see fieldExtension,
        -- a fix to the failure of map(GaloisField,GaloisField)
        function when Variable option is used
      * "switchFieldMap(Ring,Ring,List)" -- see switchFieldMap,
        -- a function to provide correct map between rings with
        different finite coefficient field

For the programmer
==================

The object SwitchingFields, is a package (Macaulay2Doc).

extendFieldByDegree
*******************

Ways to use extendFieldByDegree :
=================================

  * extendFieldByDegree(ZZ,Ring) (missing documentation)

For the programmer
==================

The object extendFieldByDegree (missing documentation) is a method function with options (Macaulay2Doc).

fieldBaseChange -- a function to compute the base change between GaloisFields
*****************************************************************************

Synopsis
========

  * Usage:
        fieldBaseChange(R, K)
  * Inputs:
      * R, a ring (Macaulay2Doc), with a GaloisField $L$ as its
        coefficient ring
      * K, a Galois field (Macaulay2Doc), extension of $L$
  * Outputs:
      * a sequence (Macaulay2Doc), ($T$ ,$f$) where $T = R
        \otimes_L K$ is the base-changed ring, $f:R\to T$ is the ring map
        $R\otimes_L L\to R\otimes_L K$ induced from $L\to K$.

Description
===========

+-------------------------------------------------+
|i1 : R = GF(8)[x,y,z]/(x*y-z^2)                  |
|                                                 |
|o1 = R                                           |
|                                                 |
|o1 : QuotientRing                                |
+-------------------------------------------------+
|i2 : K = GF(64)                                  |
|                                                 |
|o2 = K                                           |
|                                                 |
|o2 : GaloisField                                 |
+-------------------------------------------------+
|i3 : (T,f) = fieldBaseChange(R,K)                |
|                                                 |
|                               5    4    2       |
|o3 = (T, map (T, R, {x, y, z, a  + a  + a  + 1}))|
|                                                 |
|o3 : Sequence                                    |
+-------------------------------------------------+
|i4 : describe T                                  |
|                                                 |
|      K[x..z]                                    |
|o4 = --------                                    |
|            2                                    |
|     x*y + z                                     |
+-------------------------------------------------+
|i5 : describe f                                  |
|                                                 |
|                           5    4    2           |
|o5 = map (T, R, {x, y, z, a  + a  + a  + 1})     |
+-------------------------------------------------+

Ways to use fieldBaseChange :
=============================

  * "fieldBaseChange(Ring,GaloisField)"

For the programmer
==================

The object fieldBaseChange, is a method function with options (Macaulay2Doc).

fieldExtension -- a fix to the failure of map(GaloisField,GaloisField) function when Variable option is used
************************************************************************************************************

Synopsis
========

  * Usage:
        fieldExtension(L, K)
  * Inputs:
      * K, a Galois field (Macaulay2Doc), a finite field
      * L, a Galois field (Macaulay2Doc), a field extension
        of $K$
  * Outputs:
      * a ring map (Macaulay2Doc), the natural ring map $K \to
        L$.

Description
===========

The usual map (Macaulay2Doc), function is not working properly when
the generators of a GaloisField (Macaulay2Doc), are
designated. For example,

+-----------------------------------------------------------------------------+
|i1 : K1 = GF(8); L1 = GF(64);                                                |
+-----------------------------------------------------------------------------+
|i3 : K2 = GF(8, Variable=>b); L2 = GF(64, Variable=>c);                      |
+-----------------------------------------------------------------------------+
|i5 : map(L1, K1) --correct natural map                                       |
|                                                                             |
|                    5    4    2                                              |
|o5 = map (L1, K1, {a  + a  + a  + 1})                                        |
|                                                                             |
|o5 : RingMap L1 <--- K1                                                      |
+-----------------------------------------------------------------------------+
|i6 : try map(L2, K2) then << "correct map" else << "error: not implemented:  |
|correct map                                                                  |
|-----------------------------------------------------------------------------|
|maps between non-Conway Galois fields";                                      |
+-----------------------------------------------------------------------------+

This function is a fix for that. See following example

+-------------------------------------------------------+
|i7 : K2 = GF(8, Variable=>b); L2 = GF(64, Variable=>c);|
+-------------------------------------------------------+
|i9 : fieldExtension(L2, K2)                            |
|                                                       |
|                    5    4    2                        |
|o9 = map (L2, K2, {c  + c  + c  + 1})                  |
|                                                       |
|o9 : RingMap L2 <--- K2                                |
+-------------------------------------------------------+

The function is implemented by composing the isomorphism $K_2\cong K_1$, the
natural embedding $K_1\to L_1$ and the isomorphism $L_1\cong L_2$.

Caveat
======

The function depends on the implementation of map(GaloisField,GaloisField).

Ways to use fieldExtension :
============================

  * "fieldExtension(GaloisField,GaloisField)"
  * fieldExtension(GaloisField,QuotientRing) (missing documentation)

For the programmer
==================

The object fieldExtension, is a method function with options (Macaulay2Doc).

switchFieldMap -- a function to provide correct map between rings with different finite coefficient field
*********************************************************************************************************

Synopsis
========

  * Usage:
        switchFieldMap(S, R, l)
  * Inputs:
      * S, a ring (Macaulay2Doc), with a GaloisField as its
        coefficientRing
      * R, a ring (Macaulay2Doc), with a GaloisField as its
        coefficientRing
      * l, a list (Macaulay2Doc), defining the map $R \to S$
  * Outputs:
      * a ring map (Macaulay2Doc), the natural ring map  $R \to
        S$

Description
===========

The usual map (Macaulay2Doc), function does not check whether the map
for the ground field is a well-defined map.

+-------------------------------------------------------+
|i1 : R = GF(8)[x,y,z]/(x*y-z^2); S = GF(64)[u,v]/(v^2);|
+-------------------------------------------------------+
|i3 : f = map(S, R, {u, 0, v})                          |
|                                                       |
|o3 = map (S, R, {u, 0, v, a})                          |
|                                                       |
|o3 : RingMap S <--- R                                  |
+-------------------------------------------------------+
|i4 : t = (coefficientRing R)_0;                        |
+-------------------------------------------------------+
|i5 : f(t^3+t+1)                                        |
|                                                       |
|o5 = 0                                                 |
|                                                       |
|o5 : S                                                 |
+-------------------------------------------------------+
|i6 : f(t)^3+f(t)+1                                     |
|                                                       |
|      3                                                |
|o6 = a  + a + 1                                        |
|                                                       |
|o6 : S                                                 |
+-------------------------------------------------------+

Our function provides a fix to this issue. See below

+-------------------------------------------------------+
|i7 : R = GF(8)[x,y,z]/(x*y-z^2); S = GF(64)[u,v]/(v^2);|
+-------------------------------------------------------+
|i9 : f = switchFieldMap(S, R, {u, 0, v})               |
|                                                       |
|                           5    4    2                 |
|o9 = map (S, R, {u, 0, v, a  + a  + a  + 1})           |
|                                                       |
|o9 : RingMap S <--- R                                  |
+-------------------------------------------------------+
|i10 : t = (coefficientRing R)_0;                       |
+-------------------------------------------------------+
|i11 : f(t)^3+f(t)+1                                    |
|                                                       |
|o11 = 0                                                |
|                                                       |
|o11 : S                                                |
+-------------------------------------------------------+

The switchFieldMap makes the user defined map compatible with the natural map
between the coefficient fields.

Ways to use switchFieldMap :
============================

  * "switchFieldMap(Ring,Ring,List)"

For the programmer
==================

The object switchFieldMap, is a method function with options (Macaulay2Doc).