doc

src/F4_launcher.h

@@ -21,6 +21,9 @@
  *
  */
 
+/// @file
+/// @brief Routines for lauching F4
+
 #ifndef _F4_laucher_h
 #define F4_launcher_h
 
@@ -28,9 +31,15 @@
 #include "polynomial.h"
 #include "parser.h"
 
-void launchF4(std::istream&, std::ostream&);
+/// @brief F4 wrapper
+/// @param in Input stream describing the system
+/// @param out Ouput stream for verbosity
+void launchF4(std::istream& in, std::ostream& out);
 
-void initF4(std::istream&, std::ostream&);
+/// @brief selecting the template parameters, and initialize finite field
+/// @param in Input stream describing the system
+/// @param out Ouput stream for verbosity
+void initF4(std::istream& in, std::ostream& out);
 
 template <class T>
 void field_init();

src/F4_launcher.tpp

@@ -21,6 +21,17 @@
  *
  */
 
+/// @brief selecting the template parameters, and initialize finite field
+/// @param in Input stream describing the system
+/// @param out Ouput stream for verbosity
+void initF4(std::istream& in, std::ostream& out);
+
+template <class T>
+void field_init();
+
+template <class T>
+void field_clear();
+
 template <class T>
 void launchF4(istream &in, ostream &out)
 {
@@ -30,8 +41,6 @@ void launchF4(istream &in, ostream &out)
   log(LOG_INFO) << "parsing done" << endl;
   vector<polynomial<T> > G;
   F4<T>(sys, G);
-//  if(!G.empty())
-//    magma_verif_fprint<T>(sys, G, "verif.mgm");
   for(typename std::vector<polynomial <T>>::const_iterator it = G.begin(); \
       it != G.end(); ++it)
   { 
@@ -47,7 +56,10 @@ void initF4(istream &in, ostream &out)
   in >> s;
   N = (unsigned)atoi(s.c_str());  
   in >> s;
-  mpz_set_str(cardfield, s.c_str(), 10);
+  // set cardinality of finite field
+  // at most UINT_MAX at the moment
+  // TODO: multiprecision
+  mpz_set_str(cardfield, s.c_str(), 10); 
   log(LOG_INFO) << N << " variables" << endl;
 
   mpz_t max64b;
@@ -61,7 +73,7 @@ void initF4(istream &in, ostream &out)
       mpfq_p_0_5_field_specify(GFp_05::k, MPFQ_PRIME_MPZ, cardfield);
       BLASFLAG = true;
       launchF4<GFp_05>(in,out);
-      mpfq_p_0_5_field_clear(GFp_1::k); //  clearing field
+      mpfq_p_0_5_field_clear(GFp_1::k); // clear field
     }
   else if (mpz_cmp(cardfield, max64b) <= 0)
     {
@@ -74,4 +86,3 @@ void initF4(istream &in, ostream &out)
   mpz_clear(max64b);
 }
 
-

src/algos.h

@@ -21,25 +21,23 @@
  *
  */
 
+/// @file 
+/// @brief Implementations of Grobner basis algorithms
+
 #ifndef _algos_h
 #define _algos_h
 #include "polynomial.h"
 
-/*! @file 
-  @brief Implementations of Grobner basis algorithms
-*/
+/// @brief Implementation of Faugere's F4 algorithm 
+/// @param sys input polynomial system over the field T
+/// @param GB Groebner basis of the ideal
 
-/*! @brief Implementation of Faugere's F4 algorithm 
-  @param sys input polynomial system
-  @param GB vector to store the Groebner basis 
-*/
 template <class T>
 void F4(const std::vector<polynomial<T> > &sys, 
     std::vector<polynomial<T> > &GB);
 
-/*! @brief Check if the Grobner basis is minimal
-  @param GB Grobner basis
-*/
+/// @brief Check if the Grobner basis is minimal
+/// @param GB A Groebner basis
 template <class T>
 bool gb_is_minimal(const std::vector<polynomial<T> >&);
 

src/polynomial.h

@@ -21,6 +21,9 @@
  *
  */
 
+/// @file
+/// @brief Polynomials in sparse representation
+
 #ifndef POLYNOMIAL_H_
 #define POLYNOMIAL_H_
 
@@ -28,82 +31,105 @@
 #include "param.h"
 #include "monomial.h"
 
-//////////////////////////// class definitions //////////////////////////////
-
-// polynomial is a class encoding polynomials in sparse representation, i.e. as
-// a list of pairs <coeff, monomial>
-
 template<class T>
 class polynomial;
 
 template<class T>
 std::ostream& operator<<(std::ostream &o, const polynomial<T> &p);
 
+/// @class
+/// @brief Class for manipulating polynomials in sparse representation
 template<class T>
-class polynomial
+class polynomial 
 {
   void combine_LM();
   std::list<std::pair<monomial,T> > vp;
 
-public:
-
+  public:
+  /// @brief default constructor, construct the zero polynomial
   polynomial() 
-  {
-    vp = std::list<std::pair<monomial,T> >();
-  }
+    {
+      vp = std::list<std::pair<monomial,T> >();
+    }
   
+  /// @brief constructor from an ordered list of pairs
   polynomial(std::list<std::pair<monomial,T> > _vp) : vp(_vp){}
 
+  /// @brief get the list of terms
   const std::list<std::pair<monomial,T> >& get_vp() const 
   {
     return vp;
   }
 
+  /// @brief orders the list of terms and merges terms with same monomials.
   void normalize();  
   
+  /// @brief set the polynomial to 0
   void clear() 
   {
     vp.clear();
   }
   
+  /// @brief adds a term
+  /// @param m monomial part of the term
+  /// @param e field element
   void insert(monomial m, T e) 
   {
     vp.push_back(std::pair<monomial, T>(m,e));
   }
-  
+ 
+  /// @brief get the leading monomial
   const monomial& LM() const 
   {
     assert(!vp.back().second.is_zero());
     return vp.back().first;
   }
 
+  /// @brief get the leading coefficient
   const T& LC() const 
   {
     return vp.back().second;
   }
 
+  /// @brief scales the polynomial so that the leading coefficient is 1.
   void set_monic();
   unsigned size() const 
   {
     return vp.size();
   }
   
+  /// @brief tests if a normalized polynomial is zero.
   bool is_zero() const 
   {
     return vp.empty();
   }
 
+  /// @brief computes the degree, only works for degree orderings
+  /// @returns the sum of the exponents
   unsigned degree() const 
   {
+    //@todo extends for non-degree orderings
     return LM().degree();
   }
 
 #ifdef BILIN
+  /// @brief special degree for the selection of critpairs for bilinear systems
   unsigned degree_bilin() const;
 #endif
 
+  /// @brief top-reduce by a polynomial
+  /// @param g reductor
+  /// @returns a boolean indicating if the polynomial was topreduced
   bool topred(const polynomial &g);
+
+  /// @brief check if top-reducible by another polynomial
+  /// @param g reductor
+  /// @returns a boolean indicating if the polynomial was topreduced
   bool istopred(const polynomial &g) const;
+
+  /// @brief get the coefficient of a given monomial
+  /// @param m monomial whose coefficient is returned
+  /// @returns the corresponding coefficient
   T coeff(const monomial& m) const;
 
   /****************************************/
@@ -113,7 +139,10 @@ public:
   void operator-=(const polynomial<T>&);
   void operator*=(const T&);
   void operator/=(const T&);
-  void print(std::ostream&) const;
+
+  /// @brief prints the list of pairs coeff/monomial
+  /// @param out output stream
+  void print(std::ostream& out) const;
 
   //human readable formatting
   friend std::ostream& operator<< <T>(std::ostream&, const polynomial<T>&);

src/polynomial.tpp

@@ -21,8 +21,10 @@
  *
  */
 
-#ifdef BILIN
+/// @file 
+/// @brief Implementation of basic operations on polynomials.
 
+#ifdef BILIN
 template<class T>
 unsigned polynomial<T>::degree_bilin() const
 {

src/timer.h

@@ -21,6 +21,9 @@
  *
  */
 
+/// @file
+/// @brief timers for runtime measurements
+
 #ifndef TIMER_H_
 #define TIMER_H_