<!-- 

  scalars.xml            cvec package documentation           Max Neunhoeffer

  Copyright (C) 2007  Max Neunhoeffer, Lehrstuhl D f. Math., RWTH Aachen
  This file is free software, see license information at the end.

This chapter covers the scalars, especially those for bigger finite fields.
No longer used.

-->

<Chapter Label="scalars">
<Heading>Scalars</Heading>

See Section <Ref Sect="cscas"/> for a documentation of the data format
of <C>csca</C>s and its restrictions.<P/>

<Section>
<Heading>Creation of <C>csca</C>s</Heading>

Note that many functions described later in this chapter implicitly 
create new <C>csca</C>s, such that it is relatively rarely necessary
to create <C>csca</C>s explicitly.

<ManSection>
<Oper Name="CSca" Arg="arg"/>
<Returns>a <C>csca</C></Returns>
<Description>
    Creates a new <C>csca</C>. See the method descriptions for details.
</Description>
</ManSection>

<ManSection>
<Meth Name="CSca" Arg="coeffs, cscaclass" 
      Label="coeffl_cscaclass"/>
<Returns>a <C>csca</C></Returns>
<Description>
    This method takes a coefficient list and a <C>cscaclass</C>
    as arguments. The coefficient list <A>coeffs</A> must be
    <M>[a_0,\ldots,a_{{d-1}}]</M> if the new finite field element is
    represented by the polynomial <M>\sum_{{i=0}}^{{d-1}} a_i x^i</M>,
    where the <M>a_i</M> are integers between <M>0</M> and <M>p-1</M>.
    For an explanation of the term <C>cscaclass</C> see Section <Ref
    Sect="cscas"/> and <Ref Oper="CVecClass"/>.
</Description>
</ManSection>

<ManSection>
<Meth Name="CSca" Arg="coeffs, csca" 
      Label="coeffl_csca"/>
<Returns>a <C>csca</C></Returns>
<Description>
    This method takes a coefficient list and a <C>csca</C> as arguments.
    It creates a new <C>csca</C> from the same class as <A>csca</A>
    using the coefficient list <A>coeffs</A>. The coefficient list
    <A>coeffs</A> must be <M>[a_0,\ldots,a_{{d-1}}]</M> if the new finite field
    element is represented by the polynomial <M>\sum_{{i=0}}^{{d-1}} a_i
    x^i</M>, where the <M>a_i</M> are integers between <M>0</M> and
    <M>p-1</M>.
</Description>
</ManSection>

<ManSection>
<Meth Name="CSca" Arg="coeffs, p, d" 
      Label="coeffl_p_d"/>
<Returns>a <C>csca</C></Returns>
<Description>
    This method takes a coefficient list and two integers <A>p</A> and
    <A>d</A> as arguments.
    It creates a new <C>csca</C> in the field <M>GF(<A>p</A>,<A>d</A>)</M>
    using the coefficient list <A>coeffs</A>. The coefficient list
    <A>coeffs</A> must be <M>[a_0,\ldots,a_{{d-1}}]</M> if the new finite field
    element is represented by the polynomial <M>\sum_{{i=0}}^{{d-1}} a_i
    x^i</M>, where the <M>a_i</M> are integers between <M>0</M> and
    <M>p-1</M>.
</Description>
</ManSection>

<ManSection>
<Meth Name="ZeroSameMutability" Arg="s" Label="csca"/>
<Returns>The zero <C>csca</C> in the same <C>cscaclass</C> as <A>s</A>.
</Returns>
<Description>
<A>s</A> must be a <C>csca</C> or a <C>cscaclass</C>.
Note that all <C>csca</C>s are by convention immutable.
</Description>
</ManSection>

<ManSection>
<Meth Name="ZeroImmutable" Arg="s" Label="csca"/>
<Returns>The zero <C>csca</C> in the same <C>cscaclass</C> as <A>s</A>.
</Returns>
<Description>
<A>s</A> must be a <C>csca</C> or a <C>cscaclass</C>.
Note that all <C>csca</C>s are by convention immutable.
</Description>
</ManSection>

<ManSection>
<Meth Name="OneSameMutability" Arg="s" Label="csca"/>
<Returns>The one <C>csca</C> in the same <C>cscaclass</C> as <A>s</A>.
</Returns>
<Description>
<A>s</A> must be a <C>csca</C> or a <C>cscaclass</C>.
Note that all <C>csca</C>s are by convention immutable.
</Description>
</ManSection>

<ManSection>
<Meth Name="OneImmutable" Arg="s" Label="csca"/>
<Returns>The one <C>csca</C> in the same <C>cscaclass</C> as <A>s</A>.
</Returns>
<Description>
<A>s</A> must be a <C>csca</C> or a <C>cscaclass</C>.
Note that all <C>csca</C>s are by convention immutable.
</Description>
</ManSection>

<ManSection>
<Meth Name="PrimitiveRoot" Arg="s" Label="csca"/>
<Returns>The <C>csca</C> represented by the polynomial <M>x</M> in the 
same <C>cscaclass</C> as <A>s</A>.
</Returns>
<Description>
<A>s</A> must be a <C>csca</C> or a <C>cscaclass</C>.
The definition of Conway polynomials ensures that the returned element
is a primitive root.
Note that all <C>csca</C>s are by convention immutable.
</Description>
</ManSection>

