Merge pull request #28 from jointpoints/development

Update to v.3.0.1

Author: jointpoints

README.md

@@ -3,6 +3,12 @@
 
 This repository contains a C++ generator of digital (t, m, s)-nets in base 2 as well as a number of tools to measure their figures of merit.
 
+Available nets:
+
+* Sobol,
+* Niederreiter,
+* Any digital net with manually set generating matrices.
+
 Broadly speaking, (t, m, s)-nets are low-discrepancy finite sets of points in _s_-dimensional unit cube. They have been proven to be efficient in a number of Numerical Analysis tasks.
 
 ![Example of a net](tools/custom_dox_content/tutorial1_Step4_1.jpg)

include/tms-nets.hpp

@@ -16,7 +16,7 @@
 // Include generators
 #include "tms-nets/digital_net.hpp"
 #include "tms-nets/niederreiter.hpp"
-#include "tms-nets/modified_niederreiter.hpp"
+#include "tms-nets/sobol.hpp"
 // Include details
 #include "tms-nets/details/genmat.hpp"
 // Include analysis

include/tms-nets/analysis/analysis.hpp

@@ -46,6 +46,14 @@ namespace tms::analysis
 	 * @param   net     A digital net.
 	 * 
 	 * @returns Precise value of parameter \f$t\f$ for the given digital net.
