Cleanup doxygen documentation. Add untrace.

kpeeters · kpeeters · commit f61965923870 · 2018-12-13T13:53:25.000Z
diff --git a/Makefile b/Makefile
@@ -8,10 +8,12 @@ tarball:
 	git archive --format=tar --prefix=cadabra2-latest/ HEAD | gzip > ${HOME}/tmp/cadabra2-latest.tar.gz
 
 doc:
-	doxygen
+	doxygen config/Doxyfile
 
 webup:
 	cd build; make -f web2/Makefile
+	doxygen config/Doxyfile
+	rsync -avz --chmod=+rx doxygen/ cadabra_web:/var/www/cadabra2/doxygen/
 	cd web2/cadabra2; clay build; rsync -avz --chmod=+rx build/ cadabra_web:/var/www/cadabra2/;  rsync -avz --chmod=+rx source/static/styles/ cadabra_web:/var/www/cadabra2/static/styles; rsync -avz --chmod=+rx source/static/images/ cadabra_web:/var/www/cadabra2/static/images/; rsync -avz --chmod=+rx source/static/icons/ cadabra_web:/var/www/cadabra2/static/icons/; rsync -avz --chmod=+rx source/static/pdf/ cadabra_web:/var/www/cadabra2/static/pdf/; rsync -avz --chmod=+rx source/static/scripts/ cadabra_web:/var/www/cadabra2/static/scripts/; rsync -avz --chmod=+r robots.txt cadabra_web:/var/www/cadabra2
 
 packages:
diff --git a/config/Doxyfile b/config/Doxyfile
@@ -684,7 +684,7 @@ FILE_VERSION_FILTER    =
 # DoxygenLayout.xml, doxygen will parse it automatically even if the LAYOUT_FILE
 # tag is left empty.
 
-LAYOUT_FILE            = DoxygenLayout.xml
+LAYOUT_FILE            = config/DoxygenLayout.xml
 
 # The CITE_BIB_FILES tag can be used to specify one or more bib files containing
 # the reference definitions. This must be a list of .bib files. The .bib
@@ -1145,7 +1145,7 @@ HTML_STYLESHEET        =
 # list). For an example see the documentation.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_EXTRA_STYLESHEET  = DoxygenStyle.css
+HTML_EXTRA_STYLESHEET  = config/DoxygenStyle.css
 
 # The HTML_EXTRA_FILES tag can be used to specify one or more extra images or
 # other source files which should be copied to the HTML output directory. Note
