[Boost-commit] svn:boost r64233 - in sandbox/SOC/2010/quasi_random: . libs/random/doc

Subject: [Boost-commit] svn:boost r64233 - in sandbox/SOC/2010/quasi_random: . libs/random/doc
From: jvd_at_[hidden]
Date: 2010-07-21 15:41:51

Author: qrng
Date: 2010-07-21 15:41:50 EDT (Wed, 21 Jul 2010)
New Revision: 64233
URL: http://svn.boost.org/trac/boost/changeset/64233

Log:
Initial documentation

Added:
   sandbox/SOC/2010/quasi_random/Jamfile.v2   (contents, props changed)
   sandbox/SOC/2010/quasi_random/LICENSE_1_0.txt   (contents, props changed)
   sandbox/SOC/2010/quasi_random/libs/random/doc/Jamfile.v2   (contents, props changed)
   sandbox/SOC/2010/quasi_random/libs/random/doc/main.qbk   (contents, props changed)
   sandbox/SOC/2010/quasi_random/project-root.jam   (contents, props changed)
Properties modified: 
   sandbox/SOC/2010/quasi_random/   (props changed)
   sandbox/SOC/2010/quasi_random/libs/random/doc/   (props changed)

Added: sandbox/SOC/2010/quasi_random/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/SOC/2010/quasi_random/Jamfile.v2	2010-07-21 15:41:50 EDT (Wed, 21 Jul 2010)
@@ -0,0 +1,11 @@
+# Copyright 2008-2009 Justinas Vygintas Daugmaudis.
+# Distributed under the Boost Software License, Version 1.0. (See accompanying
+# file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+project quasi_random
+    : requirements
+        <include>.
+        <include>$(BOOST_ROOT)
+    :
+        build-dir bin.v2
+    ;

Added: sandbox/SOC/2010/quasi_random/LICENSE_1_0.txt
==============================================================================
--- (empty file)
+++ sandbox/SOC/2010/quasi_random/LICENSE_1_0.txt	2010-07-21 15:41:50 EDT (Wed, 21 Jul 2010)
@@ -0,0 +1,23 @@
+Boost Software License - Version 1.0 - August 17th, 2003
+
+Permission is hereby granted, free of charge, to any person or organization
+obtaining a copy of the software and accompanying documentation covered by
+this license (the "Software") to use, reproduce, display, distribute,
+execute, and transmit the Software, and to prepare derivative works of the
+Software, and to permit third-parties to whom the Software is furnished to
+do so, all subject to the following:
+
+The copyright notices in the Software and this entire statement, including
+the above license grant, this restriction and the following disclaimer,
+must be included in all copies of the Software, in whole or in part, and
+all derivative works of the Software, unless such copies or derivative
+works are solely in the form of machine-executable object code generated by
+a source language processor.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT
+SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE
+FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

