added module descriptions

Signed-off-by: Leonardo de Moura <leonardo@microsoft.com>

scripts/mk_util.py

@@ -1464,7 +1464,7 @@ def pyg_default_as_c_literal(p):
 def to_c_method(s):
     return s.replace('.', '_')
 
-def def_module_params(module_name, export, params, class_name=None):
+def def_module_params(module_name, export, params, class_name=None, description=None):
     pyg = get_curr_pyg()
     dirname = os.path.split(get_curr_pyg())[0]
     if class_name == None:
@@ -1491,6 +1491,8 @@ def def_module_params(module_name, export, params, class_name=None):
     if export:
         out.write('  /*\n')
         out.write("     REG_MODULE_PARAMS('%s', '%s::collect_param_descrs')\n" % (module_name, class_name))
+        if description != None:
+            out.write("     REG_MODULE_DESCRIPTION('%s', '%s')\n" % (module_name, description))
         out.write('  */\n')
     # Generated accessors
     for param in params:
@@ -1763,12 +1765,14 @@ def mk_all_mem_initializer_cpps():
 def mk_gparams_register_modules(cnames, path):
     cmds = []
     mod_cmds = []
+    mod_descrs = []
     fullname = '%s/gparams_register_modules.cpp' % path
     fout  = open(fullname, 'w')
     fout.write('// Automatically generated file.\n')
     fout.write('#include"gparams.h"\n')
     reg_pat = re.compile('[ \t]*REG_PARAMS\(\'([^\']*)\'\)')
     reg_mod_pat = re.compile('[ \t]*REG_MODULE_PARAMS\(\'([^\']*)\', *\'([^\']*)\'\)')
+    reg_mod_descr_pat = re.compile('[ \t]*REG_MODULE_DESCRIPTION\(\'([^\']*)\', *\'([^\']*)\'\)')
     for cname in cnames:
         c = get_component(cname)
         h_files = filter(lambda f: f.endswith('.h') or f.endswith('.hpp'), os.listdir(c.src_dir))
@@ -1788,11 +1792,16 @@ def mk_gparams_register_modules(cnames, path):
                         added_include = True
                         fout.write('#include"%s"\n' % h_file)
                     mod_cmds.append((m.group(1), m.group(2)))
+                m = reg_mod_descr_pat.match(line)
+                if m:
+                    mod_descrs.append((m.group(1), m.group(2)))
     fout.write('void gparams_register_modules() {\n')
     for code in cmds:
         fout.write('{ param_descrs d; %s(d); gparams::register_global(d); }\n' % code)
     for (mod, code) in mod_cmds:
         fout.write('{ param_descrs * d = alloc(param_descrs); %s(*d); gparams::register_module("%s", d); }\n' % (code, mod))
+    for (mod, descr) in mod_descrs:
+        fout.write('gparams::register_module_descr("%s", "%s");\n' % (mod, descr))
     fout.write('}\n')
     if VERBOSE:
         print "Generated '%s'" % fullname

src/ast/normal_forms/nnf_params.pyg

