Changeset 2045

Timestamp:

Oct 11, 2004, 11:49:56 AM (22 years ago)

Author:

Paul Price

Message:

Adding random numbers. Removed psGaussianDev, and altered psLibInit.

Location:

trunk/doc/pslib

Files:

• ChangeLogSDRS.tex (modified) (2 diffs)
• psLibSDRS.tex (modified) (6 diffs)

trunk/doc/pslib/ChangeLogSDRS.tex

@@ -1 @@
-%%% $Id: ChangeLogSDRS.tex,v 1.31 2004-10-11 19:54:50 price Exp $
+%%% $Id: ChangeLogSDRS.tex,v 1.32 2004-10-11 21:49:56 price Exp $
 
 \subsection{Changes from version 00 to version 01}
@@ -335 +335 @@
 \item Added \code{psTimeAlloc}.
 \item Adding \code{errors} to \code{psVectorStats}.
+\item Adding \code{psRandom}, with three distributions (uniform,
+  Gaussian, Poisson).  This obsoletes \code{psGaussianDev}, and
+  impacts \code{psLibInit} (no longer needs to seed the RNG).
 \end{itemize}

trunk/doc/pslib/psLibSDRS.tex

@@ -1 @@
-%%% $Id: psLibSDRS.tex,v 1.133 2004-10-09 01:37:41 price Exp $
+%%% $Id: psLibSDRS.tex,v 1.134 2004-10-11 21:49:44 price Exp $
 \documentclass[panstarrs,spec]{panstarrs}
 
@@ -175 +175 @@
 \begin{itemize}
 \item Set the error codes for PSLib.
-\item Seed the random number generator.
 \item Read the \code{psTime} configuration file (\code{timeConfig})
   and set up the appropriate \code{psTimeTable}s and predictions.
@@ -182 +181 @@
 The prototype is:
 \begin{verbatim}
-void psLibInit(bool predictable, const char *timeConfig);
-\end{verbatim}
-
-If \code{predictable} is \code{true}, then the random number generator
-shall be seeded with a value that does not vary (allowing bugs relying
-on random numbers to be reproduced); otherwise, the random number
-generator shall be seeded from \code{/dev/random} if it exists,
-otherwise from the system clock.
+void psLibInit(const char *timeConfig);
+\end{verbatim}
 
 \code{timeConfig} specifies the filename of the configuration file
@@ -2167 +2160 @@
 Gaussians are used extensively in any data-analysis system, in
 particular to represent a real population distribution.  We require a
-function to evaluate a Gaussian for a given coordinate and one which
-generates a Gaussian deviate; a collection of data points whose
-distribution obeys a specified Gaussian.
+function to evaluate a Gaussian for a given coordinate.
 
 The Gaussian evaluation is provide by:
@@ -2185 +2176 @@
 In the case of the non-normalized Gaussian, the leading coefficient is
 dropped.
-
-A vector with a specified Gaussian deviate distribution is provide by:
-\begin{verbatim}
-psVector *psGaussianDev(float mean, float sigma, int Npts);
-\end{verbatim}
-which generates a vector (type \code{psF32}) of \code{Npts} elements
-whose distribution has the given \code{mean} and \code{sigma}.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -3187 +3171 @@
 In the event that \code{out} is \code{NULL}, a new \code{psImage}
 shall be allocated and returned.
+
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\subsection{Random Numbers}
+
+Many applications involve random numbers, with the particular
+distribution depending upon the application.  We will wrap the GSL
+implementation.
+
+We define a \code{psRandom} type, which will allow us to carry around
+pre-computed random numbers, if required.  For the time being, we only
+specify a single randon number generator (RNG) in \code{psRandomType}
+(that provided by \code{gsl_rng_taus}), but we leave this open to
+expansion in the future, depending upon user requirements.
+
+\begin{verbatim}
+typedef enum {
+    PS_RANDOM_TAUS                      ///< A maximally equidistributed combined Tausworthe generator
+} psRandomType;
+
+typedef struct {
+    psRandomType type;                  ///< The type of RNG
+    gsl_rng *gsl;                       ///< The RNG itself
+} psRandom;
+\end{verbatim}
+
+We require the ability to seed the random number generator (RNG) with
+a known value, so that bugs in modules which rely upon random numbers
+may be reproduced.
+
+\begin{verbatim}
+psRandom *psRandomAlloc(psRandomType type, unsigned long seed);
+void psRandomReset(psRandom *rand, unsigned long seed);
+\end{verbatim}
+
+\code{psRandomAlloc} shall construct a new instance of \code{psRandom}
+of the given \code{type}, and seed it with the given \code{seed}.  The
+\code{seed} is specified as an \code{unsigned long} so that the system
+clock may be used to set it.  If the \code{seed} is zero, then the RNG
+shall be seeded from \code{/dev/random} if it exists, or otherwise
+from the system clock, and the particular seed shall be printed using
+\code{psLogMsg} with a level of \code{PS_LOG_INFO}.
+
+\begin{verbatim}
+double psRandomUniform(const psRandom *r);
+double psRandomGaussian(const psRandom *r);
+double psRandomPoisson(const psRandom *r, double mean);
+\end{verbatim}
+
+\code{psRandomUniform} shall return random numbers uniformly
+distributed on $[0,1)$, using \code{gsl_rng_uniform}.
+\code{psRandomGaussian} shall return random numbers distributed on a
+Gaussian deviate, $N(0,1)$, using \code{gsl_ran_gaussian}.
+\code{psRandomPoisson} shall return random numbers distributed on a
+Poisson distribution with the given \code{mean} using
+\code{gsl_ran_poisson}.
 
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%