You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by md...@apache.org on 2003/07/05 18:59:13 UTC
cvs commit: jakarta-commons-sandbox/math/xdocs navigation.xml index.xml
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: phil@steitz.com
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="rdonkin@apache.org">Robert Burrell Donkin</author>
+ <author email="phil@steitz.com">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="phil@steitz.com">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="phil@steitz.com">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="phil@steitz.com">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="phil@steitz.com">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="phil@steitz.com">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="phil@steitz.com">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="phil@steitz.com">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: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org