Added: sandbox/SOC/2010/quasi_random/libs/random/doc/Jamfile.v2
==============================================================================
--- (empty file)
+++ sandbox/SOC/2010/quasi_random/libs/random/doc/Jamfile.v2	2010-07-21 15:41:50 EDT (Wed, 21 Jul 2010)
@@ -0,0 +1,69 @@
+# Jamfile.v2
+#
+# Copyright (c) 2009
+# Steven Watanabe
+# Copyright (C) 2010
+# Justinas Vygintas Daugmaudis
+#
+# Distributed under the Boost Software License, Version 1.0. (See
+# accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+using quickbook ;
+using doxygen ;
+import boostbook ;
+import regex ;
+import os ;
+import path ;
+
+doxygen_files =
+    faure
+    niederreiter_base2
+    sobol
+;
+
+path-constant here : . ;
+
+doxygen reference :
+    $(here)/../../../boost/random/$(doxygen_files).hpp
+  :
+    <doxygen:param>EXPAND_ONLY_PREDEF=YES
+    <doxygen:param>"ALIASES= \\
+        xmlnote=\"@xmlonly <note><para> @endxmlonly\" \\
+        endxmlnote=\"@xmlonly </para></note> @endxmlonly\" \\
+        blockquote=\"@xmlonly <blockquote><para> @endxmlonly\" \\
+        endblockquote=\"@xmlonly </para></blockquote> @endxmlonly\" \\
+        boost=\"$(BOOST_ROOT)\" \\
+        niederreiter_base2=\"@xmlonly <classname alt=\\\"boost::random::niederreiter_base2\\\">niederreiter_base2</classname> @endxmlonly\" \\
+	sobol=\"@xmlonly <classname alt=\\\"boost::random::sobol\\\">sobol</classname> @endxmlonly\" \\
+	faure=\"@xmlonly <classname alt=\\\"boost::random::faure\\\">faure</classname> @endxmlonly\""
+    <doxygen:param>HIDE_UNDOC_MEMBERS=NO
+    <doxygen:param>QUIET=YES
+    <doxygen:param>WARN_IF_UNDOCUMENTED=NO
+    <doxygen:param>EXTRACT_PRIVATE=NO
+    <doxygen:param>ENABLE_PREPROCESSING=YES
+    <doxygen:param>MACRO_EXPANSION=YES
+    <doxygen:param>SEARCH_INCLUDES=NO
+    # Expand macros and clean up a bunch of ugly names
+    <doxygen:param>"PREDEFINED= \\
+        \"BOOST_RANDOM_DOXYGEN=1\" \\
+        \"BOOST_PREVENT_MACRO_SUBSTITUTION=\" \\
+        \"BOOST_STATIC_ASSERT(x)=\" \\
+        \"BOOST_STATIC_CONSTANT(type,value)=static const type value\" \\
+        \"BOOST_RANDOM_DETAIL_OSTREAM_OPERATOR(os,T,t)=template<class CharT, class Traits> friend std::basic_ostream<CharT,Traits>& operator<<(std::basic_ostream<CharT,Traits>& os, const T& t)\" \\
+        \"BOOST_RANDOM_DETAIL_ISTREAM_OPERATOR(is,T,t)=template<class CharT, class Traits> friend std::basic_istream<CharT,Traits>& operator>>(std::basic_istream<CharT,Traits>& is, const T& t)\" \\
+        \"BOOST_RANDOM_DETAIL_EQUALITY_OPERATOR(T,lhs,rhs)=friend bool operator==(const T& lhs, const T& rhs)\" \\
+        \"BOOST_RANDOM_DETAIL_INEQUALITY_OPERATOR(T)=friend bool operator!=(const T& lhs, const T& rhs) { return !(lhs == rhs); }\""
+    <reftitle>"Headers"
+    <doxygen:xml-imagedir>images/random
+;
+
+xml quasi_random : main.qbk : <dependency>reference ;
+
+boostbook standalone :
+    quasi_random
+  :
+    <implicit-dependency>reference
+    <xsl:param>boost.root=../../../..
+    <xsl:param>chunk.section.depth=2
+;

