rmc-inclusion README -- Important introductory notes.
Copyright (C) 2012-2015 Tumaykin Ilya <itumaykin[at]gmail[dot]com>
See the end of this document for copying conditions.

rmc-inclusion: this project is dedicated to construction and plotting of
the inclusion graphs of certain ideals M_pi(m,k), called the basic Reed-Muller
codes (see [0]), and the radical powers of a group algebra QH, where Q
is a finite field with characteristic p and order q = p^l and H is a group
isomorphic to (Q,+), i.e. the additive group of the field Q.

[0]: E. Couselo, S. Gonzalez, V. Markov, C. Martinez, A. Nechaev,
    “Ideal representation of Reed-Solomon and Reed-Muller codes”,
    Algebra and Logic, 51, 3 (2012), pp. 195-212.


README
------
It is a known fact (see [0]) that in the case of a prime subfield of Q
all basic Reed-Muller codes are equal to radical powers. However,
there are no such equalities in the case of a non-prime subfield of Q,
except for trivial ones. This program helps to study the layout of these ideals
in non-prime cases.

This project consists of 3 main parts: librmc, rmc-{diff,ig,short} tools and
a number of small utilities.

librmc: a library that provides a simple interface to work with M_pi(m,k) ideals.
It supports all basic operations, like creation, multiplication, subtraction,
intersection, and a number of functions to calculate various parameters
of these ideals, like dimension.

rmc-diff: a tool to print diff between M_pi(m,i) and Rad^j ideals.
If both i and j are given, then diff between M_pi(m,i) and Rad^j is printed.
If only one index is given, then the shortest inclusion path is constructed,
where the specified ideal is between the nearest ideals of the other type,
and then diff between the specified ideal and other two is printed.

rmc-ig: the most powerful tool: it is able to print all the needed info
about M_pi(m,k) ideals and radical powers; it is also able to print
inclusion graphs of Ms/Rads and Rad*Ms/Ms. That is, it allows to visualize
the layout of Ms in QH completely.

rmc-short: a special tool for Ms/Rads inclusion graph plotting only.
However, it doesn't compute ideals directly, but uses some theoretical results
to construct almost* transitively reduced inclusion graph. It is much faster
than rmc-ig and plots only the needed M_pi(m,k), omitting trivial inclusion paths.
*Note: 'almost' means that the graph is transitively reduced with
the possible exception to arcs between consecutive radical powers,
which sometimes are redundant. However, this only applies to a very small cases,
namely p = lambda = 2 and even l.

utils: various utilities for printing special information related to the basic
Reed-Muller codes and radical powers. Refer to the source code or a short help
message provided by each utility.


LIMITATIONS
-----------
All ideals' indices and most of other parameters are bounded by the size of
`unsigned long long` type on your machine. However, this bound is far beyond
practical limits of these programs, as with increasing number of processed ideals
graphs become too big and complex to comprehend.
If you want to prevent possible overflows and wraps by performing needed checks,
you should enable debug support.


COMPILATION
-----------
External dependencies are minimal: CMake and C compiler.
Optional dependency is GMP, which unlocks m_k function that calculates M_pi(m,k)
dimension and also unlocks u_calculator utility.
You can use preferred cmake building procedure or run script
tools/build.sh from the project's top dir.


LICENSING
---------
All content in this project is licensed under
the GNU Lesser General Public License (LGPL) version 2.1,
with the only exception to files in cmake/Modules dir which were once
a part of libssh project and have their own license.
You can find the full text of LGPLv2.1 license in the COPYING file.