Add big docstring in module to discuss terminology

2 files changed, 105 insertions, 2 deletions

diff --git a/mdpoly/__init__.py b/mdpoly/__init__.py
index c976db3..15ab8c9 100644
--- a/mdpoly/__init__.py
+++ b/mdpoly/__init__.py
@@ -1,4 +1,106 @@
-""" A Library to represent multivariate polynomials """
+r""" A Library to represent multivariate polynomials
+
+Overview
+========
+
+TODO
+
+
+Terminology
+===========
+
+Herein we will describe the terminology used to talk about polynomials, both in
+their mathematical sense as well as their representation in code. Most terms
+should already be well known to the reader, and the purpose ir rather to remove
+any ambiguities.
+
+
+Variable, Monomial, Term, Entry, and Coefficient
+------------------------------------------------
+
+From a mathematical perspective this library describes objects from
+:math:`\mathbb{R}^{n\times m} [x_1, x_2, \ldots, x_k]`, where
+:math:`\mathbb{R}^{n\times m}` is the set of matrices with real entries and
+:math:`x_i` are called *variables*. The simplest concrete example is
+:math:`\mathbb{R}[x]`, the set of scalar univariate polynomials for example
+
+.. math::
+    p(x) = x^2 + 2x + 3 \in \mathbb{R}[x].
+
+A scalar multivariate polynomial could be for example:
+
+.. math::
+    p(x, y) = x^2 +  2 xy^4 + y + 5 \in \mathbb{R}[x, y].
+
+A *monomial* is a product powers of variables, in the example above
+:math:`xy^4` or :math:`x^2`. Note that :math:`1` is also a monomial, the
+constant monomial, since it is a product of variables to the zeroth power. In
+front of a monomial there is a scalar *coefficient* and we call *term* a
+monomial with its coefficient. In code we index a polynomial term using
+:py:class:`mdpoly.index.PolyIndex`.
+
+To provide an example of the most general case consider :math:`P(x, y) \in
+\mathbb{R}^{2 \times 3} [x, y]`, a matrix of polynomials:
+
+.. math::
+    P(x, y) = \begin{bmatrix}
+        3 x^2 + y & y + 1 & 0 \\
+        y^5 + 8 xy & x + y & 2 y^3 \\
+    \end{bmatrix}
+    \in \mathbb{R}^{2 \times 3}[x, y].
+
+Since we are dealing with matrices, we say that at the *entry* with row 1 and
+column 1 there is a polymial `x^2 + y`. It is important to note that in
+mathematics it is customary to start indices at 1, whereas in software
+programming at 0. We will index rows and columns starting at 0 in
+:py:class:`mdpoly.index.MatrixIndex`.
+
+
+Expression
+----------
+
+Within the code, we will often call something like :math:`x^2 + 1` and
+*expression* (for example :py:class:`mdpoly.abc.Expr` or
+:py:class:`mdpoly.algebra.PolyRingExpr`) instead of polynomial. Expressions are
+more general and can include any mathematical operation. Of course in the end
+and expression should result in a polynomial.
+
+
+Decision Variables, Program
+---------------------------
+
+This package also contains a module :py:mod:`mdpoly.sos` for sum-of-square
+polynomials, which involves mathematical programming (optimization). Now,
+because of this fact we have to resolve the following ambiguity: consider the
+polynomial
+
+.. math::
+    p = a^2 x + b x^2 + y \in \mathbb{R}[x, y, a, b].
+
+TODO: difference between variables and decision / optimization variables.
+
+
+Parameters
+----------
+
+From the field of parametric programming we borrow the term *parameter* to mean
+a constant that is specified at a later time. Think of physical / design
+constants that are subject to change (or are computed by another process) and
+should not be hard-coded, but rather only given names.
+
+However, unlike in the discipline parametric programming we may not leave the
+parameter unspecified before solving the optimization problem (yet). This is
+because the theory of parametric semi-definite programming is still very, very
+far from developed (compared to say, parametric LPs).
+
+
+Representation
+--------------
+
+TODO: data structure(s) that represent the polynomial
+
+
+"""
 
 # internal classes imported with underscore because 
 # they should not be exposed to the end users
diff --git a/mdpoly/abc.py b/mdpoly/abc.py
index c5fadbe..f617436 100644
--- a/mdpoly/abc.py
+++ b/mdpoly/abc.py
@@ -379,7 +379,8 @@ class Repr(ABC):
     r""" Representation of a multivariate matrix polynomial expression.
 
     Concretely, a representation must be able to store a mathematical object
-    like :math:`Q \in \mathbb{R}^2[x, y]`, for example
+    from :math:`\mathbb{K}^{n\times m}[x_1, \ldots, x_k]`. Concretely for
+    example :math:`Q \in \mathbb{R}^{2\times 2}[x, y]`, with
 
     .. math::
         Q = \begin{bmatrix}