Reorganised documentation, adding Foundations module, and merged Stor…

…age module into Geometry module.

doc/differential_algebra.dox

@@ -31,7 +31,7 @@
 \page differential_algebra_page Differential Algebra and Automatic Differentiation
 
 This page describes the mathematical framework of differential algebra, and the algorithms of automatic differentiation.
-For details on how this is implemented in %Ariadne, see the \ref DifferentiationModule documentation.
+For details on how this is implemented in %Ariadne, see the \ref DifferentiationSubModule documentation.
 
 \b References
 - Andreas Griewank and Andrea Walther, <em>Evaluating Derivatives: Principles and Techniques of Algorithmic Differentiation</em> , SIAM, 2008. ISBN 0-89871-659-4

doc/linear_algebra.dox

@@ -32,7 +32,7 @@
 \page linear_algebra_page Linear Algebra
 
 This page describes the basic data structures and mathematical algorithms of computational linear algebra.
-For details on how this is implemented in %Ariadne, see the \ref LinearAlgebraModule documentation.
+For details on how this is implemented in %Ariadne, see the \ref LinearAlgebraSubModule documentation.
 
 \b References
 - David C. Lay, <em>Linear Algebra and its Applicatons</em>, Addison-Wesley, 2002. ISBN 0-20170-970-8

doc/logic.dox

