NAME

   Math::GF - Galois Fields arithmetics

VERSION

   This document describes Math::GF version 0.004.

SYNOPSIS

      use Math::GF;

      # prime orders leverage on Math::GF::Zn
      my $GF5 = Math::GF->new(order => 5);

      # prints "yes!" because 5 is prime
      say 'yes!' if $GF5->order_is_prime;
      # prints "order 5 = 5^1"
      say 'order ', $GF5->order, ' = ', $GF5->p, '^', $GF5->n;

      # generate some elements
      my $zero_gf5 = $GF5->additive_neutral;
      my $one_gf5  = $GF5->multiplicative_neutral;
      my $four_gf5 = $GF5->e(4);                # scalar context
      my ($two_gf5, $three_gf5) = $GF5->(2, 3); # list context

      # use some operations, both print "yes!"
      say 'yes!' if $two_gf5   == $one_gf5  + $one_gf5;
      say 'yes!' if $three_gf5 == $four_gf5 * $two_gf5;

      # non-prime orders leverage on Math::GF::Extension
      my $GF8 = Math::GF->new(order => 8);

      # prints "order not prime!"
      say 'order not prime!' unless $GF8->order_is_prime;

      # prints "order 8 = 2^3"
      say 'order ', $GF8->order, ' = ', $GF8->p, '^', $GF8->n;

      # same operations as before anyway, no change in API
      my $zero_gf8 = $GF8->additive_neutral;
      my $one_gf8  = $GF8->multiplicative_neutral;
      my ($three_gf8, $five_gf8) = $GF8->e(3, 5);

      # use some operations... no more modulo operations in GF(2^3)
      say 'yes!' if $three_gf8 * $five_gf8 == $GF8->e(4);

      # import a factory function for building elements
      Math::GF->import_builder(81, name => 'GF81'); # GF(3^4)
      say 'yes!' if GF81(5) * GF81(8) == GF81(19);

      # Need all elements? No problem
      my @all_gf27 = Math::GF->new(order => 27)->all;

DESCRIPTION

   This module allows you to generate and handle operations inside a
   Galois Field (GF) of any allowed order:

     * orders that are too big are likely to explode

     * orders that aren't prime number powers do not have associated
     Galois Fields.

   It's easy to generate a new GF of a given order:

      my $GF5 = Math::GF->new(order => 5); # GF(5)
      my $GF8 = Math::GF->new(order => 8); # GF(2^3)

   Since a GF of order N has exactly N elements, it's easy to refer to
   them with integers from 0 to N - 1. If you want to actually generate
   the associated element you can use the "e" method:

      my $e5_gf8 = $GF8->e(5);

   If you're planning to work extensively with a specific GF, or just want
   some syntactic sugar, you can import a factory function in your package
   that will generate elements in the specific GF:

      # by default, import a function named GF_p_n for GF(p^n)
      Math::GF->import_builder(8);
      my $e5 = GF_2_3(5);

      # you can give your name though
      Math::GF->import_builder(8, name => 'GF8');
      my $e5_gf8 = GF8(5);

   If you need all elements, look at the "all" method. It's the same as
   doing this:

      my @all = map { $GF8->e($_) } 0 .. 8 - 1;

   but easier to type and possibly a bit quicker.

   Elements associated to 0 and 1 have the usual meaning of the additive
   and multiplicative neutral elements, respectively. You can also get
   them with "additive_neutral" and "multiplicative_neutral".

METHODS

   In the following, $GF is supposed to be a Math::GF object.

additive_neutral

      my $zero = $GF->additive_neutral;

   the neutral element of the Galois Field with respect to the addition
   operation. Same as $GF->e(0).

all

      my @all_elements = $GF->all;

   generate all elements of the Galois Field.

e

      my $e5 = $GF->e(5);
      my @some = $GF->e(2, 3, 5, 7);

   factory method to generate one or more elements in the field. When
   called in scalar context it always operate on the first provided
   argument only.

element_class

      my $class_name = $GF->element_class;

   the underlying class for generating elements. It defaults to
   Math::GF::Zn when the "order" is a prime number and Math::GF::Extension
   when it is not; there is probably little motivation for you to fiddle
   with this.

import_builder

      Math::GF->import_builder($order, %args);

   import a factory function in the caller's package for easier generation
   of elements in the GF of the specified $order.

   By default, the name of the imported function is GF_p or GF_p_n where p
   is a prime and n is the power of the prime such that $order = p ** n
   (the n part is omitted if it is equal to 1). For example:

      Math::GF->import_builder(5); # imports GF_5()
      Math::GF->import_builder(8); # imports GF_2_3()

   You can pass your own name in the %args though:

      Math::GF->import_builder(8, name => 'GF8'); # imports GF8()

   The imported function is a wrapper around "e":

      my $one = GF_2_3(1);
      my @some = GF_5(1, 3, 4);

   Allowed keys in %args:

   level

     by default the function is imported in the caller's package. This
     allows you to alter which level in the call stack you want to peek
     for importing the sub.

   name

     the name of the method, see above for the default.

multiplicative_neutral

      my $one = $GF->multiplicative_neutral;

   the neutral element of the Galois Field with respect to the
   multiplication operation. Same as $GF>e(1).

n

      my $power = $GF->n;

   the "order" of a Galois Field must be a power of a prime "p", this
   method provides the value of the power. E.g. if the order is 8, the
   prime is 2 and the power is 3.

order

      my $order = $GF->order;

   the order of the Galois Field. Only powers of a single prime are
   allowed.

order_is_prime

      my $boolean = $GF->order_is_prime;

   the "order" of a Galois Field can only be a power of a prime, with the
   special case in which this power is 1, i.e. the order itself is a prime
   number. This method provided a true value in this case, false
   otherwise.

p

      my $prime = $GF->p;

   the "order" of a Galois Field must be a power of a prime, this method
   provides the value of the prime number. E.g. if the order is 8, the
   prime is 2 and the power is 3. See also "n".

prod_table

      my $pt = $GF->prod_table;

   a table that can be used to evaluate the product of two elements in the
   field.

   The table is provided as a reference to an Array of Arrays. The
   elements in the field are associated to indexes from 0 to order - 1;
   table element $pt->[$A][$B] represents the result of the product
   between element associated to $A and element associated to $B.

   You shouldn't in general need to fiddle with this table, as it is used
   behind the scenes by Math::GF::Extension, where all operations are
   overloaded.

sum_table

      my $st = $GF->sum_table;

   a table that can be used to evaluate the product of two elements in the
   field.

   The table is provided as a reference to an Array of Arrays. The
   elements in the field are associated to indexes from 0 to order - 1;
   table element $pt->[$A][$B] represents the result of the addition
   between element associated to $A and element associated to $B.

   You shouldn't in general need to fiddle with this table, as it is used
   behind the scenes by Math::GF::Extension, where all operations are
   overloaded.

BUGS AND LIMITATIONS

   Report bugs through GitHub (patches welcome).

SEE ALSO

   Math::Polynomial is used behind the scenes to generate the tables in
   case the order is not a prime.

   Math::GF::Zn is used for generating elements in the field and handling
   operations between them in an easy way in case of prime "order".
   Math::GF::Extension is used for elements in the field in case of
   non-prime "order"s.

AUTHOR

   Flavio Poletti <[email protected]>

COPYRIGHT AND LICENSE

   Copyright (C) 2017, 2018 by Flavio Poletti <[email protected]>

   This module is free software. You can redistribute it and/or modify it
   under the terms of the Artistic License 2.0.

   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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.