Merge branch 'docs' into develop

Author: bxparks

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changelog
 
 - Unreleased
+- 0.12.0-rc1 (2024-06-18)
     - TVM
         - add `C/YR` menu (number of compoundings per year)
             - uses the same variable as the `C/Y` variable of the "Finance" app
@@ -21,6 +22,10 @@
           flag of the "Finance" app provided by TI-OS
         - display status message 'TVM Calculated (Multiple)' if the TVM equation
           has 2 solutions, but only one of them was found
+    - docs
+        - simplify pandoc processing pipeline
+        - change PDF font to FreeSerif and FreeMono to render the U+2220 (angle)
+          symbol properly
 - 0.11.0 (2024-05-28)
     - **Warning**: Previously saved RPN stack and storage registers are
       incompatible and are lost when upgrading to this version.

README.md

@@ -113,7 +113,7 @@ Missing features (partial list):
 - vectors and matrices
 - keystroke programming
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Changelog**: [CHANGELOG.md](CHANGELOG.md)
 

docs/DEVELOPER.md

@@ -3,7 +3,7 @@
 Notes for the developers of the RPN83P app, likely myself in 6 months when I
 cannot remember how the code works.
 
-**Version**: 0.9.0 (2024-01-06)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Project Home**: https://github.com/bxparks/rpn83p
 

docs/FUTURE.md

@@ -14,7 +14,7 @@ because it is faster and easier to use compared to a web app, especially for
 small features that can be described in a few sentences. Usually only the larger
 and more complicated features will get their own GitHub tickets.
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Parent Document**: [USER_GUIDE.md](USER_GUIDE.md)
 
@@ -30,26 +30,6 @@ and more complicated features will get their own GitHub tickets.
 
 ## Near Future
 
-- `TVM` (time value of money)
-    - improve TVM Solver for `I%YR`
-        - The current default initial guess is 0% and 100% so that positive
-          interest rates are required (because a sign change over the initial
-          guesses are required). If there is a rounding error, the actual
-          numerical solution could be slighlty negative, which would cause an
-          `TVM Not Fount` error message because a sign-change is currently
-          required over the 2 initial guesses.
-        - One solution could be use something like `-1%` for the lower guess,
-          and then check for a sign change over 2 sub-intervals: `[-1%,0%]` and
-          `[0%,100%]`. We also have to careful to detect cases where expected
-          solution is exactly `0%`.
-        - The terminating tolerance could be selectable or more intelligent.
-        - Maybe change the root solving algorithm from Secant method to Newton's
-          method for faster convergence.
-    - support `C/YR` (compounding periods per year) as a separate parameter
-        - currently `C/YR` is set to be the same as `P/YR` (payments per year)
-          for ease of implementation
-        - there are apparently jurisdictions (Canada, UK) where it is common for
-          `C/YR` to be different from `P/YR`
 - add a `ROOT > CLR > CLAL` (Clear All) menu function
     - becomes useful as more features and configuration options are added
 - allow numbers in any base to be entered regardless of the BASE mode

docs/TVM.md

@@ -3,7 +3,7 @@
 Equations, algorithms, and other tricks used to calculate the Time Value of
 Money (TVM) variables in the RPN83P calculator app.
 
-**Version**: 0.9.0 (2024-01-06)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Project Home**: https://github.com/bxparks/rpn83p
 