</Section>

<Section>
<Heading>Arithmetic</Heading>

Of course, the standard arithmetic infix operations <M>+</M>, <M>-</M>,
<M>*</M> and <M>/</M> work as expected by using the following methods:

<ManSection>
<Meth Name="\+" Arg="s, t" Label="csca_csca"/>
<Returns>The sum <M><A>s</A>+<A>t</A></M> as a <C>csca</C>.</Returns>
<Description>
    For two <C>csca</C>s <A>s</A> and <A>t</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\-" Arg="s, t" Label="csca_csca"/>
<Returns>The difference <M><A>s</A>-<A>t</A></M> as a <C>csca</C>.</Returns>
<Description>
    For two <C>csca</C>s <A>s</A> and <A>t</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\*" Arg="s, t" Label="csca_csca"/>
<Returns>The product <M><A>s</A> \cdot <A>t</A></M> as a <C>csca</C>.</Returns>
<Description>
    For two <C>csca</C>s <A>s</A> and <A>t</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\/" Arg="s, t" Label="csca_csca"/>
<Returns>The quotient <M><A>s</A>/<A>t</A></M> as a <C>csca</C>.</Returns>
<Description>
    For two <C>csca</C>s <A>s</A> and <A>t</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="AdditiveInverseSameMutability" Arg="s" Label="csca"/>
<Returns>The additive inverse of <A>s</A> as a <C>csca</C>.</Returns>
<Description>
For a <C>csca</C> <A>s</A>. Works as expected.
Note that all <C>csca</C>s are immutable by convention.
</Description>
</ManSection>

<ManSection>
<Meth Name="AdditiveInverseImmutable" Arg="s" Label="csca"/>
<Returns>The additive inverse of <A>s</A> as a <C>csca</C>.</Returns>
<Description>
For a <C>csca</C> <A>s</A>. Works as expected.
Note that all <C>csca</C>s are immutable by convention.
</Description>
</ManSection>

<ManSection>
<Meth Name="InverseSameMutability" Arg="s" Label="csca"/>
<Returns>The multiplicative inverse of <A>s</A> as a <C>csca</C>.</Returns>
<Description>
For a <C>csca</C> <A>s</A>. Works as expected.
Note that all <C>csca</C>s are immutable by convention.
</Description>
</ManSection>

<ManSection>
<Meth Name="InverseImmutable" Arg="s" Label="csca"/>
<Returns>The multiplicative inverse of <A>s</A> as a <C>csca</C>.</Returns>
<Description>
For a <C>csca</C> <A>s</A>. Works as expected.
Note that all <C>csca</C>s are immutable by convention.
</Description>
</ManSection>

</Section>

<Section>
<Heading>Comparison</Heading>

<ManSection>
<Meth Name="\=" Arg="s, t" Label="csca_csca"/>
<Returns>A boolean value indicating, whether <A>s</A> and <A>t</A> are equal
    or not.</Returns>
<Description>
    For two <C>csca</C>s <A>s</A> and <A>t</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="\&lt;" Arg="s, t" Label="csca_csca"/>
<Returns>A boolean value indicating, whether <A>s</A> is smaller than <A>t</A>
    or not.</Returns>
<Description>
    For two <C>csca</C>s <A>s</A> and <A>t</A>. This method implements
    lexicographic ordering of coefficient lists as stored in the internal
    format (see Section <Ref Sect="cscas"/>) and only applies for <C>csca</C>s
    over the same finite field.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsZero" Arg="s" Label="csca"/>
<Returns>A boolean value indicating, whether <A>s</A> is equal to zero
    or not.</Returns>
<Description>
    For a <C>csca</C>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="IsOne" Arg="s" Label="csca"/>
<Returns>A boolean value indicating, whether <A>s</A> is equal to one
    or not.</Returns>
<Description>
    For a <C>csca</C>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="Sqrt" Arg="s" Label="csca"/>
<Returns>A square root of <A>s</A> or <C>fail</C> if none exists.</Returns>
<Description>
    For a <C>csca</C>. Works as expected. This method is quite efficient
    and uses the algorithm described in <Cite Key="highspeed"/>.
</Description>
</ManSection>

Note that <M>r</M>th roots for higher <M>r</M> are possible to do with 
a similar approach as long as the prime factors of <M>r</M> do not
become big, but this is not yet implemented.

</Section>

<Section>
<Heading>Access to the base field</Heading>

<ManSection>
<Meth Name="Characteristic" Arg="s" Label="csca"/>
<Returns>Returns the characteristic of the field of <A>s</A>.</Returns>
<Description>
    For a <C>csca</C> <A>s</A>. Works as expected.
</Description>
</ManSection>

<ManSection>
<Meth Name="DegreeFFE" Arg="s" Label="csca"/>
<Returns>Returns the degree of the field of <A>s</A> over its prime field.
</Returns>
<Description>
    For a <C>csca</C> <A>s</A>. Works as expected.
</Description>
</ManSection>

</Section>

<!-- template:
<ManSection>
<Meth Name="" Arg="" Label=""/>
<Returns></Returns>
<Description>
</Description>
</ManSection>

 -->

<P/>

<!-- ############################################################ -->

</Chapter>

<!--
  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 of the License,
  or (at your option) any later version.

  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.

  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
-->

