Author: luc
Date: Wed May 18 09:48:24 2011
New Revision: 1124151
URL: http://svn.apache.org/viewvc?rev=1124151&view=rev
Log:
improved javadoc for FastMath.
JIRA: MATH-579
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/util/FastMath.java
commons/proper/math/trunk/src/site/xdoc/changes.xml
Modified:
commons/proper/math/trunk/src/main/java/org/apache/commons/math/util/FastMath.java
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math/util/FastMath.java?rev=1124151&r1=1124150&r2=1124151&view=diff
==============================================================================
---
commons/proper/math/trunk/src/main/java/org/apache/commons/math/util/FastMath.java
(original)
+++
commons/proper/math/trunk/src/main/java/org/apache/commons/math/util/FastMath.java
Wed May 18 09:48:24 2011
@@ -17,7 +17,30 @@
package org.apache.commons.math.util;
/**
- * Faster, more accurate, portable alternative to {@link StrictMath}.
+ * Faster, more accurate, portable alternative to {@link StrictMath}
+ * for large scale computation.
+ * <p>
+ * FastMath speed is achieved by relying heavily on optimizing compilers
+ * to native code present in many JVM todays and use of large tables that
+ * are computed once at class loading (regardless of the number of subsequent
+ * calls to computation methods). This implies that FastMath is targeted
+ * more towards large scale computation (i.e. computation that take at least
+ * a handful of seconds to complete) on desktop or server machines rather
+ * than very small utilities on devices with limited power (i.e. computation
+ * that should return a result almost instantly). Note that FastMath is
+ * extensively used inside Apache Commons Math, so by calling some algorithms,
+ * the one-shot overhead will occur regardless of the end-user calling FastMath
+ * methods directly or not.
+ * <p>
+ * <p>
+ * FastMath accuracy should be mostly independent of the JVM as it relies only
+ * on IEEE-754 basic operations and on embedded tables. Almost all operations
+ * are accurate to about 0.5 ulp throughout the domain range. This statement,
+ * of course is only a rough global observed behavior, it is <em>not</em> a
+ * guarantee for <em>every</em> double numbers input (see William Kahan's <a
+ *
href="http://en.wikipedia.org/wiki/Rounding#The_table-maker.27s_dilemma";>Table
+ * Maker's Dilemma</a>).
+ * </p>
* <p>
* Additionally implements the following methods not found in StrictMath:
* <ul>
Modified: commons/proper/math/trunk/src/site/xdoc/changes.xml
URL:
http://svn.apache.org/viewvc/commons/proper/math/trunk/src/site/xdoc/changes.xml?rev=1124151&r1=1124150&r2=1124151&view=diff
==============================================================================
--- commons/proper/math/trunk/src/site/xdoc/changes.xml (original)
+++ commons/proper/math/trunk/src/site/xdoc/changes.xml Wed May 18 09:48:24 2011
@@ -52,6 +52,10 @@ The <action> type attribute can be add,u
If the output is not quite correct, check for invisible trailing spaces!
-->
<release version="3.0" date="TBD" description="TBD">
+ <action dev="luc" type="fix" issue="MATH-579">
+ Improved javadoc for FastMath explaining the overhead at class loading
and
+ the targeted use cases.
+ </action>
<action dev="erans" type="fix" issue="MATH-574">
Allow outer product of vectors of different sizes.
</action>