@@ -20,7 +20,7 @@ Money (TVM) variables in the RPN83P calculator app.
     - [Taming Overflows](#taming-overflows)
     - [Secant Method](#secant-method)
     - [Initial Guesses](#initial-guesses)
-    - [Tolerance](#tolerance)
+    - [Terminating Conditions](#terminating-conditions)
     - [Maximum Iterations](#maximum-iterations)
     - [Convergence](#convergence)
 - [References](#references)
@@ -69,23 +69,55 @@ NPV = NFV * (1+i)^N
 
 ## Interest Rate Conversions
 
-The variable `i` in the `NPV` and `NFV` equations defines the interest rate per
-payment period. For most real-life problems, it is more convenient to express
-the interest rate per year. The relationship between these quantities are:
+Most real-life problems express the nominal annual interest rate `I%YR` as a
+percentage instead of a dimensionless fraction `IYR` which is more useful in
+computation. So let's define:
+
+```
+IYR = I%YR / 100
+```
+
+The variable `i` in the `NPV` and `NFV` equations is the interest rate per
+payment period, which is defined from the nominal interest rate `IYR` by:
 
 ```
 i = IYR/PYR
 ```
 
-where:
+where `PYR` is the number of payments per year
+
+However, this is true only if `PYR` is equal to `CYR`, the number of
+compoundings per year. It seems that in some countries (e.g. Canada and the UK),
+lenders are required to calculate the `CYR` differently from the `PYR`.
+
+When the 2 quantities are different, the total effective annual interest rate
+that results from compounding for each payment period at interest rate `i` must
+equal the total effective annual interest rate when compounded using the `CYR`
+compounds per year. In other words, the following defines the meaning of `CYR`:
+
+```
+(1 + i) ^ PYR = (1 + IYR/CYR) ^ CYR
+```
+
+We can rearrange the equation to solve the payment-period interest rate `i`
+which is used on the TVM equations:
+
+```
+i = (1 + IYR/CYR) ^ (CYR/PYR) - 1
+  = expm1[ (CYR/PYR) log1p(IYR/CYR) ]
+```
+
+where we have used the `expm1()` and `log1p()` functions that we defined below.
+
+Since the `expm1()` and `log1p()` functions are inverses of each other, we can
+easily get the formula for calculating `IYR` from `i`:
+
 ```
-IYR = nominal interest rate per year (without compounding)
-PYR = number of payments per year
+IYR = CYR expm1[ (PYR/CYR) log1p(i) ]
 ```
 
-In addition, most real-life problems express the annual interest rate as a
-percentage instead of a dimensionless fraction. So `IYR = I%YR / 100`, where
-`I%YR` is the nominal interest percentage per year.
+From `IYR`, we can calculate the nominal percent interest rate `I%YR` as
+`100*IYR`.
 
 ## TVM Formulas
 
@@ -361,6 +393,12 @@ equation are *unchanged*. Let's define a new term `CFN(i,N)`:
 
 ```
 CFN(i,N) = CF2(i)/N = [(1+i)^N-1]/Ni
+
+             expm1(N log1p(i)) / Ni     (i!=0)
+           /
+         =
+           \
+             1                          (i==0)
 ```
 
 (Note that this is slightly different than the `C(i,N)` function defined by
@@ -374,8 +412,9 @@ called `NPMT(i)`:
 
 ```
 NPMT(i) = NFV(i) / CFN(i,N)
-        = PV (1+i)^N Ni / [(1+i)^N-1] + (1+ip)N*PMT + FV / CFN(i,N)
-        = PV (-N)i / [(1+i)^(-N)-1] + (1+ip)N*PMT + FV / CFN(i,N)
+        = PV (1+i)^N Ni / [(1+i)^N-1] + (1+ip)N*PMT + FV Ni / [(1+i)^N-1]
+        = PV (1+i)^N Ni / [(1+i)^N-1] + (1+ip)N*PMT + FV Ni / [(1+i)^N-1]
+        = PV (-N)i / [(1+i)^(-N)-1] + (1+ip)N*PMT + FV Ni / [(1+i)^N-1]
         = PV / CFN(i,-N) + (1+ip)N*PMT + FV / CFN(i,N)
 ```
 
@@ -432,11 +471,18 @@ beginning or end of the cash flow. The `NPMT(i)` function essentially averages
 all 3 terms over the entire duration of the `N` payment periods, instead of
 pulling everything to the present or pushing everything to the future.
 
-**Implementation Note**: The `inverseCompoundingFactor()` routine calculates the
-reciprocal of `CFN(i,N)`. In other words, it calculates `ICFN(i,N) = 1/CFN(i,N)
-= Ni/((1+i)^N-1)` for a slight gain in efficiency by avoiding a division or two.
-This makes `ICFN(i,N)` similar to the `C(n)` function given by Albert Chan in
-[TVM formula error in programming
+**Implementation Note**:
+
+The `inverseCompoundingFactor()` routine calculates the reciprocal of
+`CFN(i,N)`. In other words, it calculates
+
+```
+ICFN(i,N) = 1/CFN(i,N) = Ni/((1+i)^N-1)
+```
+
+for a slight gain in efficiency by avoiding a division or two. This makes
+`ICFN(i,N)` similar to the `C(n)` function given by Albert Chan in [TVM formula
+error in programming
 manual?](https://www.hpmuseum.org/forum/thread-20739-post-179371.html#pid179371)
 (2023), within a factor of `(1+i)^N`, or equivalently, a substitution of `-N`
 for `N`.
@@ -472,20 +518,31 @@ of about 1e-8 within 7-8 iterations.
 ### Initial Guesses
 
 The Secant method (as well as other root finding methods) requires 2 initial
-guesses to be provided. The TVM Solver currently (v0.9.0) uses the following
-defaults:
-
-- `i0` = 0
-- `i1` = 1/PYR, where PYR is the number of payments per year.
-
-The value of `i0` can be set to `0` because all of our various terms and
-equations (`ICFN(i,N)`, `NPMT(i)`) have been defined to remove their singularity
-at `i=0`. Those functions are now continuous (and probably infinitely
-differentiable) at `i=0`.
-
-The value of `i1` is actually specified as `IYR1` of 100%, a nominal yearly rate
-of 100%. Most real-life problems will never need to search for an interest rate
-higher than 100%/year. The `i1` variable is `IYR/PYR` or `100%/PYR` or `1/PYR`.
+guesses to be provided. The TVM Solver (v0.12.0) uses the following defaults:
+
+- `IYR1` = -50%
+- `IYR2` = 100%
+
+We calculate the internal payment-period initial guesses `i1` and `i2` using the
+formula `i=expm1[(CYR/PYR) log1p(IYR/CYR)]` as given above. From these starting
+points `i1` and `i2`, the TVM Solver makes a few more heuristic guesses:
+
+- If the interval `[i1, i2]` overlaps the 0% point, the intervals are split into
+  two on either side of the `0`:
+    - `[i1,0]` and `[0,i2]`
+    - the positive interest interval `[0,i2]` is checked first, and if no sign
+      change is detected, then,
+    - the negative interest interval is checked
+- If no sign change is detected in either `[i1,0]` and `[0,i2]`, then we take
+  the positive interval `[0,i2]` and decompose that into 2 intervals again:
+    - check the lower interval `[0,(i1+i2)/2]` first, and if no sign change
+      is found, then
+    - check the upper interval `[(i1+i2)/2, i2]`
+
+The value of `i=0` is allowed in the various candidate intervals because all of
+our various terms and equations (`ICFN(i,N)`, `NPMT(i)`) have been defined to
+remove their singularity at `i=0`. Those functions are now continuous (and
+probably infinitely differentiable) at `i=0`.
 
 The following posts by Albert Chan suggest that there are better initial guess:
 
@@ -502,38 +559,46 @@ checks if the very first guesses bracket a root with a change in sign of the
 `NPMT(i)` function. If no sign change is detected, a `TVM No Solution` error
 message is returned.
 
-### Tolerance
+### Terminating Conditions
 
-Currently (v0.9.0), the TVM Solver iterates until the relative tolerance between
-two successive iterations is less than 1e-8. The value of 1e-8 is hardcoded.
+TVM Solver iterates until the relative tolerance between two successive
+iterations is less than some amount. The root finding iteration stops when one
+of the following conditions are met:
 
-To avoid division by zero, the tolerance is calculated as:
+- `f0==0`
+- `f1==0`
+- `f1==f0` and `iterationCount>=3`
+- `|i1-i0|<=tol*max(|i1|,|i0|)`, `tol=1e-10`
 
-```
-      |i1 - i0| / |i1|, if |i1|!=0
-     /
-tol =
-     \
-      |i1 - i0|, if i1==0
+The values `f0` and `f1` are defined to be `f0=NPMT(i0)` and `f1=NPMT(i1)` and
+the conditions `f0==0` and `f1==0` detect the situation where an iteration lands
+directly on the root of the equation.
 
-```
+The `f1==f0` condition happens when the 2 successive iteration produces no
+change in the value of `NPMT(i)`. The `iterationCount>=3` comes from avoiding
+the situation where the very early guesses just happened to evaluate to a secant
+line with zero slope, which results in a division-by-zero error when evaluating
+the next iteration.
 
-I am sure this is not optimal, but I needed a quick way to avoid a division by
-zero if `i1` was equal to zero.
+The complicated equation involving the `tol` parameter detects the convergence
+of successive iterations of `i0` and `i1`. The equation was selected to deal
+with situations where the solution converges to a value that is equal or very
+close to `0`.
 
-Maybe the tolerance limit (1e-8) should be exposed to the user and be
-configurable? I believe the HP calculators use the number of significant digits
-in its `FIX` mode to determine the tolerance limit. But TI calculator users tend
-not to use `FIX` modes, leaving the calculator with the maximum number of
-significant digits (i.e. the `FIX(-)` mode). I'm not sure that using the number
-of digits from the `FIX` mode is a reasonable mechanism for the RPN83P app.
+The tolerance limit (`tol=1e-10`) is hard coded and not configurable by the
+user. (I'm not sure if it's useful to make that configurable). I believe the HP
+calculators use the number of significant digits in its `FIX` mode to determine
+the tolerance limit. But TI calculator users tend not to use `FIX` modes,
+leaving the calculator with the maximum number of significant digits (i.e. the
+`FIX(-)` mode). I'm not sure that using the number of digits from the `FIX` mode
+is a reasonable mechanism for the RPN83P app.
 
 ### Maximum Iterations
 
 To avoid an infinite loop, the maximum iterations used by the TVM Solver is
 limited to `TMAX`. By default, `TMAX` is set to 15, but can be configured by the
 user. Empirically, the TVM Solver (using the Secant method) seems to converge to
-the tolerance of 1e-8 within about 7-8 iterations. So I set the default `TMAX`
+the tolerance of 1e-10 within about 7-8 iterations. So I set the default `TMAX`
 to be about double that, which is where the 15 came from.
 
 ### Convergence

docs/USER_GUIDE.md

@@ -2,7 +2,7 @@
 
 RPN calculator app for the TI-83 Plus and TI-84 Plus inspired by the HP-42S.
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Project Home**: https://github.com/bxparks/rpn83p
 
@@ -150,7 +150,8 @@ Summary of features:
     - carry flag and bit masks: `CCF`, `SCF`, `CF?`, `CB`, `SB`, `B?`
     - word sizes: `WSIZ`, `WSZ?`: 8, 16, 24, 32 bits
 - time value of money (TVM), inspired by HP-12C, HP-17B, and HP-30b
-    - `N`, `I%YR`, `PV`, `PMT`, `FV`, `P/YR`, `BEG`, `END`, `CLTV` (clear TVM)
+    - `N`, `I%YR`, `PV`, `PMT`, `FV`
+    - `P/YR`, `C/YR`, `BEG`, `END`, `CLTV` (clear TVM)
 - complex numbers, inspired by HP-42S and HP-35s
     - stored in RPN stack registers (`X`, `Y`, `Z`, `T`, `LASTX`) and storage
       registers `R00-R99`
@@ -1420,6 +1421,7 @@ buttons just under the LCD screen. Use the `UP`, `DOWN`, `ON` (EXIT/ESC), and
     - `PMT`: set or calculate Payment per period
     - `FV`: set or calculate Future Value
     - `P/YR`: set number of payments per year
+    - `C/YR`: set number of compoundings per year
     - `BEG`: payment occurs at the Beginning of each period
     - `END`: payment occurs at the End of each period
     - `CLTV`: clear TVM variables and parameters
@@ -2163,16 +2165,17 @@ The RPN83P app interacts with the underlying TI-OS in the following ways.
       exiting. Changing the `MODE` settings in one app will not cause changes to
       the other.
 - TVM variables
-    - RPN83P uses some of the same TI-OS floating point variables used by the
-      `Finance` app (automatically provided by the TI-OS on the TI-84 Plus).
-        - `N`, `I%YR`, `PV`, `PMT`, `FV`, and `P/YR`
-    - These variables appear in the Finance app with slightly different names:
-        - `N`, `I%`, `PV`, `PMT`, `FV`, and `P/Y`
-    - Two variables not synchronized between the 2 apps are:
-        - `BEG`/`END` flag
-            - could not figure out where the Finance app stores this
-        - `C/Y` (compoundings per year)
-            - always set equal to `P/YR` in the RPN83P app
+    - RPN83P uses the exact same TI-OS floating point variables and flags used
+      by the `Finance` app (automatically provided by the TI-OS on the TI-84
+      Plus). When these variables are changed in RPN83P, they automatically
+      appear in the `Finance` app, and vise versa:
+    - RPN83P variable names:
+        - `N`, `I%YR`, `PV`, `PMT`, `FV`, `P/YR`, `C/YR`, `BEG`, `END`
+    - TI-OS Finance app variable names:
+        - `N`, `I%`, `PV`, `PMT`, `FV`, `P/Y`, `C/Y`, `BEGIN`, `END`
+    - An interesting consequence of sharing these variables with the TI-OS
+      Finance app is that these are the only RPN83P variables which are *not*
+      saved in the `RPN83SAV` appVar.
 
 ## Future Enhancements
 

docs/USER_GUIDE_BASE.md

@@ -1,11 +1,11 @@
-# RPN83P User Guide: BASE Operations
+# RPN83P User Guide: BASE Functions
 
 This document describes the `BASE` functions of the RPN83P application which
 allow numbers to be converted between 4 different bases (DEC, HEX, OCT, and BIN)
 and support various arithmetic and bitwise operations similar to the HP-16C. It
 has been extracted from [USER_GUIDE.md](USER_GUIDE.md) due to its length.
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Parent Document**: [USER_GUIDE.md](USER_GUIDE.md)
 

docs/USER_GUIDE_COMPLEX.md

@@ -10,7 +10,7 @@ independent of each other. For example, a complex number can be entered in
 rectangular form, even if the current display mode is polar form. Internally,
 complex numbers are *always* stored in rectangular format.
 
-**Version**: 0.11.0 (2024-05-28)
+**Version**: 0.12.0-rc1 (2024-06-18)
 
 **Parent Document**: [USER_GUIDE.md](USER_GUIDE.md)