@@ -1619,7 +1619,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = YES
+GENERATE_LATEX         = NO
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
diff --git a/config/DoxygenLayout.xml b/config/DoxygenLayout.xml
diff --git a/config/DoxygenStyle.css b/config/DoxygenStyle.css
diff --git a/core/CMakeLists.txt b/core/CMakeLists.txt
@@ -81,7 +81,8 @@ SET(ALGORITHM_SRC_FILES
 	algorithms/take_match.cc
 	algorithms/replace_match.cc
 	algorithms/unwrap.cc
-	algorithms/unzoom.cc    
+	algorithms/unzoom.cc
+	algorithms/untrace.cc
 	algorithms/vary.cc
 	algorithms/young_project.cc
 	algorithms/young_project_product.cc
diff --git a/core/Cleanup.hh b/core/Cleanup.hh
@@ -41,7 +41,7 @@ typedef void (*dispatcher_t)(const Kernel& k, Ex&, Ex::iterator& it);
 /// first layer of child nodes, but do NOT descend deeper down the
 /// tree, UNLESS that would leave the tree in an inconsistent
 /// state. An example is acting at the top node of
-/// \prod{4}{\sum{a}{b}}, which would push the 4 to the multiplier of
+/// `\prod{4}{\sum{a}{b}}`, which would push the 4 to the multiplier of
 /// the sum, but that is not allowed, so it needs to go further down.
 /// Sibling nodes of 'it' remain untouched as well.
 
diff --git a/core/Compare.hh b/core/Compare.hh
@@ -214,8 +214,8 @@ class Ex_comparator {
 		/// Determine whether Coordinates in the pattern (first argument
 		/// to functions below) can match against Indices in the object
 		/// (second argument). That is to say, whether the pattern
-		/// \partial_{t}{A} matches against the expression
-		/// \partial_{\mu}{A} when \mu can take the value t. This is
+		/// `\partial_{t}{A}` matches against the expression
+		/// `\partial_{\mu}{A}` when `\mu` can take the value `t`. This is
 		/// used in 'evaluate', but should generically be turned off for
 		/// 'substitute'.
 
diff --git a/core/DisplayBase.hh b/core/DisplayBase.hh
@@ -27,9 +27,9 @@ class DisplayBase {
 	protected:
 		/// Determine if a node needs extra brackets around it. Uses context from the
 		/// parent node if necessary. Has to be implemented in a derived class, because
-      /// the answer depends on the printing method (e.g. (a+b)/c needs brackets
+      /// the answer depends on the printing method (e.g. `(a+b)/c` needs brackets
 		/// when printed like this, but does not need brackets when printed as
-		/// \frac{a+b}{c}).
+		/// `\frac{a+b}{c}`).
 
 		virtual bool needs_brackets(Ex::iterator it)=0;
 
diff --git a/core/DisplayMMA.hh b/core/DisplayMMA.hh
@@ -23,7 +23,7 @@ class DisplayMMA : public DisplayBase {
 
       /// Rewrite the output of mathematica back into a notation used by
       /// Cadabra. This in particular involves converting 'Sin' and
-      /// friends to '\sin' and so on, as well as converting all the
+      /// friends to `\sin` and so on, as well as converting all the
       /// greek symbols.  Currently only acts node-by-node, does not
       /// do anything complicated with trees.
 
@@ -52,7 +52,7 @@ class DisplayMMA : public DisplayBase {
 		/// For every object encountered, dispatch will figure out the
 		/// most appropriate way to convert it into a LaTeX
 		/// expression. This may be done by simply looking at the
-		/// object's name (e.g. \prod will print as a product) but may
+		/// object's name (e.g. `\prod` will print as a product) but may
 		/// also involve looking up properties and deciding on the best
 		/// course of action based on the attached properties.
 
@@ -81,8 +81,8 @@ class DisplayMMA : public DisplayBase {
 
 		/// Map from Cadabra symbols to Mathematica symbols.
 		/// This is a bit tricky because MathLink does not pass
-		/// \[Alpha] and friends transparently. So we feed it UTF8
-		/// α and so on, but then we get \[Alpha] back, and that
+		/// `\[Alpha]` and friends transparently. So we feed it UTF8
+		/// α and so on, but then we get `\[Alpha]` back, and that
 		/// needs to be regex-replaced before we feed it to our
 		/// parser as ours does not swallow that kind of bracketing.
 		std::map<std::string, std::string>      symmap;
diff --git a/core/DisplaySympy.hh b/core/DisplaySympy.hh
@@ -16,15 +16,15 @@ namespace cadabra {
 /// parse. Will throw an exception if a Cadabra Ex object cannot be
 /// understood by Sympy. Can also convert expressions back to Cadabra
 /// notation. This class contains the printing logic that you see in
-/// action when you call the '__sympy__' method on an Ex object.
+/// action when you call the `__sympy__` method on an Ex object.
 
 class DisplaySympy : public DisplayBase {
 	public:
 		DisplaySympy(const Kernel&, const Ex&);
 
       /// Rewrite the output of sympy back into a notation used by
       /// Cadabra. This in particular involves converting 'sin' and
-      /// friends to '\sin' and so on, as well as converting all the
+      /// friends to `\sin` and so on, as well as converting all the
       /// greek symbols.  Currently only acts node-by-node, does not
       /// do anything complicated with trees.
 
@@ -51,7 +51,7 @@ class DisplaySympy : public DisplayBase {
 		/// For every object encountered, dispatch will figure out the
 		/// most appropriate way to convert it into a LaTeX
 		/// expression. This may be done by simply looking at the
-		/// object's name (e.g. \prod will print as a product) but may
+		/// object's name (e.g. `\prod` will print as a product) but may
 		/// also involve looking up properties and deciding on the best
 		/// course of action based on the attached properties.
 
diff --git a/core/DisplayTeX.hh b/core/DisplayTeX.hh
@@ -48,7 +48,7 @@ class DisplayTeX : public DisplayBase {
 		/// For every object encountered, dispatch will figure out the
 		/// most appropriate way to convert it into a LaTeX
 		/// expression. This may be done by simply looking at the
-		/// object's name (e.g. \prod will print as a product) but may
+		/// object's name (e.g. `\prod` will print as a product) but may
 		/// also involve looking up properties and deciding on the best
 		/// course of action based on the attached properties.
 
@@ -84,16 +84,16 @@ class DisplayTeX : public DisplayBase {
 		/// Determine whether the indicated object 'obj', when acting on
 		/// the single argument 'arg', reads as an operator, and therefore
 		/// 'arg' does not need to be wrapped in brackets. 
-		/// Example: the tree \\partial{A} can be displayed as '\\partial A'
-		/// (or rather, '\\partial{A}', instead of '\\partial(A)'. 
+		/// Example: the tree `\partial{A}` can be displayed as `\partial A`
+		/// (or rather, `\partial{A}`, instead of `\partial(A)`. 
 	  
 		bool reads_as_operator(Ex::iterator obj, Ex::iterator arg) const;
 
 		/// Map from Cadabra symbols to LaTeX symbols (for some typographic cleanup).
 		std::map<std::string, std::string> symmap;
 
 		/// List of operators which need all arguments fed with curly brackets, not 
-		/// round ones (e.g. \\sqrt).
+		/// round ones (e.g. `\sqrt`).
 		std::set<std::string> curly_bracket_operators;
 
 };
diff --git a/core/Stopwatch.hh b/core/Stopwatch.hh
@@ -41,6 +41,7 @@
 ///
 /// Example C++ usage:
 ///
+/// ~~~~~~~{.cc}
 /// #include <iostream>
 /// #include <vector>
 /// #include "Stopwatch.hh"
@@ -71,10 +72,11 @@
 ///   std::cout << "Doing other stuff takes " << s.useconds() << "us\n"; //Assuming do_other_stuff() takes < 1s
 ///   return 0;
 /// }
-///
+/// ~~~~~~~
 ///
 /// Example python usage:
 ///
+/// ~~~~~~~{.py}
 /// from cadabra2 import Stopwatch
 ///
 /// def do_other_stuff():
@@ -100,7 +102,7 @@
 /// do_other_stuff()
 /// s.stop()
 /// print("Doing other stuff takes {}us".format(s.useconds())) #Assuming do_other_stuff() takes < 1s
-
+/// ~~~~~~~
 
 class Stopwatch {
 	public:
diff --git a/core/algorithms/collect_components.hh b/core/algorithms/collect_components.hh
@@ -7,7 +7,7 @@ namespace cadabra {
 
 /// \ingroup algorithms
 ///
-/// Collect \components terms inside a sum, merging their substitution rules.
+/// Collect `\components` terms inside a sum, merging their substitution rules.
 
 class collect_components : public Algorithm {
 	public:
diff --git a/core/algorithms/complete.cc b/core/algorithms/complete.cc
@@ -44,9 +44,11 @@ Algorithm::result_t complete::apply(iterator& it)
 		}
 	const Trace *trace = kernel.properties.get<Trace>(bg);
 	if(trace) {
-		Ex metric(trace->obj);
-		sympy::trace(kernel, metric, tr, bg);
-		res = result_t::l_applied;
+		if(trace->obj.size()>0) {
+			Ex metric(trace->obj);
+			sympy::trace(kernel, metric, tr, bg);
+			res = result_t::l_applied;
+			}
 		}
 
 	return res;
diff --git a/core/algorithms/evaluate.hh b/core/algorithms/evaluate.hh
@@ -14,6 +14,8 @@
 	See tests/components.cdb for basic samples. 
 
 	Components nodes have the following structure:
+	
+	\verbatim
 
      \components
         _{m}            // index names/types
@@ -35,14 +37,20 @@
      vals:= { A_{t t} -> r, A_{r r} -> r**2, A_{t \phi} -> t, B_{t t} -> 1 };
      evaluate(ex, crds, vals);
      tst:= r * ( r + 1 ) + r**2 * r**2 + t*t - @(ex);
+	  
+	\endverbatim
 
 	The algorithm performs
 	the following steps.  First, all free and dummy indices are
 	classified using members of Algorithm (maybe later?). For all indices, the 'crds'
 	argument to the algorithm is scanned for a
 
+	\verbatim
+
         m -> { a,b,c }
 
+	\endverbatim
+
    type pattern. 
 
    Do a dept-first scan until the first sum or product node. 
@@ -60,9 +68,13 @@
      In a product node, find all dummies and free indices. Create a 
      set of all index value sets, e.g.
 
+	  \verbatim 
+
         {m, n, p} ->
          { {t, t, t}, {r,t,t}, {t,r,t}, ... }
 
+	  \endverbatim
+
      For each such index value set, lookup replacement rules.
 
      KEY: quick way to lookup, for a given set of index values on a
diff --git a/core/algorithms/untrace.cc b/core/algorithms/untrace.cc
@@ -0,0 +1,92 @@
+
+#include "untrace.hh"
+#include "Cleanup.hh"
+
+#include "properties/ImplicitIndex.hh"
+#include "properties/Trace.hh"
+
+using namespace cadabra;
+
+untrace::untrace(const Kernel& k, Ex& tr)
+	: Algorithm(k, tr)
+	{
+	}
+
+bool untrace::can_apply(iterator st)
+	{
+	const Trace *trace = kernel.properties.get<Trace>(st);
+	if(trace) {
+		auto sib=tr.begin(st);
+		if(sib==tr.end(st))      return false;
+		if(*sib->name=="\\prod") return true;
+		if(is_single_term(sib))   return true;
+		}
+	return false;
+	}
+
+Algorithm::result_t untrace::apply(iterator& trloc)
+	{
+	const Trace *trace = kernel.properties.get<Trace>(trloc);
+	
+	// ensure we sit in a product
+	auto par=tr.parent(trloc);
+	iterator moveprod=par;
+	if(tr.is_head(trloc) || *par->name!="\\prod") {
+		moveprod=trloc;
+		prod_wrap_single_term(moveprod);
+		}
+
+	// ensure the argument is a product
+	iterator prodloc=tr.begin(trloc);
+	prod_wrap_single_term(prodloc);
+	
+	// scan arguments of trace
+	sibling_iterator st=tr.begin(prodloc);
+	while(st!=tr.end(prodloc)) {
+		sibling_iterator nxt=st;
+		++nxt;
+		
+		bool move_out=true;
+		
+		auto imp = kernel.properties.get<ImplicitIndex>(st);
+		if(imp) {
+			// std::cerr << st << " has implicit index" << std::endl;
+			if(imp->explicit_form.size()==0) move_out=false;
+			else {
+				iterator eb=imp->explicit_form.begin();
+				index_iterator ii=index_iterator::begin(kernel.properties, eb);
+				while(ii!=index_iterator::end(kernel.properties, eb)) {
+					auto ind=kernel.properties.get<Indices>(ii, true);
+					if(ind) {
+						// std::cerr << "seen set name " << ind->set_name << std::endl;
+						if(ind->set_name==trace->index_set_name) {
+							move_out=false;
+							break;
+							}
+						}
+					else {
+						// no Indices property known, better be safe.
+						move_out=false;
+						break;
+						}
+					++ii;
+					}
+				}
+			}
+		
+		if(move_out) {
+			tr.move_before(trloc, st);
+			//multiply(it->multiplier, sign);
+			}
+		
+		st=nxt;
+		}
+
+	// Trace of empty product should become trace of 1.
+	if(tr.number_of_children(prodloc)==0)
+		node_one(prodloc);
+
+	trloc = moveprod;
+	// std::cerr << trloc << std::endl;
+	return result_t::l_no_action;
+	}
diff --git a/core/algorithms/untrace.hh b/core/algorithms/untrace.hh
@@ -0,0 +1,16 @@
+
+#pragma once
+
+#include "Algorithm.hh"
+
+namespace cadabra {
+
+class untrace : public Algorithm {
+	public:
+		untrace(const Kernel&, Ex&);
+
+		virtual bool     can_apply(iterator) override;
+		virtual result_t apply(iterator&) override;
+};
+
+}
diff --git a/core/properties/Trace.cc b/core/properties/Trace.cc
@@ -23,6 +23,9 @@ bool Trace::parse(Kernel&, keyval_t& keyvals)
 	keyval_t::const_iterator kv=keyvals.find("object");
 	if(kv!=keyvals.end())
 		obj = kv->second;
+	kv=keyvals.find("indices");
+	if(kv!=keyvals.end()) 
+		index_set_name=*(kv->second->name);
 	return true;
 	}
 
diff --git a/core/properties/Trace.hh b/core/properties/Trace.hh
@@ -16,6 +16,7 @@ namespace cadabra {
 			virtual void        latex(std::ostream&) const override;
 			
 			Ex obj;
+			std::string index_set_name; // refers to Indices::set_name
 	};
 
 }
diff --git a/core/pythoncdb/py_algorithms.cc b/core/pythoncdb/py_algorithms.cc
diff --git a/doc/modules.dox b/doc/modules.dox
diff --git a/frontend/gtkmm/CMakeLists.txt b/frontend/gtkmm/CMakeLists.txt
diff --git a/tests/implicit.cdb b/tests/implicit.cdb
diff --git a/web2/cadabra2/source/developers.html b/web2/cadabra2/source/developers.html
