mdiggory 2003/07/05 09:59:13
Modified: math/xdocs/userguide overview.xml
math/xdocs navigation.xml index.xml
Added: math/xdocs/userguide stat.xml analysis.xml utilities.xml
special.xml linear.xml index.xml random.xml
Log:
PR: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=21277
Submitted by: [EMAIL PROTECTED]
Revision Changes Path
1.2 +91 -5 jakarta-commons-sandbox/math/xdocs/userguide/overview.xml
Index: overview.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/math/xdocs/userguide/overview.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- overview.xml 20 May 2003 10:27:57 -0000 1.1
+++ overview.xml 5 Jul 2003 16:59:13 -0000 1.2
@@ -4,14 +4,100 @@
<properties>
<title>User Guide - Overview</title>
<author email="[EMAIL PROTECTED]">Robert Burrell Donkin</author>
+ <author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
+
+<body>
+
+<section name="Overview">
+
+<subsection name="0.1 About The User Guide" href="about">
+ <p>
+ This guide is intended to help programmers quickly find what they need to
develop
+ solutions using Commons Math. It also provides a supplement to the javadoc API
documentation,
+ providing a little more explanation of the mathematical objects and functions
included
+ in the package.
+ </p>
+</subsection>
+
+<subsection name="0.2 What's in commons-math" href="summary">
+ <p>
+ Commons Math is made up of a small set of math/stat utilities addressing
+ programming problems like the ones in the list below. This list is not
exhaustive,
+ it's just meant to give a feel for the kinds of things that Commons Math
provides.
+ <ul>
+ <li>Computing means, variances and other summary statistics for a list of
numbers</li>
+ <li>Fitting a line to a set of data points using linear regression</li>
+ <li>Solving equations involving real-valued functions (i.e.
root-finding)</li>
+ <li>Performing statistical significance tests</li>
+ <li>Solving systems of linear equations</li>
+ <li>Generating random numbers with more restrictions (e.g distribution,
range) than what
+ is possible using the JDK</li>
+ <li>Generating random samples and/or datasets that are "like" the data in
an input file</li>
+ <li>Finding a smooth curve that passes through a collection of points
(interpolation)</li>
+ <li>Miscellaneous mathematical functions such as factorials and binomial
+ coefficients</li>
+ </ul></p>
+ <p>
+ Commons Math is a new project and we are actively seeking ideas for additional
components that
+ fit into the <a href="../index.html#summary">Commons Math vision</a> of a set
of lightweight,
+ self-contained math/stat components useful for solving common programming
problems.
+ Suggestions for new components or enhancements to existing functionality are
always welcome!
+ All feedback/suggestions for improvement should be sent to the
+ <a href="http://jakarta.apache.org/site/mail.html";>commons-dev mailing list</a>
with
+ [math] at the beginning of the subject line.
+ </p>
+</subsection>
+
+<subsection name="0.3 How commons-math is organized" href="organization">
+ <p>
+ Commons Math is divided into 6 subpackages, based on functionality provided.
+ <ol><li><a href="stat.html">org.apache.commons.math.stat</a> - statistics,
statistical tests, probability distributions</li>
+ <li><a href="analysis.html">org.apache.commons.math.analysis</a> -
rootfinding and interpolation</li>
+ <li><a href="random.html">org.apache.commons.math.random</a> - random
numbers, strings and data generation</li>
+ <li><a href="special.html">org.apache.commons.math.special</a> - special
functions (Gamma, Beta) </li>
+ <li><a href="linear.html">org.apache.commons.math.linear</a> - matrices,
solving linear systems </li>
+ <li><a href="utilities.html">org.apache.commons.matn.utitlities</a> -
common math/stat functions extending java.lang.Math </li>
+ </ol>
+ Package javadocs are <a href="../apidocs/index.html">here</a>
+ </p>
+</subsection>
+
+<subsection name="0.4 How interface contracts are specified in commons-math
javadoc" href="contracts">
+ <p>
+ You should always read the javadoc class and method comments carefully when
using
+ Commons Math components in your programs. The javadoc provides references to
the algorithms
+ that are used, usage notes about limitations, performance, etc. as well as
interface contracts.
+ Interface contracts are specified in terms of preconditions (what has to be
true in order
+ for the method to return valid results), special values returned (e.g.
Double.NaN)
+ or exceptions that may be thrown if the preconditions are not met, and
definitions for returned
+ values/objects or state changes.</p>
+ <p>
+ When the actual parameters provide to a method or the internal state of an
object
+ make a computation meaningless, an IllegalArgumentException or
IllegalStateException may
+ be thrown. Exact conditions under which runtime exceptions (and any other
exceptions) are
+ thrown are specified in the javadoc method comments. In some cases, to be
consistent with
+ the <a href="http://grouper.ieee.org/groups/754/";>IEEE 754 standard</a> for
floating point
+ arithmetic and with java.lang.Math, Commons Math methods return Double.NaN
values.
+ Conditions under which Double.NaN or other special values are returned are
fully specified
+ in the javadoc method comments.
+ </p>
+</subsection>
+
+<subsection name="0.5 Dependencies" href="dependencies">
+ <p>
+ Commons Math requires JDK 1.2+ and has no dependencies other than the following
Jakarta Commons
+ components:
+ <ul>
+ <li>commons-beanutils 1.5 </li>
+ <li>commons-collections 2.1 </li>
+ <li>commons-logging 1.0.3 </li>
+ </ul>
+ </p>
+</subsection>
- <body>
- <section name="About The User Guide">
- <p>
-This is yet to be written. Any contributions will be greatfully accepted!
- </p>
</section>
+
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/stat.xml
Index: stat.xml
===================================================================
<?xml version="1.0"?>
<document url="stat.html">
<properties>
<title>The Commons Math User Guide - Statistics</title>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
<body>
<section name="1 Statistics">
<subsection name="1.1 Overview" href="overview">
<p>
This is yet to be written. Any contributions will be greatfully accepted!
</p>
</subsection>
<subsection name="1.2 Univariate statistics" href="univariate">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="1.3 Frequency distributions" href="frequency">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="1.4 Bivariate regression" href="regression">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="1.5 Statistical tests" href="tests">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="1.6 Distribution framework" href="distributions">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/analysis.xml
Index: analysis.xml
===================================================================
<?xml version="1.0"?>
<document url="analysis.html">
<properties>
<title>The Commons Math User Guide - Numerical Analysis</title>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
<body>
<section name="4 Numerical Analysis">
<subsection name="4.1 Overview" href="overview">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="4.2 Root-finding" href="rootfinding">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="4.3 Interpolation" href="interpolation">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/utilities.xml
Index: utilities.xml
===================================================================
<?xml version="1.0"?>
<document url="utilities.html">
<properties>
<title>The Commons Math User Guide - Utilites</title>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
<body>
<section name="6 Utilities">
<subsection name="6.1 Overview" href="overview">
<p>
This is yet to be written. Any contributions will be greatfully accepted!
</p>
</subsection>
<subsection name="6.2 Double array utilities" href="arrays">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="6.3 Continued Fractions" href="continued_fractions">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="6.4 binomial coefficients, factorials and other common math
functions" href="math_utils">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="6.5 statistical computation utiliities" href="stat_utils">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/special.xml
Index: special.xml
===================================================================
<?xml version="1.0"?>
<document url="special.html">
<properties>
<title>The Commons Math User Guide - Special Functions</title>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
<body>
<section name="5 Special Functions">
<subsection name="5.1 Overview" href="overview">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="5.2 Gamma functions" href="gamma">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="5.3 Beta funtions" href="beta">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/linear.xml
Index: linear.xml
===================================================================
<?xml version="1.0"?>
<document url="linear.html">
<properties>
<title>The Commons Math User Guide - Linear Algebra</title>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
<body>
<section name="3 Linear Algebra">
<subsection name="3.1 Overview" href="overview">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="3.2 Real matrices" href="real_matrices">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
<subsection name="3.3 Solving linear systems" href="solve">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/index.xml
Index: index.xml
===================================================================
<?xml version="1.0"?>
<document url="index.html">
<properties>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
<title>The Commons Math User Guide - Table of Contents</title>
</properties>
<body>
<section name="Table of Contents" href="toc">
<ul>
<li><a href="overview.html">0. Overview</a>
<ul>
<li><a href="overview.html#about">0.1 About the User Guide</a></li>
<li><a href="overview.html#summary">0.2 What's in commons-math</a></li>
<li><a href="overview.html#organization">0.3 How commons-math is
organized</a></li>
<li><a href="overview.html#contracts">0.4 How interface contracts are
specified in commons-math javadoc</a></li>
<li><a href="overview.html#dependencies">0.5 Dependencies</a></li>
</ul></li>
<li><a href="stat.html">1. Statistics</a>
<ul>
<li><a href="stat.html#overview">1.1 Overview</a></li>
<li><a href="stat.html#univariate">1.2 Univariate statistics</a></li>
<li><a href="stat.html#frequency">1.3 Frequency
distributions</a></li>
<li><a href="stat.html#regression">1.4 Bivariate regression</a></li>
<li><a href="stat.html#tests">1.5 Statistical tests</a></li>
<li><a href="stat.html#distributions">1.6 Distribution
framework</a></li>
</ul></li>
<li><a href="random.html">2. Data Generation</a>
<ul>
<li><a href="random.html#overview">2.1 Overview</a></li>
<li><a href="random.html#deviates">2.2 Random numbers</a></li>
<li><a href="random.html#strings">2.3 Random Strings</a></li>
<li><a href="random.html#combinatorics">2.4 Random permutations,
combinations, sampling</a></li>
<li><a href="random.html#empirical">2.5 Generating data "like" an
input file</a></li>
</ul></li>
<li><a href="linear.html">3. Linear Algebra</a>
<ul>
<li><a href="linear.html#overview">3.1 Overview</a></li>
<li><a href="linear.html#real_matrices">3.2 Real matrices</a></li>
<li><a href="linear.html#solve">3.3 Solving linear systems</a></li>
</ul></li>
<li><a href="analysis.html">4. Numerical Analysis</a>
<ul>
<li><a href="analysis.html#overview">4.1 Overview</a></li>
<li><a href="analysis.html#rootfinding">4.2 Root-finding</a></li>
<li><a href="analysis.html#interpolation">4.3 Interpolation</a></li>
</ul></li>
<li><a href="special.html">5. Special Functions</a>
<ul>
<li><a href="special.html#overview">5.1 Overview</a></li>
<li><a href="special.html#gamma">5.2 Gamma functions</a></li>
<li><a href="special.html#beta">5.3 Beta funtions</a></li>
</ul></li>
<li><a href="utilities.html">6. Utilities</a>
<ul>
<li><a href="utilities#overview">6.1 Overview</a></li>
<li><a href="utilities.html#arrays">6.2 Double array
utilities</a></li>
<li><a href="utilities.html#continued_fractions">6.3 Continued
Fractions</a></li>
<li><a href="utilities.html#math_utils">6.4 binomial coefficients,
factorials and other common math functions</a></li>
<li><a href="utilities.html#stat_utils">6.5 statistical computation
utiliities</a></li>
</ul></li>
</ul>
</section>
</body>
</document>
1.1 jakarta-commons-sandbox/math/xdocs/userguide/random.xml
Index: random.xml
===================================================================
<?xml version="1.0"?>
<document url="random.html">
<properties>
<title>The Commons Math User Guide - Data Generation</title>
<author email="[EMAIL PROTECTED]">Phil Steitz</author>
</properties>
<body>
<section name="2 Data Generation">
<subsection name="2.1 Overview" href="overview">
<p>
The Commons Math random package includes utilities for
<ul>
<li>generating random numbers</li>
<li>generating random strings</li>
<li>generating cryptographically secure sequences of random numbers or
strings</li>
<li>generating random samples and permuations</li>
<li>analyzing distributions of values in an input file and generating values
"like"
the values in the file</li>
<li>generating data for grouped frequency distributions or histograms</li>
</ul></p>
</subsection>
<subsection name="2.2 Random numbers" href="deviates">
<p>
The <a href="../apidocs/org/apache/commons/math/random/RandomData.html">
org.apache.commons.math.RandomData</a> interface defines methods for generating
random sequences of numbers. The API contracts of these methods use the
following concepts:
<dl>
<dt>Random sequence of numbers from a probability distribution</dt>
<dd>There is no such thing as a single "random number." What can be generated
are <i>sequences</i> of numbers that appear to be random. When using the
built-in JDK function <code>Math.random(),</code> sequences of values generated
follow the <a
href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm";>
Uniform Distribution</a>, which means that the values are evenly spread over the
interval
between 0 and 1, with no sub-interval having a greater probability of containing
generated
values than any other interval of the same length. The mathematical concept of
a <a href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda36.htm";>
probability distribution</a> basically amounts to asserting that different
ranges in the set
of possible values for of a random variable have different probabilities of
containing the value.
Commons Math supports generating random sequences from the following probability
distributions. The
javadoc for the <code>nextXxx</code> methods in <code>RandomDataImpl</code>
describes the algorithms used
to generate random deviates from each of these distributions.
<ul>
<li><a
href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3662.htm";>uniform
distribution</a></li>
<li><a
href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3667.htm";>exponential
distribution</a></li>
<li><a
href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda366j.htm";>poisson
distribution</a></li>
<li><a
href="http://www.itl.nist.gov/div898/handbook/eda/section3/eda3661.htm";>Gaussian
distribution</a></li>
</ul>
</dd>
<dt>Cryptographically secure random sequences</dt>
<dd>It is possible for a sequence of numbers to appear random, but nonetheless
to be
predictable based on the algorithm used to generate the sequence. If in addition
to
randomness, strong unpredictability is required, it is best to use a
<a
href="http://www.wikipedia.org/wiki/Cryptographically_secure_pseudo-random_number_generator";>
secure random number generator</a> to generate values (or strings). The
nextSecureXxx methods
in the <code>RandomDataImpl</code> implementation of the <code>RandomData</code>
interface use the
JDK <code>SecureRandom</code> pseudo-random number generator (PRNG)
to generate cryptographically secure sequences. The
<code>setSecureAlgorithm</code> method
allows you to change the underlying PRNG. These methods are <strong>much
slower</strong> than
the corresponding "non-secure" versions, so they should only be used when
cryptographic security
is required.</dd>
<dt>Seeding pseudo-random number generators</dt>
<dd>By default, the implementation provided in <code>RandomDataImpl</code> uses
the JDK-provided
PRNG. Like other PRNGs, the JDK generator generates sequences of random numbers
based on an initial
"seed value". For the non-secure methods, starting with the same seed always
produces the same
sequence of values. Secure sequences started with the same seeds will diverge.
When a new
<code>RandomDataImpl</code> is created, the underlying random number generators
are
<strong>not</strong> intialized. The first call to a data generation method, or
to a
<code>reSeed()</code> method initializes the appropriate generator. If you do
not explicitly
seed the generator, it is by default seeded with the current time in
milliseconds. Therefore,
to generate sequences of random data values, you should always instantiate
<strong>one</strong>
<code>RandomDataImpl</code> and use it repeatedly instead of creating new
instances for
subsequent values in the sequence. For example, the following will generate a
random sequence
of 50 long integers between 1 and 1,000,000, using the current time in
milliseconds as the seed
for the JDK PRNG:
<pre><code>
RandomDataImpl randomData = new RandomDataImpl();
for (int i = 0; i < 1000; i++) {
value = randomData.nextLong(1, 1000000);
}
</code></pre>
The following will not in general produce a good random sequence, since the PRNG
is reseeded
each time through the loop with the current time in milliseconds:
<pre><code>
for (int i = 0; i < 1000; i++) {
RandomDataImpl randomData = new RandomDataImpl();
value = randomData.nextLong(1, 1000000);
}
</code></pre>
The following will produce the same random sequence each time it is executed:
<pre><code>
RandomDataImpl randomData = new RandomDataImpl();
randomData.reSeed(1000);
for (int i = 0; i = 1000; i++) {
value = randomData.nextLong(1, 1000000);
}
</code></pre>
The following will produce a different random sequence each time it is executed.
<pre><code>
RandomDataImpl randomData = new RandomDataImpl();
randomData.reSeedSecure(1000);
for (int i = 0; i < 1000; i++) {
value = randomData.nextSecureLong(1, 1000000);
}
</code></pre>
</dd></dl>
</p>
</subsection>
<subsection name="2.3 Random Strings" href="strings">
<p>
The methods <code>nextHexString</code> and <code>nextSecureHexString</code>
can be used to generate random strings of hexadecimal characters. Both of these
methods produce sequences of strings with good dispersion properties.
The difference between the two methods is that the second is cryptographically
secure.
Specifically, the implementation of <code>nextHexString(n)</code> in
<code>RandomDataImpl</code>
uses the following simple algorithm to generate a string of <code>n</code> hex
digits:
<ol>
<li>n/2+1 binary bytes are generated using the underlying Random</li>
<li>Each binary byte is translated into 2 hex digits</li></ol>
The <code>RandomDataImpl</code> implementation of the "secure" version,
<code>nextSecureHexString</code> generates hex characters in 40-byte "chunks"
using a 3-step process:
<ol>
<li>20 random bytes are generated using the underlying
<code>SecureRandom</code>.</li>
<li>SHA-1 hash is applied to yield a 20-byte binary digest.</li>
<li>Each byte of the binary digest is converted to 2 hex digits</li></ol>
Similarly to the secure random number generation methods,
<code>nextSecureHexString</code>
is <strong>much slower</strong> than the non-secure version. It should be used
only for
applications such as generating unique session or transaction ids where
predictability of
subsequent ids based on observation of previous values is a security concern.
If all
that is needed is an even distribution of hex characters in the generated
strings, the
non-secure method should be used.
</p>
</subsection>
<subsection name="2.4 Random permutations, combinations, sampling"
href="combinatorics">
<p>
To select a random sample of objects in a collection, you can use the
<code>nextSample</code> method in the <code>RandomData</code> interface.
Specifically,
if <code>c</code> is a collection containing at least <code>k</code> objects, and
<code>ranomData</code> is a <code>RandomDataImpl</code> instance
<code>randomData.nextSample(c, k)</code>
will return an <code>object[]</code> array of length <code>k</code> consisting of
elements randomly selected from the collection. If <code>c</code> contains
duplicate references, there may be duplicate references in the returned array;
otherwise returned elements will be unique -- i.e., the sampling is without
replacement among the object references in the collection. </p>
<p>
If <code>randomData</code> is a <code>RandomDataImpl</code> instance, and
<code>n</code> and <code>k</code> are integers with <code> k <= n</code>,
then <code>randomData.nextPermutation(n, k)</code> returns an <code>int[]</code>
array of length <code>k</code> whose whose entries are selected randomly,
without repetition, from the integers <code>0</code> through <code>n-1</code>
(inclusive), i.e.,
<code>randomData.nextPermutation(n, k)</code> returns a random permutation of
<code>n</code> taken <code>k</code> at a time.
</p>
</subsection>
<subsection name='2.5 Generating data "like" an input file' href="empirical">
<p>
This is yet to be written. Any contributions will be gratefully accepted!
</p>
</subsection>
</section>
</body>
</document>
1.2 +6 -0 jakarta-commons-sandbox/math/xdocs/navigation.xml
Index: navigation.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/math/xdocs/navigation.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- navigation.xml 20 May 2003 10:27:26 -0000 1.1
+++ navigation.xml 5 Jul 2003 16:59:13 -0000 1.2
@@ -12,7 +12,13 @@
<item name="Tasks: Done And To Do" href="/tasks.html"/>
</menu>
<menu name="User Guide">
+ <item name="Contents" href="/userguide/index.html"/>
<item name="Overview" href="/userguide/overview.html"/>
+ <item name="Statistics" href="/userguide/stat.html"/>
+ <item name="Data generation" href="/userguide/random.html"/>
+ <item name="Linear Algebra" href="/userguide/linear.html"/>
+ <item name="Special Functions" href="/userguide/special.html"/>
+ <item name="Utilities" href="/userguide/utilities.html"/>
</menu>
</body>
</project>
1.2 +1 -1 jakarta-commons-sandbox/math/xdocs/index.xml
Index: index.xml
===================================================================
RCS file: /home/cvs/jakarta-commons-sandbox/math/xdocs/index.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- index.xml 20 May 2003 10:27:26 -0000 1.1
+++ index.xml 5 Jul 2003 16:59:13 -0000 1.2
@@ -9,7 +9,7 @@
<body>
-<section name="Commons-Math: The Jakarta Mathematics Library">
+<section name="Commons-Math: The Jakarta Mathematics Library" href="summary">
<p>
The Java programming language and the math extensions in commons-lang provide
implementations for only the most basic mathematical algorithms. Routine
development
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