@@ -1,4 +1,5 @@
 def_module_params('nnf', 
+                  description='negation normal form',
                   export=True,
                   params=(max_memory_param(),
                           ('sk_hack', BOOL, False, 'hack for VCC'),

src/ast/pattern/pattern_inference_params.cpp

@@ -0,0 +1,32 @@
+/*++
+Copyright (c) 2012 Microsoft Corporation
+
+Module Name:
+
+    pattern_inference_params.h
+
+Abstract:
+
+    <abstract>
+
+Author:
+
+    Leonardo de Moura (leonardo) 2012-12-02.
+
+Revision History:
+
+--*/
+#include"pattern_inference_params.h"
+#include"pattern_inference_params_helper.hpp"
+
+void pattern_inference_params::updt_params(params_ref const & _p) {
+    pattern_inference_params_helper p(_p);
+    m_pi_max_multi_patterns      = p.max_multi_patterns();
+    m_pi_block_loop_patterns     = p.block_loop_patterns();
+    m_pi_arith                   = static_cast<arith_pattern_inference_kind>(p.arith());
+    m_pi_use_database            = p.use_database();
+    m_pi_arith_weight            = p.arith_weight();
+    m_pi_non_nested_arith_weight = p.non_nested_arith_weight();
+    m_pi_pull_quantifiers        = p.pull_quantifiers();
+    m_pi_warnings                = p.warnings();
+}

src/ast/pattern/pattern_inference_params.h

@@ -19,7 +19,7 @@ Revision History:
 #ifndef _PATTERN_INFERENCE_PARAMS_H_
 #define _PATTERN_INFERENCE_PARAMS_H_
 
-#include"pattern_inference_params_helper.hpp"
+#include"params.h"
 
 enum arith_pattern_inference_kind {
     AP_NO,           // do not infer patterns with arithmetic terms
@@ -45,17 +45,7 @@ struct pattern_inference_params {
         updt_params(p);
     }
 
-    void updt_params(params_ref const & _p) {
+    void updt_params(params_ref const & _p);
-        pattern_inference_params_helper p(_p);
-        m_pi_max_multi_patterns      = p.max_multi_patterns();
-        m_pi_block_loop_patterns     = p.block_loop_patterns();
-        m_pi_arith                   = static_cast<arith_pattern_inference_kind>(p.arith());
-        m_pi_use_database            = p.use_database();
-        m_pi_arith_weight            = p.arith_weight();
-        m_pi_non_nested_arith_weight = p.non_nested_arith_weight();
-        m_pi_pull_quantifiers        = p.pull_quantifiers();
-        m_pi_warnings                = p.warnings();
-    }
 };
 
 #endif /* _PATTERN_INFERENCE_PARAMS_H_ */

src/ast/pattern/pattern_inference_params_helper.pyg

@@ -1,5 +1,6 @@
 def_module_params(class_name='pattern_inference_params_helper',
                   module_name='pi',
+                  description='pattern inference (heuristics) for universal formulas (without annotation)',
                   export=True,
                   params=(('max_multi_patterns', UINT, 0, 'when patterns are not provided, the prover uses a heuristic to infer them, this option sets the threshold on the number of extra multi-patterns that can be created; by default, the prover creates at most one multi-pattern when there is no unary pattern'),
                           ('block_loop_patterns', BOOL, True, 'block looping patterns during pattern inference'),

src/ast/pp_params.pyg

@@ -1,5 +1,6 @@
 def_module_params('pp', 
                   export=True,
+                  description='pretty printer',
                   params=(('max_indent', UINT, UINT_MAX, 'max. indentation in pretty printer'),
                           ('max_num_lines', UINT, UINT_MAX, 'max. number of lines to be displayed in pretty printer'),
                           ('max_width', UINT, 80, 'max. width in pretty printer'),

src/ast/simplifier/arith_simplifier_params.cpp

@@ -0,0 +1,26 @@
+/*++
+Copyright (c) 2006 Microsoft Corporation
+
+Module Name:
+
+    arith_simplifier_params.cpp
+
+Abstract:
+
+    <abstract>
+
+Author:
+
+    Leonardo de Moura (leonardo) 2012-12-02.
+
+Revision History:
+
+--*/
+#include"arith_simplifier_params.h"
+#include"arith_simplifier_params_helper.hpp"
+
+void arith_simplifier_params::updt_params(params_ref const & _p) {
+    arith_simplifier_params_helper p(_p);
+    m_arith_expand_eqs      = p.arith_expand_eqs();
+    m_arith_process_all_eqs = p.arith_process_all_eqs();
+}

src/ast/simplifier/arith_simplifier_params.h

@@ -19,7 +19,7 @@ Revision History:
 #ifndef _ARITH_SIMPLIFIER_PARAMS_H_
 #define _ARITH_SIMPLIFIER_PARAMS_H_
 
-#include"arith_simplifier_params_helper.hpp"
+#include"params.h"
 
 struct arith_simplifier_params { 
     bool    m_arith_expand_eqs;
@@ -29,11 +29,7 @@ struct arith_simplifier_params {
         updt_params(p);
     }
 
-    void updt_params(params_ref const & _p) {
+    void updt_params(params_ref const & _p);
-        arith_simplifier_params_helper p(_p);
-        m_arith_expand_eqs      = p.arith_expand_eqs();
-        m_arith_process_all_eqs = p.arith_process_all_eqs();
-    }
 };
     
 #endif /* _ARITH_SIMPLIFIER_PARAMS_H_ */

src/ast/simplifier/arith_simplifier_params_helper.pyg

@@ -1,5 +1,6 @@
 def_module_params(class_name='arith_simplifier_params_helper',
                   module_name="old_simplify", # Parameters will be in the old_simplify module
+                  description="old simplification (stack) still used in the smt module",
                   export=True,
                   params=(
                           ('arith.expand_eqs', BOOL, False, 'expand equalities into two inequalities'),

src/ast/simplifier/array_simplifier_params.cpp

@@ -0,0 +1,26 @@
+/*++
+Copyright (c) 2012 Microsoft Corporation
+
+Module Name:
+
+    array_simplifier_params.cpp
+
+Abstract:
+
+    This file was created during code reorg.
+
+Author:
+
+    Leonardo de Moura (leonardo) 2012-12-02.
+
+Revision History:
+
+--*/
+#include"array_simplifier_params.h"
+#include"array_simplifier_params_helper.hpp"
+
+void array_simplifier_params::updt_params(params_ref const & _p) {
+    array_simplifier_params_helper p(_p);
+    m_array_canonize_simplify = p.array_canonize();
+    m_array_simplify          = p.array_simplify();
+}

src/ast/simplifier/array_simplifier_params.h

@@ -1,5 +1,5 @@
 /*++
-Copyright (c) 2006 Microsoft Corporation
+Copyright (c) 2012 Microsoft Corporation
 
 Module Name:
 
@@ -19,7 +19,7 @@ Revision History:
 #ifndef _ARRAY_SIMPLIFIER_PARAMS_H_
 #define _ARRAY_SIMPLIFIER_PARAMS_H_
 
-#include"array_simplifier_params_helper.hpp"
+#include"params.h"
 
 struct array_simplifier_params {
     bool            m_array_canonize_simplify;
@@ -29,11 +29,7 @@ struct array_simplifier_params {
         updt_params(p);
     }
 
-    void updt_params(params_ref const & _p) {
+    void updt_params(params_ref const & _p);
-        array_simplifier_params_helper p(_p);
-        m_array_canonize_simplify = p.array_canonize();
-        m_array_simplify          = p.array_simplify();
-    }
 };
     
 #endif /* _ARITH_SIMPLIFIER_PARAMS_H_ */

src/ast/simplifier/bv_simplifier_params.cpp

@@ -0,0 +1,26 @@
+/*++
+Copyright (c) 2006 Microsoft Corporation
+
+Module Name:
+
+    bv_simplifier_params.cpp
+
+Abstract:
+
+    <abstract>
+
+Author:
+
+    Leonardo de Moura (leonardo) 2012-12-02.
+
+Revision History:
+
+--*/
+#include"bv_simplifier_params.h"
+#include"bv_simplifier_params_helper.hpp"
+
+void bv_simplifier_params::updt_params(params_ref const & _p) {
+    bv_simplifier_params_helper p(_p);
+    m_hi_div0 = p.bv_hi_div0();
+    m_bv2int_distribute = p.bv_bv2int_distribute();
+}

src/ast/simplifier/bv_simplifier_params.h

@@ -19,7 +19,7 @@ Revision History:
 #ifndef _BV_SIMPLIFIER_PARAMS_H_
 #define _BV_SIMPLIFIER_PARAMS_H_
 
-#include"bv_simplifier_params_helper.hpp"
+#include"params.h"
 
 struct bv_simplifier_params {
     bool  m_hi_div0; //!< if true, uses the hardware interpretation for div0, mod0, ... if false, div0, mod0, ... are considered uninterpreted.
@@ -29,11 +29,7 @@ struct bv_simplifier_params {
         updt_params(p);
     }
 
-    void updt_params(params_ref const & _p) {
+    void updt_params(params_ref const & _p);
-        bv_simplifier_params_helper p(_p);
-        m_hi_div0 = p.bv_hi_div0();
-        m_bv2int_distribute = p.bv_bv2int_distribute();
-    }
 };
 
 #endif /* _BV_SIMPLIFIER_PARAMS_H_ */

src/math/polynomial/algebraic.pyg

@@ -1,4 +1,5 @@
 def_module_params('algebraic', 
+                  description='real algebraic number package',
                   export=True,
                   params=(('zero_accuracy', UINT, 0, 'one of the most time-consuming operations in the real algebraic number module is determining the sign of a polynomial evaluated at a sample point with non-rational algebraic number values. Let k be the value of this option. If k is 0, Z3 uses precise computation. Otherwise, the result of a polynomial evaluation is considered to be 0 if Z3 can show it is inside the interval (-1/2^k, 1/2^k)'),
                           ('min_mag', UINT, 16, 'Z3 represents algebraic numbers using a (square-free) polynomial p and an isolating interval (which contains one and only one root of p). This interval may be refined during the computations. This parameter specifies whether to cache the value of a refined interval or not. It says the minimal size of an interval for caching purposes is 1/2^16'),

src/nlsat/nlsat_params.pyg

@@ -1,5 +1,6 @@
 
 def_module_params('nlsat', 
+                  description='nonlinear solver',
                   export=True,
                   params=(max_memory_param(),
                           ('lazy', UINT, 0, "how lazy the solver is."),

src/util/gparams.cpp

@@ -37,6 +37,7 @@ bool is_old_param_name(symbol const & name) {
 
 struct gparams::imp {
     dictionary<param_descrs*> m_module_param_descrs;
+    dictionary<char const *>  m_module_descrs;
     param_descrs              m_param_descrs;
     dictionary<params_ref *>  m_module_params;
     params_ref                m_params;
@@ -83,6 +84,13 @@ public:
         }
     }
 
+    void register_module_descr(char const * module_name, char const * descr) {
+        #pragma omp critical (gparams)
+        {
+            m_module_descrs.insert(symbol(module_name), descr);
+        }
+    }
+
     void display(std::ostream & out, unsigned indent, bool smt2_style) {
         #pragma omp critical (gparams)
         {
@@ -92,7 +100,12 @@ public:
             dictionary<param_descrs*>::iterator it  = m_module_param_descrs.begin();
             dictionary<param_descrs*>::iterator end = m_module_param_descrs.end();
             for (; it != end; ++it) {
-                out << "[module] " << it->m_key << "\n";
+                out << "[module] " << it->m_key;
+                char const * descr = 0;
+                if (m_module_descrs.find(it->m_key, descr)) {
+                    out << ", description: " << descr;
+                }
+                out << "\n";
                 it->m_value->display(out, indent + 4, smt2_style);
             }
         }
@@ -337,6 +350,11 @@ void gparams::register_module(char const * module_name, param_descrs * d) {
     g_imp->register_module(module_name, d);
 }
 
+void gparams::register_module_descr(char const * module_name, char const * descr) {
+    SASSERT(g_imp != 0);
+    g_imp->register_module_descr(module_name, descr);
+}
+
 params_ref gparams::get_module(char const * module_name) {
     return get_module(symbol(module_name));
 }

src/util/gparams.h

@@ -79,6 +79,11 @@ public:
     */
     static void register_module(char const * module_name, param_descrs * d); 
 
+    /**
+       \brief Add a (small) description to the given module.
+    */
+    static void register_module_descr(char const * module_name, char const * descr);
+
     /**
        \brief Retrieves the parameters associated with the given module.