+	 * 
+	 * @throws  invalid_argument    If at least one generating matrix of the given net is degenerate
+	 *                              (determinant equals zero over \f$\mathbb{F}_2\f$).
+	 * 
+	 * @note Exceptions will never be encountered in this function if it used with \c Niederreiter
+	 * and \c Sobol nets provided in this library. Their generating matrices are \b guaranteed to
+	 * always be non-degenerate. If you discover a case when this function fails to perform on these
+	 * nets, [<b>report a bug</b>](https://github.com/jointpoints/tms-nets/issues/new).
 	 */
 	BasicInt            t               (DigitalNet const &net);
 

include/tms-nets/details/common.hpp

@@ -7,65 +7,109 @@
 #include <stdexcept>
 
 
+/** @namespace tms
+ *  @brief All the entities in the library are defined in this namespace. */
 namespace tms
 {
-	using DirNumInt  = uintmax_t;
-	
-	using IntPoint   = std::vector<DirNumInt>;
-	/// Type used for storing integer values that are less than word size.
+	/// A type for integer values that are less than word size (e.g. m, s parameters of the net)
 	using BasicInt   = unsigned int;
-	/// Type used for storing quantity-values and indexation-values, i.e. the total amount of points to generate.
+	/// A type for integer counting values, (e.g. number of net's point)
 	using CountInt   = uintmax_t;
-	/// Type used for storing coordinates of points of (t,m,s)-net.
+	/// A type of coordinates of points of (t, m, s)-net
 	using Real	     = long double;
-	/// Type used for storing points of (t,m,s)-net.
+	/// Represents a generating number of a digital (t, m, s)-net
+	using GenNumInt = uintmax_t;
+	/// Represents a point of a scaled (t, m, s)-net
+	using IntPoint   = std::vector<uintmax_t>;
+	/// Represents a point of a (t, m, s)-net
 	using Point	     = std::vector<Real>;
-	/// Type used for storing polynomials.
+	/// Represents a polynomial over GF[2]
 	using Polynomial = irrpoly::gfpoly;
 
-	class DirNum;
+	
+	/// Highest allowed m parameter value of created nets, i.e. highest bit depth value
+	BasicInt const max_nbits = sizeof(uintmax_t)*8;
+	
+	
+	class GenNum;
 
 	class GenMatRow;
 
 	class GenMat;
 
-	BasicInt const max_nbits = sizeof(DirNumInt)*8;
-	
 
-	class DirNum
+	/** @class GenNum
+	 *  @brief Represents container of generating numbers of a digital net.
+	 *         Can be used as a shortened version of generating matrix  */
+	class GenNum
 	{
 	public:
 
-		DirNum(void);
-		DirNum(DirNum const&);
-		DirNum(DirNum &&);
+		/// Creates empty container with no generating numbers
+		GenNum(void);
+		GenNum(GenNum const&);
+		GenNum(GenNum &&);
+		
+		~GenNum(void);
 
-		~DirNum(void);
+		GenNum& operator =(GenNum const &);
+		GenNum& operator =(GenNum &&);
 
-		DirNum& operator =(DirNum const &);
-		DirNum& operator =(DirNum &&);
+		/** Creates generating numbers with given values
+		 *  @param values – vector of generating numbers values */
+		GenNum(std::vector<GenNumInt> const &values);
 
-		DirNum(std::vector<DirNumInt> const &values);
-		DirNum(BasicInt size);
-		//DirNum(GenMat   const &gen_mat);
+		/** Creates certain amount of zero defined generating numbers
+		 *  @param amount – amount of generating numbers */
+		GenNum(BasicInt amount);
 
+		/// Casts generating numbers to the corresponding generating matrix
 		explicit operator GenMat(void) const;
 
+		/// Checks whether generating numbers container is empty
+		bool       empty(void) const;
+		
+		/// Checks whether the corresponding generating matrix is toeplitz
+		bool       is_toeplitz(void) const;
+		
+		/// Returns amount of generating numbers in the containter
 		BasicInt   size(void) const;
+		
+		/** Returns certain bit of a generating number addressed as an element of generating matrix
+		 *  @param i – row number
+		 *  @param j – column number */
 		bool       get_bit(BasicInt i, BasicInt j) const;
-		DirNumInt  operator[](BasicInt n) const;
 
+		/** Returns certain generating number
+		 *  @param n – index of a number */
+		uintmax_t  operator[](BasicInt n) const;
+		
+		/** Sets new bit value of a certain generating number addressed as an element of generating matrix
+		 *  @param i – row number
+		 *  @param j – column number
+		 *  @param value – new bit value */
 		void       set_bit(BasicInt i, BasicInt j, bool value);
-		DirNumInt& operator[](BasicInt n);
+		
+		/** Returns reference to a certain generating number
+		 *  @param n – index of a number */
+		uintmax_t& operator[](BasicInt n);
+		
+		GenNum& operator *=(GenNum const& l);
+		
+		friend bool operator ==(GenNum const &r, GenNum const &l);
 
 
 	private:
 
 		BasicInt               m_nbits;
-		std::vector<DirNumInt> m_numbers;
+		std::vector<GenNumInt> m_numbers;
 	};
 
+	GenNum operator * (GenNum r, GenNum const &l);
+	bool   operator !=(GenNum const &l, GenNum const &r);
+	
 
+	/** Represents a row of a generating matrix */
 	class GenMatRow
 	{
 	public:
@@ -83,6 +127,8 @@ namespace tms
 		GenMatRow(std::vector<uint8_t> const &values_vector); //?
 		GenMatRow(std::initializer_list<uint8_t> const &values_list);
 
+		bool     empty(void) const;
+		
 		BasicInt size(void) const;
 		uint8_t  operator [](BasicInt n) const;
 		uint8_t& operator [](BasicInt n);
@@ -127,13 +173,15 @@ namespace tms
 		GenMat(std::vector<GenMatRow> const &matrix);
 		GenMat(std::initializer_list<GenMatRow> const &lines_list);
 
-		explicit operator DirNum(void) const;
+		explicit operator GenNum(void) const;
 
-		BasicInt size(void) const;
+		bool       empty(void) const;
+		
+		BasicInt   size(void) const;
 		GenMatRow  operator [](BasicInt n) const;
 		GenMatRow& operator [](BasicInt n);
 
-		bool   is_shifted(void) const;
+		bool   is_toeplitz(void) const;
 		GenMat inverse(void) const;
 
 		GenMat& operator *=(GenMat const &r);
@@ -159,30 +207,38 @@ namespace tms
 
 
 
+	inline bool
+	GenNum::empty() const
+	{ return m_numbers.empty(); }
+	
 	inline BasicInt
-	DirNum::size(void) const
+	GenNum::size(void) const
 	{ return m_nbits; }
 
 	inline bool
-	DirNum::get_bit(BasicInt i, BasicInt j) const
+	GenNum::get_bit(BasicInt i, BasicInt j) const
 	{ return (m_numbers[j] >> (m_nbits - 1 - i)) & 1; }
 
-	inline DirNumInt
-	DirNum::operator[](BasicInt n) const
+	inline uintmax_t
+	GenNum::operator[](BasicInt n) const
 	{ return m_numbers[n]; }
 
 
 	inline void
-	DirNum::set_bit(BasicInt i, BasicInt j, bool value)
-	{ m_numbers[j] |= static_cast<DirNumInt>(value) << (m_nbits - 1 - i); }
+	GenNum::set_bit(BasicInt i, BasicInt j, bool value)
+	{ m_numbers[j] |= static_cast<uintmax_t>(value) << (m_nbits - 1 - i); }
 
-	inline DirNumInt&
-	DirNum::operator[](BasicInt n)
+	inline uintmax_t&
+	GenNum::operator[](BasicInt n)
 	{ return m_numbers[n]; }
 
 
 
 
+	inline bool
+	GenMatRow::empty(void) const
+	{ return m_values.empty(); }
+	
 	inline BasicInt
 	GenMatRow::size(void) const
 	{ return static_cast<BasicInt>(m_values.size()); }
@@ -198,6 +254,10 @@ namespace tms
 
 
 
+	inline bool
+	GenMat::empty() const
+	{ return m_rows.empty(); }
+	
 	inline BasicInt
 	GenMat::size(void) const
 	{ return m_nbits; }