Apache
/
commons-math
mirror of https://github.com/apache/commons-math.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

PR: http://nagoya.apache.org/bugzilla/show_bug.cgi?id=21277 

Submitted by:	phil@steitz.com


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/math/trunk@140956 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Mark R. Diggory 2003-07-05 16:59:13 +00:00
parent 62577ea18b
commit fb359aaee0
10 changed files with 540 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
xdocs/index.xml
View File

@ -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

6
xdocs/navigation.xml
View File

@ -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>

34
xdocs/userguide/analysis.xml Normal file
View File

@ -0,0 +1,34 @@
<?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>

70
xdocs/userguide/index.xml Normal file
View File

@ -0,0 +1,70 @@
<?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>

34
xdocs/userguide/linear.xml Normal file
View File

@ -0,0 +1,34 @@
<?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>

90
xdocs/userguide/overview.xml
View File

@ -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="About The User Guide">
<section name="Overview">
<subsection name="0.1 About The User Guide" href="about">
<p>
This is yet to be written. Any contributions will be greatfully accepted!
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>
</section>
</body>
</document>

172
xdocs/userguide/random.xml Normal file
View File

@ -0,0 +1,172 @@
<?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 &lt; 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 &lt; 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 &lt; 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 &lt;= 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>

34
xdocs/userguide/special.xml Normal file
View File

@ -0,0 +1,34 @@
<?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>

52
xdocs/userguide/stat.xml Normal file
View File

@ -0,0 +1,52 @@
<?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>

46
xdocs/userguide/utilities.xml Normal file
View File

@ -0,0 +1,46 @@
<?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>