X-Git-Url: https://www.ginac.de/ginac.git//ginac.git?p=ginac.git;a=blobdiff_plain;f=ginac%2Fflags.h;h=ef921600aaa25483a58d54e846007b8c395a33e9;hp=62cd82a4e0840a9c9ae2e241aded65ca7dccfcc7;hb=f78b1f296310b5f1c01b74c9fb10dd33af2a8f4a;hpb=dbd9c306a74f1cb258c0d15a346b973b39deaad2
diff --git a/ginac/flags.h b/ginac/flags.h
index 62cd82a4..ef921600 100644
--- a/ginac/flags.h
+++ b/ginac/flags.h
@@ -25,12 +25,25 @@
namespace GiNaC {
+/** Flags to control the behavior of expand(). */
class expand_options {
public:
enum {
- expand_trigonometric = 0x0001,
- expand_indexed = 0x0002,
- expand_function_args = 0x0004
+ expand_indexed = 0x0001, ///< expands (a+b).i to a.i+b.i
+ expand_function_args = 0x0002 ///< expands the arguments of functions
+ };
+};
+
+/** Flags to control the behavior of subs(). */
+class subs_options {
+public:
+ enum {
+ no_pattern = 0x0001, ///< disable pattern matching
+ subs_no_pattern = 0x0001, // for backwards compatibility
+ algebraic = 0x0002, ///< enable algebraic substitutions
+ subs_algebraic = 0x0002, // for backwards compatibility
+ pattern_is_product = 0x0004, ///< used internally by expairseq::subschildren()
+ pattern_is_not_product = 0x0008 ///< used internally by expairseq::subschildren()
};
};
@@ -38,6 +51,10 @@ public:
class series_options {
public:
enum {
+ /** Suppress branch cuts in series expansion. Branch cuts manifest
+ * themselves as step functions, if this option is not passed. If
+ * it is passed and expansion at a point on a cut is performed, then
+ * the analytic continuation of the function is expanded. */
suppress_branchcut = 0x0001
};
};
@@ -46,11 +63,52 @@ public:
class determinant_algo {
public:
enum {
- automatic, ///< Let the system choose
- gauss, ///< Gauss elimiation
- divfree, ///< Division-free elimination
- laplace, ///< Laplace (or minor) elimination
- bareiss ///< Bareiss fraction-free elimination
+ /** Let the system choose. A heuristics is applied for automatic
+ * determination of a suitable algorithm. */
+ automatic,
+ /** Gauss elimination. If \f$m_{i,j}^{(0)}\f$ are the entries of the
+ * original matrix, then the matrix is transformed into triangular
+ * form by applying the rules
+ * \f[
+ * m_{i,j}^{(k+1)} = m_{i,j}^{(k)} - m_{i,k}^{(k)} m_{k,j}^{(k)} / m_{k,k}^{(k)}
+ * \f]
+ * The determinant is then just the product of diagonal elements.
+ * Choose this algorithm only for purely numerical matrices. */
+ gauss,
+ /** Division-free elimination. This is a modification of Gauss
+ * elimination where the division by the pivot element is not
+ * carried out. If \f$m_{i,j}^{(0)}\f$ are the entries of the
+ * original matrix, then the matrix is transformed into triangular
+ * form by applying the rules
+ * \f[
+ * m_{i,j}^{(k+1)} = m_{i,j}^{(k)} m_{k,k}^{(k)} - m_{i,k}^{(k)} m_{k,j}^{(k)}
+ * \f]
+ * The determinant can later be computed by inspecting the diagonal
+ * elements only. This algorithm is only there for the purpose of
+ * cross-checks. It is never fast. */
+ divfree,
+ /** Laplace elimination. This is plain recursive elimination along
+ * minors although multiple minors are avoided by the algorithm.
+ * Although the algorithm is exponential in complexity it is
+ * frequently the fastest one when the matrix is populated by
+ * complicated symbolic expressions. */
+ laplace,
+ /** Bareiss fraction-free elimination. This is a modification of
+ * Gauss elimination where the division by the pivot element is
+ * delayed until it can be carried out without computing
+ * GCDs. If \f$m_{i,j}^{(0)}\f$ are the entries of the original
+ * matrix, then the matrix is transformed into triangular form by
+ * applying the rules
+ * \f[
+ * m_{i,j}^{(k+1)} = (m_{i,j}^{(k)} m_{k,k}^{(k)} - m_{i,k}^{(k)} m_{k,j}^{(k)}) / m_{k-1,k-1}^{(k-1)}
+ * \f]
+ * (We have set \f$m_{-1,-1}^{(-1)}=1\f$ in order to avoid a case
+ * distinction in above formula.) It can be shown that nothing more
+ * than polynomial long division is needed for carrying out the
+ * division. The determinant can then be read of from the lower
+ * right entry. This algorithm is rarely fast for computing
+ * determinants. */
+ bareiss
};
};
@@ -58,10 +116,48 @@ public:
class solve_algo {
public:
enum {
- automatic, ///< Let the system choose
- gauss, ///< Gauss elimiation
- divfree, ///< Division-free elimination
- bareiss ///< Bareiss fraction-free elimination
+ /** Let the system choose. A heuristics is applied for automatic
+ * determination of a suitable algorithm. */
+ automatic,
+ /** Gauss elimination. If \f$m_{i,j}^{(0)}\f$ are the entries of the
+ * original matrix, then the matrix is transformed into triangular
+ * form by applying the rules
+ * \f[
+ * m_{i,j}^{(k+1)} = m_{i,j}^{(k)} - m_{i,k}^{(k)} m_{k,j}^{(k)} / m_{k,k}^{(k)}
+ * \f]
+ * This algorithm is well-suited for numerical matrices but generally
+ * suffers from the expensive division (and computation of GCDs) at
+ * each step. */
+ gauss,
+ /** Division-free elimination. This is a modification of Gauss
+ * elimination where the division by the pivot element is not
+ * carried out. If \f$m_{i,j}^{(0)}\f$ are the entries of the
+ * original matrix, then the matrix is transformed into triangular
+ * form by applying the rules
+ * \f[
+ * m_{i,j}^{(k+1)} = m_{i,j}^{(k)} m_{k,k}^{(k)} - m_{i,k}^{(k)} m_{k,j}^{(k)}
+ * \f]
+ * This algorithm is only there for the purpose of cross-checks.
+ * It suffers from exponential intermediate expression swell. Use it
+ * only for small systems. */
+ divfree,
+ /** Bareiss fraction-free elimination. This is a modification of
+ * Gauss elimination where the division by the pivot element is
+ * delayed until it can be carried out without computing
+ * GCDs. If \f$m_{i,j}^{(0)}\f$ are the entries of the original
+ * matrix, then the matrix is transformed into triangular form by
+ * applying the rules
+ * \f[
+ * m_{i,j}^{(k+1)} = (m_{i,j}^{(k)} m_{k,k}^{(k)} - m_{i,k}^{(k)} m_{k,j}^{(k)}) / m_{k-1,k-1}^{(k-1)}
+ * \f]
+ * (We have set \f$m_{-1,-1}^{(-1)}=1\f$ in order to avoid a case
+ * distinction in above formula.) It can be shown that nothing more
+ * than polynomial long division is needed for carrying out the
+ * division. This is generally the fastest algorithm for solving
+ * linear systems. In contrast to division-free elimination it only
+ * has a linear expression swell. For two-dimensional systems, the
+ * two algorithms are equivalent, however. */
+ bareiss
};
};
@@ -70,10 +166,11 @@ public:
class status_flags {
public:
enum {
- dynallocated = 0x0001, ///< Heap-allocated (i.e. created by new if we want to be clever and bypass the stack, @see ex::construct_from_basic() )
- evaluated = 0x0002, ///< .eval() has already done its job
- expanded = 0x0004, ///< .expand(0) has already done its job (other expand() options ignore this flag)
- hash_calculated = 0x0008 ///< .calchash() has already done its job
+ dynallocated = 0x0001, ///< heap-allocated (i.e. created by new if we want to be clever and bypass the stack, @see ex::construct_from_basic() )
+ evaluated = 0x0002, ///< .eval() has already done its job
+ expanded = 0x0004, ///< .expand(0) has already done its job (other expand() options ignore this flag)
+ hash_calculated = 0x0008, ///< .calchash() has already done its job
+ not_shareable = 0x0010 ///< don't share instances of this object between different expressions unless explicitly asked to (used by ex::compare())
};
};