Added: sandbox/SOC/2010/quasi_random/libs/random/doc/main.qbk
==============================================================================
--- (empty file)
+++ sandbox/SOC/2010/quasi_random/libs/random/doc/main.qbk	2010-07-21 15:41:50 EDT (Wed, 21 Jul 2010)
@@ -0,0 +1,94 @@
+[/
+Copyright (c) 2010 Justinas Vygintas Daugmaudis
+
+Distributed under the Boost Software License, Version 1.0. (See accompanying
+file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[library Boost.Random Quasi-random number generators extension
+    [quickbook 1.5]
+    [copyright 2010 Justinas Vygintas Daugmaudis]
+    [purpose Generation of low discrepancy sequences]
+    [license
+        Distributed under the Boost Software License, Version 1.0.
+        (See accompanying file LICENSE_1_0.txt or copy at
+        [@http://www.boost.org/LICENSE_1_0.txt])
+    ]
+    [authors [Daugmaudis, Justinas]]
+]
+
+
+[section Quasi-Random Number Generator]
+
+A quasi-random number generator is a __PseudoRandomNumberGenerator which
+provides a deterministic sequence of quasi-random numbers, based on some
+algorithm and internal state. [classref boost::random::niederreiter_base2
+Niederreiter Base 2] generator is an example of such a [qrng quasi-random
+number generator]. The "quasi" modifier is used to denote more clearly that the
+values produced by such a generator are neither random nor pseudo-random, but
+they form a low discrepancy sequence. The intuitive idea is that a low discrepancy 
+sequence is more evenly distributed than a pseudo random sequence would be.
+For example, if we generate a low discrepancy sequence of 2D points on a square,
+this square would be covered more evenly, and the number of points falling to any
+part of the square would be proportional to the number of points in the whole square.
+Such sequences share some properties of  random variables and in certain applications 
+such as the quasi-Monte Carlo method  their lower discrepancy is an important advantage.
+
+[note Quasi-random sequences are known to give efficient numerical integration 
+rules in many Bayesian statistical problems where the posterior distribution can be 
+transformed into periodic functions on the n-dimensional hypercube.]
+
+Harold Niederreiter gives an extensive overview on random number generation
+and quasi-Monte Carlo methods in his book "Random number generation and
+quasi-Monte Carlo methods, Society for Industrial and Applied Mathematics, 1992". 
+
+In addition to the __PseudoRandomNumberGenerator requirements,
+a quasi-random number generator has some additional requirements. In the
+following table, `X` denotes a quasi-random number generator class, and `v` is 
+a const value of `X`.
+
+[table QuasiRandomNumberGenerator requirements
+  [[expression] [return type] [pre/post-condition]]
+  [[`X::dimension()`] [std::size_t] [the dimension of quasi-random domain. It must be no less than 1.
+                        The return value of this function shall not change during the lifetime of the object.]]
+ ]
+
+[note The `operator()` returns a successive element of an n-dimensional (n = `X::dimension`) vector 
+at each invocation. When all elements are exhausted, `operator()` begins anew with the starting
+element of a subsequent n-dimensional vector.]
+
+The class __niederreiter_base2 is a model for a quasi-random number generator.
+
+[endsect]
+
+
+[section:HeaderSummary Header File Summary]
+The following table contains header files used within the quasi-random number generators library extension.
+For additional information please use the table of contents above.
+[table
+   [[Component][Header][Contence]]
+   [
+      [`niederreiter_base2` type]
+      [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/quasi_random/boost/random/niederreiter_base2.hpp <boost/random/niederreiter_base2.hpp>]]]
+      [ Header contains `niederreiter_base2` template. ]
+   ]
+   [
+      [`sobol` type]
+      [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/quasi_random/boost/random/sobol.hpp <boost/random/sobol.hpp>]]]
+      [ Header contains `sobol` template. ]
+   ]
+   [
+      [`faure` type]
+      [ [^[@http://svn.boost.org/svn/boost/sandbox/SOC/2010/quasi_random/boost/random/faure.hpp <boost/random/faure.hpp>]]]
+      [ Header contains `faure` template. ]
+   ]
+]
+
+[endsect]
+
+
+[section Reference]
+
+[xinclude reference.xml]
+
+[endsect]

Added: sandbox/SOC/2010/quasi_random/project-root.jam
==============================================================================
--- (empty file)
+++ sandbox/SOC/2010/quasi_random/project-root.jam	2010-07-21 15:41:50 EDT (Wed, 21 Jul 2010)
@@ -0,0 +1,42 @@
+#
+#   Copyright (c) 2010 Justinas Vygintas Daugmaudis
+#
+#   Distributed under the Boost Software License, Version 1.0. (See
+#   accompanying file LICENSE_1_0.txt or copy at
+#   http://www.boost.org/LICENSE_1_0.txt)
+#
+
+##
+##  IMPORTANT NOTE: This file MUST NOT be copied over a boost installation
+##
+
+path-constant top : . ;
+
+import modules ;
+import path ;
+
+local boost-root = [ modules.peek : BOOST_ROOT ] ;
+
+if ! $(boost-root)
+{
+    local boost-search-dirs = [ modules.peek : BOOST_BUILD_PATH ] ;
+
+    for local dir in $(boost-search-dirs)
+    {
+        if [ path.glob $(dir)/../../../ : boost/version.hpp ]
+        {
+            boost-root += $(dir)/../../../ ;
+        }
+    }
+
+    if $(boost-root)
+    {
+        boost-root = [ path.make $(boost-root[1]) ] ;
+    }
+    else
+    {
+        ECHO "Warning: couldn't find BOOST_ROOT in" $(boost-root) ;
+    }
+}
+
+path-constant BOOST_ROOT : $(boost-root) ;