Add docs directory and contents
Add the following documentation files:
arithmetic-overview.html describes the approach used to get "exact"
arithmetic.
implementation-overview.html outlines the major parts of the
implementation.
Change-Id: I3c8645aabbc5fb8aa894372a1eea0b5aad4a6473
(cherry picked from commit dd895bcaedc095c6dbb4d6df7cbc941e7a2a9d8d)
diff --git a/docs/arithmetic-overview.html b/docs/arithmetic-overview.html
new file mode 100644
index 0000000..68dd24e
--- /dev/null
+++ b/docs/arithmetic-overview.html
@@ -0,0 +1,271 @@
+<!doctype html>
+<html>
+<head>
+<title>Calculator Arithmetic Overview</title>
+<meta charset="UTF-8">
+<style>
+#toc {
+ width:300px;
+ border:1px solid #ccc;
+ background-color:#efefef;
+ float:right;
+}
+.display {
+ color:#666666;
+ background-color:#f3f3f3;
+}
+</style>
+</head>
+<body onload="init();">
+<div id="toc"></div>
+<h1>Arithmetic in the Android M Calculator</h1>
+<p>Most conventional calculators, both the specialized hardware and software varieties, represent
+numbers using fairly conventional machine floating point arithmetic. Each number is stored as an
+exponent, identifying the position of the decimal point, together with the first 10 to 20
+significant digits of the number. For example, 1/300 might be stored as
+0.333333333333x10<sup>-2</sup>, i.e. as an exponent of -2, together with the 12 most significant
+digits. This is similar, and sometimes identical to, computer arithmetic used to solve large
+scale scientific problems.</p> <p>This kind of arithmetic works well most of the time, but can
+sometimes produce completely incorrect results. For example, the trigonometric tangent (tan) and
+arctangent (tan<sup>-1</sup>) functions are defined so that tan(tan<sup>-1</sup>(<i>x</i>)) should
+always be <i>x</i>. But on most calculators we have tried, tan(tan<sup>-1</sup>(10<sup>20</sup>))
+is off by at least a factor of 1000. A value around 10<sup>16</sup> or 10<sup>17</sup> is quite
+popular, which unfortunately doesn't make it correct. The underlying problem is that
+tan<sup>-1</sup>(10<sup>17</sup>) and tan<sup>-1</sup>(10<sup>20</sup>) are so close that
+conventional representations don't distinguish them. (They're both 89.9999… degrees with at least
+fifteen 9s beyond the decimal point.) But the tiny difference between them results in a huge
+difference when the tangent function is applied to the result.</p>
+
+<p>Similarly, it may be puzzling to a high school student that while the textbook claims that for
+any <i>x</i>, sin(<i>x</i>) + sin(<i>x</i>+π) = 0, their calculator says that sin(10<sup>15</sup>)
++ sin(10<sup>15</sup>+π) = <span class="display">-0.00839670971</span>. (Thanks to floating point
+standardization, multiple on-line calculators agree on that entirely bogus value!)</p>
+
+<p>We know that the instantaneous rate of change of a function f, its derivative, can be
+approximated at a point <i>x</i> by computing (<i>f</i>(<i>x</i> + <i>h</i>) - <i>f</i>(<i>x</i>))
+/ <i>h</i>, for very small <i>h</i>. Yet, if you try this in a conventional calculator with
+<i>h</i> = 10<sup>-20</sup> or smaller, you are unlikely to get a useful answer.</p>
+
+<p>In general these problems occur when computations amplify tiny errors, a problem referred to as
+numerical instability. This doesn't happen very often, but as in the above examples, it may
+require some insight to understand when it can and can't happen.</p>
+
+<p>In large scale scientific computations, hardware floating point computations are essential
+since they are the only reasonable way modern computer hardware can produce answers with
+sufficient speed. Experts must be careful to structure computations to avoid such problems. But
+for "computing in the small" problems, like those solved on desk calculators, we can do much
+better!</p>
+
+<h2>Producing accurate answers</h2>
+<p>The Android M Calculator uses a different kind of computer arithmetic. Rather than computing a
+fixed number of digits for each intermediate result, the computation is much more goal directed.
+The user would like to see only correct digits on the display, which we take to mean that the
+displayed answer should always be off by less than one in the last displayed digit. The
+computation is thus performed to whatever precision is required to achieve that.</p>
+
+<p>Let's say we want to compute π+⅓, and the calculator display has 10 digits. We'd compute both π
+and ⅓ to 11 digits each, add them, and round the result to 10 digits. Since π and ⅓ were accurate
+to within 1 in the 11<sup>th</sup> digit, and rounding adds an error of at most 5 in the
+11<sup>th</sup> digit, the result is guaranteed accurate to less than 1 in the 10<sup>th</sup>
+digit, which was our goal.</p>
+
+<p>This is of course an oversimplification of the real implementation. Operations other than
+addition do get appreciably more complicated. Multiplication, for example, requires that we
+approximate one argument in order to determine how much precision we need for the other argument.
+The tangent function requires very high precision for arguments near 90 degrees to produce
+meaningful answers. And so on. And we really use binary rather than decimal arithmetic.
+Nonetheless the above addition method is a good illustration of the approach.</p>
+
+<p>Since we have to be able to produce answers to arbitrary precision, we can also let the user
+specify how much precision she wants, and use that as our goal. In the Android M Calculator, the
+user specifies the requested precision by scrolling the result. As the result is being scrolled,
+the calculator reevaluates it to the newly requested precision. In some cases, the algorithm for
+computing the new higher precision result takes advantage of the old, less accurate result. In
+other cases, it basically starts from scratch. Fortunately modern devices and the Android runtime
+are fast enough that the recomputation delay rarely becomes visible.</p>
+
+<h2>Design Decisions and challenges</h2>
+<p>This form of evaluate-on-demand arithmetic has occasionally been used before, and we use a
+refinement of a previously developed open source package in our implementation. However, the
+scrolling interface, together with the practicailities of a usable general purpose calculator,
+presented some new challenges. These drove a number of not-always-obvious design decisions which
+briefly describe here.</p>
+
+<h3>Indicating position</h3>
+<p>We would like the user to be able to see at a glance which part of the result is currently
+being displayed.</p>
+
+<p>Conventional calculators solve the vaguely similar problem of displaying very large or very
+small numbers by using scientific notation: They display an exponent in addition to the most
+significant digits, analogously to the internal representation they use. We solve that problem in
+exactly the same way, in spite of our different internal representation. If the user enters
+"1÷3⨉10^20", computing ⅓ times 10 to the 20th power, the result may be displayed as <span
+class="display">3.3333333333E19</span>, indicating that the result is approximately 3.3333333333
+times 10<sup>19</sup>. In this version of scientific notation, the decimal point is always
+displayed immediately to the right of the most significant digit, and the exponent indicates where
+it really belongs.</p>
+
+<p>Once the decimal point is scrolled off the display, this style of scientific notation is not
+helpful; it essentially tells us where the decimal point is relative to the most significant
+digit, but the most significant digit is no longer visible. We address this by switching to a
+different variant of scientific notation, in which we interpret the displayed digits as a whole
+number, with an implied decimal point on the right. Instead of displaying <span
+class="display">3.3333333333E19</span>, we hypothetically could display <span
+class="display">33333333333E9</span> or 33333333333 times 10<sup>9</sup>. In fact, we use this
+format only when the normal scientific notation decimal point would not be visible. If we had
+scrolled the above result 2 digits to the left, we would in fact be seeing <span
+ass="display">...33333333333E7</span>. This tells us that the displayed result is very close to a
+whole number ending in 33333333333 times 10<sup>7</sup>. Effectively the <span
+class="display">E7</span> is telling us that the last displayed digit corresponds to the ten
+millions position. In this form, the exponent does tell us the current position in the result.
+The two forms are easily distinguishable by the presence or absence of a decimal point, and the
+ellipsis character at the beginning.</p>
+
+<h3>Rounding vs. scrolling</h3>
+<p>Normally we expect calculators to try to round to the nearest displayable result. If the
+actual computed result were 0.66666666666667, and we could only display 10 digits, we would expect
+a result display of, for example <span class="display">0.666666667</span>, rather than <span
+class="display">0.666666666</span>. For us, this would have the disadvantage that when we
+scrolled the result left to see more digits, the "7" on the right would change to a "6". That
+would be mildly unfortunate. It would be somewhat worse that if the actual result were exactly
+0.99999999999, and we could only display 10 characters at a time, we would see an initial display
+of <span class="display">1.00000000</span>. As we scroll to see more digits, we would
+successively see <span class="display">...000000E-6</span>, then <span
+class="display">...000000E-7</span>, and so on until we get to <span
+class="display">...00000E-10</span>, but then suddenly <span class="display">...99999E-11</span>.
+If we scroll back, the screen would again show zeroes. We decided this would be excessively
+confusing, and thus do not round.</p>
+
+<p>It is still possible for previously displayed digits to change as we're scrolling. But we
+always compute a number of digits more than we actually need, so this is exceedingly unlikely.</p>
+
+<p>Since our goal is an error of strictly less than one in the last displayed digit, we will
+never, for example, display an answer of exactly 2 as <span class="display">1.9999999999</span>.
+That would involve an error of exactly one in the last place, which is too much for us.</p> <p>It
+turns out that there is exactly one case in which the display switches between 9s and 0s: A long
+but finite sequence of 9s (more than 20) in the true result can initially be displayed as a larger
+number ending in 0s. As we scroll, the 0s turn into 9s. When we immediately scroll back, the
+number remains displayed as 9s, since the calculator caches the best known result (though not
+currently across restarts or screen rotations).</p>
+
+<p>We prevent 9s from turning into 0s during scrolling. If we generate a result ending in 9s, our
+error bound implies that the true result is strictly less (in absolute value) than the value
+(ending in 0s) we would get by incrementing the last displayed digit. Thus we can never be forced
+back to generating zeros and will always continue to generate 9s.</p>
+
+<h3>Coping with mathematical limits</h3>
+<p>Internally the calculator essentially represents a number as a program for computing however
+many digits we happen to need. This representation has many nice properties, like never resulting
+in the display of incorrect results. It has one inherent weakness: We provably cannot compute
+precisely whether two numbers are equal. We can compute more and more digits of both numbers, and
+if they ever differ by more than one in the last computed digit, we know they are <i>not</i>
+equal. But if the two numbers were in fact the same, this process will go on forever.</p>
+
+<p>This is still better than machine floating point arithmetic, though machine floating point
+better obscures the problem. With machine floating point arithmetic, two computations that should
+mathematically have given the same answer, may give us substantially different answers, and two
+computations that should have given us different answers may easily produce the same one. We
+can indeed determine whether the floating representations are equal, but this tells us little
+about equality of the true mathematical answers.</p>
+
+<p>The undecidability of equality creates some interesting issues. If we divide a number by
+<i>x</i>, the calculator will compute more and more digits of <i>x</i> until it finds some nonzero
+ones. If <i>x</i> was in fact exactly zero, this process will continue forever.</p> <p>We deal
+with this problem using two complementary techniques:</p>
+
+<ol>
+<li>We always run numeric computations in the background, where they won't interfere with user
+interactions, just in case they take a long time. If they do take a really long time, we time
+them out and inform the user that the computation has been aborted. This is unlikely to happen by
+accident, unless the user entered an ill-defined mathematical expression, like a division by
+zero.</li>
+<li>As we will see below, in many cases we use an additional number representation that does allow
+us to determine that a number is exactly zero. Although this easily handles most cases, it is not
+foolproof. If the user enters "1÷0" we immediately detect the division by zero. If the user
+enters "1÷(π−π)" we time out. (We might choose to explicitly recognize such simple cases in the
+future. But this would always remain a heuristic.)</li>
+</ol>
+
+<h3>Zeros further than the eye can see</h3>
+<p>Prototypes of the M calculator, like mathematicians, treated all real numbers as infinite
+objects, with infinitely many digits to scroll through. If the actual computation happened to be
+2−1, the result was initially displayed as <span class="display">1.00000000</span>, and the user
+could keep scrolling through as many thousands of zeroes to the right of that as he desired.
+Although mathematically sound, this proved unpopular for several good reasons, the first one
+probably more serious than the others:</p>
+
+<ol>
+<li>If we computed $1.23 + $7.89, the result would show up as <span
+class="display">9.1200000000</span> or the like, which is unexpected and harder to read quickly
+than <span class="display">9.12</span>.</li>
+<li>Many users consider the result of 2-1 to be a finite number, and find it confusing to be able
+to scroll through lots of zeros on the right.</li>
+<li>Since the calculator couldn't ever tell that a number wasn't going to be scrolled, it couldn't
+treat any result as short enough to allow the use of a larger font.</li>
+</ol>
+
+<p>As a result, the calculator now also tries to compute the result as an exact fraction whenever
+that is easily possible. It is then easy to tell from the fraction whether a number has a finite
+decimal expansion. If it does, we prevent scrolling past that point, and may use the fact that
+the result has a short representation to increase the font size. Results displayed in a larger
+font are not scrollable. We no longer display any zeros for non-zero results unless there is
+either a nonzero or a displayed decimal point to the right. The fact that a result is not
+scrollable tells the user that the result, as displayed, is exact. This is fallible in the other
+direction. For example, we do not compute a rational representation for π−π, and hence it is
+still possible to scroll through as many zeros of that result as you like.</p>
+
+<p>This underlying fractional representation of the result is also used to detect, for example,
+division by zero without a timeout.</p>
+
+<p>Since we calculate the fractional result when we can in any case, it is also now available to
+the user through the overflow menu.</p>
+
+<h2>More details</h2>
+<p>The underlying evaluate-on-demand arithmetic package is described in H. Boehm, "The
+Constructive Reals as a Java Library'', Special issue on practical development of exact real
+number computation, <i>Journal of Logic and Algebraic Programming 64</i>, 1, July 2005, pp. 3-11.
+(Also at <a href="http://www.hpl.hp.com/techreports/2004/HPL-2004-70.html">http://www.hpl.hp.com/techreports/2004/HPL-2004-70.html</a>)</p>
+
+<p>Our version has been slightly refined. Notably it calculates inverse trigonometric functions
+directly instead of using a generic "inverse" function. This is less elegant, but significantly
+improves performance.</p>
+
+</body>
+</html>
+<script type="text/javascript">
+function generateTOC (rootNode, startLevel) {
+ var lastLevel = 0;
+ startLevel = startLevel || 2;
+ var html = "<ul>";
+
+ for (var i = 0; i < rootNode.childNodes.length; ++i) {
+ var node = rootNode.childNodes[i];
+ if (!node.tagName || !/H[1-6]/.test(node.tagName)) {
+ continue;
+ }
+ var level = +node.tagName.substr(1);
+ if (level < startLevel) { continue; }
+ var name = node.innerText;
+ if (node.children.length) { name = node.childNodes[0].innerText; }
+ if (!name) { continue; }
+ var hashable = name.replace(/[.\s\']/g, "-");
+ node.id = hashable;
+ if (level > lastLevel) {
+ html += "";
+ } else if (level < lastLevel) {
+ html += (new Array(lastLevel - level + 2)).join("</ul></li>");
+ } else {
+ html += "</ul></li>";
+ }
+ html += "<li><a class='lvl"+level+"' href='#" + hashable + "'>" + name + "</a><ul>";
+ lastLevel = level;
+ }
+
+ html += "</ul>";
+ return html;
+}
+
+function init() {
+ document.getElementById("toc").innerHTML = generateTOC(document.body);
+}
+</script>
diff --git a/docs/implementation-overview.html b/docs/implementation-overview.html
new file mode 100644
index 0000000..a06e73b
--- /dev/null
+++ b/docs/implementation-overview.html
@@ -0,0 +1,51 @@
+<!doctype html>
+<html>
+<head>
+<title>Calculator Implementation Overview</title>
+<meta charset="UTF-8">
+</head>
+<h1>M Calculator Implementation Overview</h1>
+<p>Although the appearance of the calculator has changed little from Lollipop, and some of the UI
+code is indeed the same, the rest of the code has changed substantially. Unsurprisingly,
+<b>Calculator.java</b> implements the main UI. The other major parts of the implementation
+are:</p>
+
+<p><b>CR.java</b> in <b>external/crcalc</b> provides the underlying demand-driven ("constructive
+real") arithmetic implementation. Numbers are represented primarily as objects with a method that
+can compute arbitrarily precise approximations. The actual arithmetic performed by these methods
+is based on Java's <tt>java.util.BigInteger</tt> arithmetic, with appropriate implicit
+scaling.</p>
+
+<p><b>BoundedRational.java</b> is a rational arithmetic package that is used to provide finite
+exact answers in "easy" cases. It is used primarily to determine when an approximation provided
+by CR.java is actually exact. This is used in turn both to limit the length of displayed results
+and scrolling, as well as to identify errors such as division by zero, that would otherwise result
+in timeouts during computations. It is in some sense not needed to produce correct results, but
+it significantly improves the usability of the calculator. It is also used for the "display as
+fraction" option in the overflow menu.</p>
+
+<p><b>CalculatorExpr.java</b> implements calculator arithmetic expressions. It supports editing,
+saving, restoring, and evaluation of expressions. Evaluation produces a constructive real (CR)
+and possibly a BoundedRational result. Unlike the "arity" library used in earlier versions, the
+underlying expression is represented as a sequence of "tokens", many of which are represented by
+Button ids, not as a character string.</p>
+
+<p><b>Evaluator.java</b> implements much of the actual calculator logic, particularly background
+expression evaluation. Expression evaluation here includes both using CalculatorExpr.java to
+evaluate the expression, and then invoking the resulting CR value to actually produce finite
+approximations and convert them to decimal. Two types of expression evaluation are supported:
+(1) Initial evaluation of the expression and producing an initial decimal approximation, and (2)
+reevaluation to higher precision. (1) is invoked directly from the Calculator UI, while (2) is
+invoked from the calculator display, commonly in response to scrolling. When the display requests
+a result, a "result" is immediately returned, though it may contains blank placeholders. The
+display is then notified when the real result becomes available.</p>
+
+<p><b>CalculatorText.java</b> is the TextView subclass used to display the formula.</p>
+
+<p><b>CalculatorResult.java</b> is the TextView subclass used to display the result. It handles
+result formatting, scrolling, etc. After the user hits "=", the CalculatorResult widget moves
+into the top position, replacing the formula display. Currently it remains in that position until
+the formula is again modified.</p>
+</body>
+</html>
+