@@ -34,7 +34,7 @@ namespace Ariadne {
 \page logic_page %Logical Foundations
 
 This page describes the logical foundations of computable analysis.
-For details on how this is implemented in %Ariadne, see the \ref LogicalModule documentation.
+For details on how this is implemented in %Ariadne, see the \ref LogicSubModule documentation.
 
 The foundations of computability theory underpinning this material is described on the \ref computable_analysis_page page.
 For information about computability theory for real numbers, see the \ref real_numbers_page page.

doc/modules.dox

@@ -1,7 +1,7 @@
 /***************************************************************************
  *            modules.dox
  *
- *  Copyright  2006-20  Pieter Collins
+ *  Copyright  2006-24  Pieter Collins
  *
  ****************************************************************************/
 
@@ -81,9 +81,45 @@ namespace Ariadne {
 
 
 
-
-/*!\defgroup LogicalModule Logical Module
+/*! \defgroup FoundationsModule Foundations Module
  * \ingroup CoreModules
+ *
+ *  \brief Foundational classes for information, logic, and general topology.
+ */
+
+
+
+/*!\defgroup InformationSubModule Information
+ * \ingroup FoundationsModule
+ * \brief Tag classes describing the information provided by a type, notably \ref ExactTag, as \ref EffectiveTag, \ref ValidatedTag and \ref ApproximateTag.
+ * \details <em>For the mathematical theory of computable analysis and kinds of information, see the \ref computable_analysis_page Page.</em>
+ *
+ * \anchor information_section
+ *
+ * In order to indicate the kind of guarantees on the approximation provided by a concrete object,
+ *   every type in %Ariadne has an associated <em>Paradigm</em> tag, denoted by the tempate parameter \c P.
+ * The \ref ExactTag indicates that the object represents a value exactly, and with decidable equality.
+ * The \ref EffectiveTag indicates that an object allows approximations to be computed to arbitrary, known accuracy.
+ * The \ref ValidatedTag indicates that the objects provides an approximation with guarantees on the error, such as lower- and upper-bounds, or an error bound.
+ * The \ref ApproximateTag indicates that the object is an approximation with no guarantees on the accuracy.
+ *
+ * Whenever the paradigm tag <tt>P</tt> occurs as a template parameter, a type alias is given in which the type is prefixed by the tag name. For example, \ref Number "Number<ValidatedTag>" has alias \ref Number::ValidatedNumber "ValidatedNumber", and \ref Function "Function<EffectiveTag,SIG>" has alias \ref EffectiveFunction "EffectiveFunction<SIG>".
+ *
+ * \remark In a future version of %Ariadne, it may be the case that information tags are replaced by template prefixes, so \ref Number "Number<ValidatedTag>" becomes <tt>Validated<Number></tt>.
+ *
+ * \subsection builtin_type_tag_section Builtin type tag
+ *
+ * %Ariadne also needs to handle built-in C++ types, notably \c Bool, \c Int and \c double (floating-point) classes.
+ * Since C++ internally allows unsafe and inexact conversions e.g
+ *     \code  Int n=1.5; // n is set to 1! \endcode
+ * and
+ *     \code  double x=1.3; // x not exactly equal to 1.3! \endcode
+ * care must be taken when using these objects. The \ref BuiltinTag tag is used to describe these objects.
+ * %BuiltinTag objects should be immediately converted to %Ariadne objects in user code.
+ */
+
+ /*!\defgroup LogicalSubModule Logic
+ * \ingroup FoundationsModule
  * \brief Logical types, including \ref Boolean, \ref Sierpinskian and \ref Kleenean types.
  * \details <em>For the mathematical theory of non-Boolean and constructive logic, see the \ref logic_page Page.</em>
  *
@@ -150,43 +186,15 @@ namespace Ariadne {
  */
 
 
-/*!\defgroup TopologySubModule Topology Module
- * \ingroup CoreModules
+/*!\defgroup TopologySubModule Topology
+ * \ingroup FoundationsModule
  * \brief Topological constructs, including \ref Bounds "Bounds<Q>" and \ref Ball "Ball<Q,E>" types, and general constructions.
  * \details <em>For the mathematical theory of computable topology, see the \ref topology_page Page.</em>
  *
  * In this module, we define %Ariadne's base topological types.
  * The main classes are \ref Ariadne::Bounds "Bounds<Q>", with subtypes \ref LowerBound "LowerBound<Q>" and \ref UpperBound "UpperBound<Q>", and \ref Ariadne::Ball "Ball<Q,R>".
  */
 
-/*!\defgroup InformationSubModule Information Module
- *   \ingroup CoreModules
- * \brief Tag classes describing the information provided by a type, notably \ref ExactTag, as \ref EffectiveTag, \ref ValidatedTag and \ref ApproximateTag.
- * \details <em>For the mathematical theory of computable analysis and kinds of information, see the \ref computable_analysis_page Page.</em>
- *
- * \anchor information_section
- *
- * In order to indicate the kind of guarantees on the approximation provided by a concrete object,
- *   every type in %Ariadne has an associated <em>Paradigm</em> tag, denoted by the tempate parameter \c P.
- * The \ref ExactTag indicates that the object represents a value exactly, and with decidable equality.
- * The \ref EffectiveTag indicates that an object allows approximations to be computed to arbitrary, known accuracy.
- * The \ref ValidatedTag indicates that the objects provides an approximation with guarantees on the error, such as lower- and upper-bounds, or an error bound.
- * The \ref ApproximateTag indicates that the object is an approximation with no guarantees on the accuracy.
- *
- * Whenever the paradigm tag <tt>P</tt> occurs as a template parameter, a type alias is given in which the type is prefixed by the tag name. For example, \ref Number "Number<ValidatedTag>" has alias \ref Number::ValidatedNumber "ValidatedNumber", and \ref Function "Function<EffectiveTag,SIG>" has alias \ref EffectiveFunction "EffectiveFunction<SIG>".
- *
- * \remark In a future version of %Ariadne, it may be the case that information tags are replaced by template prefixes, so \ref Number "Number<ValidatedTag>" becomes <tt>Validated<Number></tt>.
- *
- * \subsection builtin_type_tag_section Builtin type tag
- *
- * %Ariadne also needs to handle built-in C++ types, notably \c Bool, \c Int and \c double (floating-point) classes.
- * Since C++ internally allows unsafe and inexact conversions e.g
- *     \code  Int n=1.5; // n is set to 1! \endcode
- * and
- *     \code  double x=1.3; // x not exactly equal to 1.3! \endcode
- * care must be taken when using these objects. The \ref BuiltinTag tag is used to describe these objects.
- * %BuiltinTag objects should be immediately converted to %Ariadne objects in user code.
- */
 
 /*!
  * \defgroup NumericModule Numeric Module
@@ -314,9 +322,16 @@ namespace Ariadne {
  * \details In Python, the C++ operator is used as a function, e.g. \c 1.23_pr is replaced by \c pr_(1.23) .
  */
 
+
 /*!
- * \defgroup LinearAlgebraModule Linear Algebra Module
+ * \defgroup AlgebraModule Algebra Module
  * \ingroup CoreModules
+ * \brief Algebraic data types, notably for linear algebra and differential algebra.
+ */
+
+/*!
+ * \defgroup LinearAlgebraSubModule Linear Algebra Submodule
+ * \ingroup AlgebraModule
  * \brief \ref Vector "Vector<X>", \ref Matrix "Matrix<X>" and \ref Tensor "Tensor<N,X>" classes,
  * solution of linear equations, LU and QR factorisation and singular value decomposition.
  *
@@ -347,8 +362,8 @@ namespace Ariadne {
  *
  */
 
-/*!\defgroup DifferentiationModule  Differentiation Module
- * \ingroup CoreModules
+/*!\defgroup DifferentiationSubModule Differentiation Submodule
+ * \ingroup AlgebraModule
  * \brief Support for automatic differentiation using Taylor expansions, including the general \ref Differential "Differential<X>" class, fixed-order \ref FirstDifferential "FirstDifferential<X>" and \ref SecondDifferential "SecondDifferential<X>", and \ref UnivariateDifferential "UnivariateDifferential<X>" classes.
  *
  * \details <em>For the mathematical theory of automatic differentiation, see the \ref differential_algebra_page Page.</em>
@@ -463,19 +478,8 @@ namespace Ariadne {
  * \ingroup GeometryModule
  * \brief Denotable sets based on arbitrary lists of elements.
  *
- * \defgroup HybridSetSubModule Hybrid sets
+ * \defgroup DiscretisedSetSubModule Discretised sets
  * \ingroup GeometryModule
- * \ingroup HybridModules
- * \brief Sets in spaces with many components.
- *
- * The state space of a hybrid system consists of many disconnected components,
- * one for each discrete mode. Hybrid sets consist of a union of many different
- * sets, one for each component of the state space.
- */
-
-
-/*!\defgroup StorageModule Storage Module
- * \ingroup CoreModules
  * \brief Classes for representing discretised sets
  *
  * A <em>subdivision tree</em> is a binary tree describing a subdivision of
@@ -565,6 +569,15 @@ namespace Ariadne {
  *  \brief Hybrid system classes.
  */
 
+/*! \defgroup HybridSetSubModule Hybrid sets
+ *    \ingroup HybridModules
+ *  \brief Sets in spaces with many components.
+ *
+ *  The state space of a hybrid system consists of many disconnected components,
+ *  one for each discrete mode. Hybrid sets consist of a union of many different
+ *  sets, one for each component of the state space.
+ */
+
 /*! \defgroup HybridDynamicsSubModule Hybrid evolution
  *    \ingroup HybridModules
  *  \brief Classes and functions for analysing hybrid dynamic systems.

doc/python_module_demonstrations.dox

@@ -155,7 +155,7 @@ and the \ref Approximation classes support approximate arithmetic.
 As well as matrix and vector arithmetic, %Ariadne provides a \c solve routine for solving systems of linear equations:
 \skipline solve
 
-\sa \ref LinearAlgebraModule
+\sa \ref LinearAlgebraSubModule
 
 
 

source/algebra/covector.hpp

@@ -61,7 +61,7 @@ template<class U> struct CovectorExpression : public DeclareCovectorOperations {
 template<class U> struct CovectorContainer : public CovectorExpression<U> { };
 
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief A covector (dual to a vector, or a row vector) over some type \a X.
 template<class X> class Covector
     : public CovectorContainer<Covector<X>>

source/algebra/diagonal_matrix.hpp

@@ -187,7 +187,7 @@ struct DiagonalMatrixOperations {
 };
 
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief Diagonal matrices over some type \a X.
 template<class X> class DiagonalMatrix
     : DiagonalMatrixOperations

source/algebra/differential.hpp

@@ -76,7 +76,7 @@ template<class X> inline DifferentialFactory<X> factory(Differential<X> const& d
 
 
 
-//! \ingroup DifferentiationModule
+//! \ingroup DifferentiationSubModule
 //! \brief A class representing the partial derivatives of a scalar quantity
 //! depending on multiple arguments.
 //!

source/algebra/fixed_differential.hpp

@@ -130,7 +130,7 @@ template<class X> class FixedDifferentialCharacteristics {
     X zero_coefficient() const { return this->_zero_coefficient; }
 };
 
-//! \ingroup DifferentiationModule
+//! \ingroup DifferentiationSubModule
 //! \brief A class representing the partial derivatives of a scalar quantity
 //! depending on multiple arguments.
 //!
@@ -409,7 +409,7 @@ class Vector< FirstDifferential<X> >
 
 
 
-//! \ingroup DifferentiationModule
+//! \ingroup DifferentiationSubModule
 //! \brief A class representing the partial derivatives of a scalar quantity
 //! depending on multiple arguments.
 //!

source/algebra/fixed_univariate_differential.hpp

@@ -35,7 +35,7 @@ namespace Ariadne {
 
 template<class X> class DifferentialFactory;
 
-//! \ingroup DifferentiationModule
+//! \ingroup DifferentiationSubModule
 //! \brief A class representing the value and derivative of a scalar quantity
 //! depending on a single argument.
 template<class X>
@@ -222,7 +222,7 @@ template<class X> struct AlgebraOperations<UnivariateFirstDifferential<X>,X> {
 
 
 
-//! \ingroup DifferentiationModule
+//! \ingroup DifferentiationSubModule
 //! \brief A class representing the value, first and second derivatives of a scalar quantity
 //! depending on a single argument.
 template<class X>

source/algebra/matrix.hpp

@@ -117,7 +117,7 @@ class DispatchMatrixOperations {
 };
 */
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief Matrices over some type \a X.
 template<class X> class Matrix
     : public MatrixContainer<Matrix<X>>
@@ -249,7 +249,7 @@ template<AMatrixExpression M> OutputStream& operator<<(OutputStream& os, M const
 
 /************ Combinatorial Matrices *********************************************************/
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief Permutation matrices defined as a sequence of transpositions.
 //! \details Pre-multiplying a matrix \f$A\f$ by the pivot matrix with pivots \f$[p_0,p_1,\ldots,p_{n-1}]\f$
 //!   first swaps row \f$0\f$ of \f$A\f$ with row \f$p_0\f$, then row \f$1\f$ of the new matrix with row \f$p_1\geq1\f$ of the new matrix,
@@ -390,7 +390,7 @@ template<class M1, class X2> struct MatrixScalarQuotient {
 };
 template<class M1, class X2> struct IsMatrixExpression<MatrixScalarQuotient<M1,X2>> : True { };
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief A view into a submatrix of a matrix of class \a M.
 //! \see Matrix, Range
 template<class M> struct MatrixRange

source/algebra/range.hpp

@@ -33,7 +33,7 @@
 
 namespace Ariadne {
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief A range of integer values from a \em start value up to, but not including, a \em stop value.
 class Range {
     SizeType _start; SizeType _stop;

source/algebra/tensor.hpp

@@ -45,7 +45,7 @@ template<class T> class TensorRow {
     T& operator[] (SizeType j) { return _t[Array<SizeType>({_i,j})]; }
 };
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief A rank-\a N tensor with elements of type \a X.
 template<SizeType N, class X> class Tensor :
                       public LabelledDrawable2d3dInterface,

source/algebra/univariate_differential.hpp

@@ -40,7 +40,7 @@ namespace Ariadne {
 template<class X> class Series;
 template<class X> class UnivariateDifferential;
 
-//! \ingroup DifferentiationModule
+//! \ingroup DifferentiationSubModule
 //! \brief Arbitrary-order derivatives with respect to a single argument.
 template<class X> class UnivariateDifferential
     : public DispatchTranscendentalAlgebraOperations<UnivariateDifferential<X>,X>

source/algebra/vector.hpp

@@ -42,7 +42,7 @@
 
 namespace Ariadne {
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief A scalar of type \a X; defined as an synonym (typedef) of \a X.
 template<class X> using Scalar = X;
 
@@ -153,7 +153,7 @@ template<class V> struct VectorContainer : public VectorExpression<V> { };
 
 struct DefaultTag { };
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! \brief Vectors over some type \a X.
 //! Corresponds to elements of a \em module over a mathematical \em ring, or a <em>vector space</em> over a field.
 //! May also be used if \a X is an \em algebra \a A over another field.
@@ -339,7 +339,7 @@ class Vector
 
 template<class X> struct IsVector<Vector<X>> : True { };
 
-//! \ingroup LinearAlgebraModule
+//! \ingroup LinearAlgebraSubModule
 //! A view into a subvector of a vector of class \a V.
 //! \see Vector, Range
 template<class V> class VectorRange