clean up and restructurings

1 files changed, 50 insertions, 1 deletions

diff --git a/README.md b/README.md
index 3ba3ae5..98ba196 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,50 @@
-# Polynomial matrix library
+# Multivariate polynomial library
+
+`polymatrix` is a library to represent and operate on multivariate polynomials. 
+
+It is currently mainly used to define Sum Of Squares optimization problems.
+
+Some aspects of the library 
+
+* it has a lazy behavior: 
+    * the library implements operators to build polynomial expression
+    * the actual polynomial representation is created by calling the `apply(state)` method on the polynomial expression
+* a `sympy` expression can be converted to a polynomial expression using the `polymatrix.from_sympy` function
+* multiple polynomial expressions are combined using functions like `polymatrix.v_stack` or `polymatrix.block_diag`.
+* polynomial expressions are manipulated using bounded functions like `diff`, `reshape`, `substitute`, `sum` or `to_constant` (see `polymatrix/expression/mixins/expressionmixin.py`)
+* an expression can be converted to matrix representation using `polymatrix.to_matrix_repr`. Again, to get the actual representation the `apply(state)` method needs to be called.
+
+## Example
+
+``` python
+import sympy
+import polymatrix
+
+state = polymatrix.init_expression_state()
+
+x1, x2 = sympy.symbols('x1, x2')
+x = polymatrix.from_((x1, x2))
+
+f1 = polymatrix.from_(x1 + x2)
+f2 = polymatrix.from_(x1 + x1*x2)
+
+expr = f1 + f2          
+
+# prints the data structure of the expression
+# ExpressionImpl(underlying=AdditionExprImpl(left=FromSympyExprImpl(data=((x1 + x2,),)), right=FromSympyExprImpl(data=((x1*x2 + x1,),))))
+print(expr)
+
+state, poly_matrix = expr.apply(state)
+
+# prints the data structure of the polynomial matrix
+# PolyMatrixImpl(terms={(0, 0): {((0, 1), (1, 1)): 1, ((0, 1),): 2, ((1, 1),): 1}}, shape=(1, 1))
+print(poly_matrix)
+
+state, matrix_repr = polymatrix.to_matrix_repr((expr,), x).apply(state)
+
+# prints the numpy matrix representations of the polynomial matrix
+# array([[2., 1.]])
+# array([[0. , 0.5, 0.5, 0. ]])
+print(matrix_repr.data[0][1])
+print(matrix_repr.data[0][2].toarray())
+```