This is Info file calc.info, produced by Makeinfo-1.55 from the input file calc.texinfo. This file documents Calc, the GNU Emacs calculator. Copyright (C) 1990, 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the section entitled "GNU General Public License" is included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that the section entitled "GNU General Public License" may be included in a translation approved by the author instead of in the original English. File: calc.info, Node: Time Zones, Prev: Business Days, Up: Date Arithmetic Time Zones ---------- Time zones and daylight savings time are a complicated business. The conversions to and from Julian and Unix-style dates automatically compute the correct time zone and daylight savings adjustment to use, provided they can figure out this information. This section describes Calc's time zone adjustment algorithm in detail, in case you want to do conversions in different time zones or in case Calc's algorithms can't determine the right correction to use. Adjustments for time zones and daylight savings time are done by `t U', `t J', `t N', and `t C', but not by any other commands. In particular, ` - ' evaluates to exactly 30 days even though there is a daylight-savings transition in between. This is also true for Julian pure dates: `julian() - julian()'. But Julian and Unix date/times will adjust for daylight savings time: `julian(<12am may 1 1991>) - julian(<12am apr 1 1991>)' evaluates to `29.95834' (that's 29 days and 23 hours) because one hour was lost when daylight savings commenced on April 7, 1991. In brief, the idiom `julian(DATE1) - julian(DATE2)' computes the actual number of 24-hour periods between two dates, whereas `DATE1 - DATE2' computes the number of calendar days between two dates without taking daylight savings into account. The `calc-time-zone' [`tzone'] command converts the time zone specified by its numeric prefix argument into a number of seconds difference from Greenwich mean time (GMT). If the argument is a number, the result is simply that value multiplied by 3600. Typical arguments for North America are 5 (Eastern) or 8 (Pacific). If Daylight Savings time is in effect, one hour should be subtracted from the normal difference. If you give a prefix of plain `C-u', `calc-time-zone' (like other date arithmetic commands that include a time zone argument) takes the zone argument from the top of the stack. (In the case of `t J' and `t U', the normal argument is then taken from the second-to-top stack position.) This allows you to give a non-integer time zone adjustment. The time-zone argument can also be an HMS form, or it can be a variable which is a time zone name in upper- or lower-case. For example `tzone(PST) = tzone(8)' and `tzone(pdt) = tzone(7)' (for Pacific standard and daylight savings times, respectively). North American and European time zone names are defined as follows; note that for each time zone there is one name for standard time, another for daylight savings time, and a third for "generalized" time in which the daylight savings adjustment is computed from context. YST PST MST CST EST AST NST GMT WET MET MEZ 9 8 7 6 5 4 3.5 0 -1 -2 -2 YDT PDT MDT CDT EDT ADT NDT BST WETDST METDST MESZ 8 7 6 5 4 3 2.5 -1 -2 -3 -3 YGT PGT MGT CGT EGT AGT NGT BGT WEGT MEGT MEGZ 9/8 8/7 7/6 6/5 5/4 4/3 3.5/2.5 0/-1 -1/-2 -2/-3 -2/-3 To define time zone names that do not appear in the above table, you must modify the Lisp variable `math-tzone-names'. This is a list of lists describing the different time zone names; its structure is best explained by an example. The three entries for Pacific Time look like this: ( ( "PST" 8 0 ) ; Name as an upper-case string, then standard ( "PDT" 8 -1 ) ; adjustment, then daylight savings adjustment. ( "PGT" 8 "PST" "PDT" ) ) ; Generalized time zone. With no arguments, `calc-time-zone' or `tzone()' obtains an argument from the Calc variable `TimeZone' if a value has been stored for that variable. If not, Calc runs the Unix `date' command and looks for one of the above time zone names in the output; if this does not succeed, `tzone()' leaves itself unevaluated. The time zone name in the `date' output may be followed by a signed adjustment, e.g., `GMT+5' or `GMT+0500' which specifies a number of hours and minutes to be added to the base time zone. Calc stores the time zone it finds into `TimeZone' to speed later calls to `tzone()'. The special time zone name `local' is equivalent to no argument, i.e., it uses the local time zone as obtained from the `date' command. If the time zone name found is one of the standard or daylight savings zone names from the above table, and Calc's internal daylight savings algorithm says that time and zone are consistent (e.g., `PDT' accompanies a date that Calc's algorithm would also consider to be daylight savings, or `PST' accompanies a date that Calc would consider to be standard time), then Calc substitutes the corresponding generalized time zone (like `PGT'). If your system does not have a suitable `date' command, you may wish to put a `(setq var-TimeZone ...)' in your Emacs initialization file to set the time zone. The easiest way to do this is to edit the `TimeZone' variable using Calc's `s T' command, then use the `s p' (`calc-permanent-variable') command to save the value of `TimeZone' permanently. The `t J' and `t U' commands with no numeric prefix arguments do the same thing as `tzone()'. If the current time zone is a generalized time zone, e.g., `EGT', Calc examines the date being converted to tell whether to use standard or daylight savings time. But if the current time zone is explicit, e.g., `EST' or `EDT', then that adjustment is used exactly and Calc's daylight savings algorithm is not consulted. Some places don't follow the usual rules for daylight savings time. The state of Arizona, for example, does not observe daylight savings time. If you run Calc during the winter season in Arizona, the Unix `date' command will report `MST' time zone, which Calc will change to `MGT'. If you then convert a time that lies in the summer months, Calc will apply an incorrect daylight savings time adjustment. To avoid this, set your `TimeZone' variable explicitly to `MST' to force the use of standard, non-daylight-savings time. By default Calc always considers daylight savings time to begin at 2 a.m. on the first Sunday of April, and to end at 2 a.m. on the last Sunday of October. This is the rule that has been in effect in North America since 1987. If you are in a country that uses different rules for computing daylight savings time, you have two choices: Write your own daylight savings hook, or control time zones explicitly by setting the `TimeZone' variable and/or always giving a time-zone argument for the conversion functions. The Lisp variable `math-daylight-savings-hook' holds the name of a function that is used to compute the daylight savings adjustment for a given date. The default is `math-std-daylight-savings', which computes an adjustment (either 0 or -1) using the North American rules given above. The daylight savings hook function is called with four arguments: The date, as a floating-point number in standard Calc format; a six-element list of the date decomposed into year, month, day, hour, minute, and second, respectively; a string which contains the generalized time zone name in upper-case, e.g., `"WEGT"'; and a special adjustment to be applied to the hour value when converting into a generalized time zone (see below). The Lisp function `math-prev-weekday-in-month' is useful for daylight savings computations. This is an internal version of the user-level `pwday' function described in the previous section. It takes four arguments: The floating-point date value, the corresponding six-element date list, the day-of-month number, and the weekday number (0-6). The default daylight savings hook ignores the time zone name, but a more sophisticated hook could use different algorithms for different time zones. It would also be possible to use different algorithms depending on the year number, but the default hook always uses the algorithm for 1987 and later. Here is a listing of the default daylight savings hook: (defun math-std-daylight-savings (date dt zone bump) (cond ((< (nth 1 dt) 4) 0) ((= (nth 1 dt) 4) (let ((sunday (math-prev-weekday-in-month date dt 7 0))) (cond ((< (nth 2 dt) sunday) 0) ((= (nth 2 dt) sunday) (if (>= (nth 3 dt) (+ 3 bump)) -1 0)) (t -1)))) ((< (nth 1 dt) 10) -1) ((= (nth 1 dt) 10) (let ((sunday (math-prev-weekday-in-month date dt 31 0))) (cond ((< (nth 2 dt) sunday) -1) ((= (nth 2 dt) sunday) (if (>= (nth 3 dt) (+ 2 bump)) 0 -1)) (t 0)))) (t 0)) ) The `bump' parameter is equal to zero when Calc is converting from a date form in a generalized time zone into a GMT date value. It is -1 when Calc is converting in the other direction. The adjustments shown above ensure that the conversion behaves correctly and reasonably around the 2 a.m. transition in each direction. There is a "missing" hour between 2 a.m. and 3 a.m. at the beginning of daylight savings time; converting a date/time form that falls in this hour results in a time value for the following hour, from 3 a.m. to 4 a.m. At the end of daylight savings time, the hour from 1 a.m. to 2 a.m. repeats itself; converting a date/time form that falls in in this hour results in a time value for the first manifestion of that time (*not* the one that occurs one hour later). If `math-daylight-savings-hook' is `nil', then the daylight savings adjustment is always taken to be zero. In algebraic formulas, `tzone(ZONE, DATE)' computes the time zone adjustment for a given zone name at a given date. The DATE is ignored unless ZONE is a generalized time zone. If DATE is a date form, the daylight savings computation is applied to it as it appears. If DATE is a numeric date value, it is adjusted for the daylight-savings version of ZONE before being given to the daylight savings hook. This odd-sounding rule ensures that the daylight-savings computation is always done in local time, not in the GMT time that a numeric DATE is typically represented in. The `dsadj(DATE, ZONE)' function computes the daylight savings adjustment that is appropriate for DATE in time zone ZONE. If ZONE is explicitly in or not in daylight savings time (e.g., `PDT' or `PST') the DATE is ignored. If ZONE is a generalized time zone, the algorithms described above are used. If ZONE is omitted, the computation is done for the current time zone. *Note Reporting Bugs::, for the address of Calc's author, if you should wish to contribute your improved versions of `math-tzone-names' and `math-daylight-savings-hook' to the Calc distribution. File: calc.info, Node: Financial Functions, Next: Binary Functions, Prev: Date Arithmetic, Up: Arithmetic Financial Functions =================== Calc's financial or business functions use the `b' prefix key followed by a shifted letter. (The `b' prefix followed by a lower-case letter is used for operations on binary numbers.) Note that the rate and the number of intervals given to these functions must be on the same time scale, e.g., both months or both years. Mixing an annual interest rate with a time expressed in months will give you very wrong answers! It is wise to compute these functions to a higher precision than you really need, just to make sure your answer is correct to the last penny; also, you may wish to check the definitions at the end of this section to make sure the functions have the meaning you expect. * Menu: * Percentages:: * Future Value:: * Present Value:: * Related Financial Functions:: * Depreciation Functions:: * Definitions of Financial Functions:: File: calc.info, Node: Percentages, Next: Future Value, Prev: Financial Functions, Up: Financial Functions Percentages ----------- The `M-%' (`calc-percent') command takes a percentage value, say 5.4, and converts it to an equivalent actual number. For example, `5.4 M-%' enters 0.054 on the stack. (That's the META or ESC key combined with `%'.) Actually, `M-%' creates a formula of the form `5.4%'. You can enter `5.4%' yourself during algebraic entry. The `%' operator simply means, "the preceding value divided by 100." The `%' operator has very high precedence, so that `1+8%' is interpreted as `1+(8%)', not as `(1+8)%'. (The `%' operator is just a postfix notation for the `percent' function, just like `20!' is the notation for `fact(20)', or twenty-factorial.) The formula `5.4%' would normally evaluate immediately to 0.054, but the `M-%' command suppresses evaluation as it puts the formula onto the stack. However, the next Calc command that uses the formula `5.4%' will evaluate it as its first step. The net effect is that you get to look at `5.4%' on the stack, but Calc commands see it as `0.054', which is what they expect. In particular, `5.4%' and `0.054' are suitable values for the RATE arguments of the various financial functions, but the number `5.4' is probably *not* suitable--it represents a rate of 540 percent! The key sequence `M-% *' effectively means "percent-of." For example, `68 RET 25 M-% *' computes 17, which is 25% of 68 (and also 68% of 25, which comes out to the same thing). The `c %' (`calc-convert-percent') command converts the value on the top of the stack from numeric to percentage form. For example, if 0.08 is on the stack, `c %' converts it to `8%'. The quantity is the same, it's just represented differently. (Contrast this with `M-%', which would convert this number to `0.08%'.) The `=' key is a convenient way to convert a formula like `8%' back to numeric form, 0.08. To compute what percentage one quantity is of another quantity, use `/ c %'. For example, `17 RET 68 / c %' displays `25%'. The `b %' (`calc-percent-change') [`relch'] command calculates the percentage change from one number to another. For example, `40 RET 50 b %' produces the answer `25%', since 50 is 25% larger than 40. A negative result represents a decrease: `50 RET 40 b %' produces `-20%', since 40 is 20% smaller than 50. (The answers are different in magnitude because, in the first case, we're increasing by 25% of 40, but in the second case, we're decreasing by 20% of 50.) The effect of `40 RET 50 b %' is to compute `(50-40)/40', converting the answer to percentage form as if by `c %'. File: calc.info, Node: Future Value, Next: Present Value, Prev: Percentages, Up: Financial Functions Future Value ------------ The `b F' (`calc-fin-fv') [`fv'] command computes the future value of an investment. It takes three arguments from the stack: `fv(RATE, N, PAYMENT)'. If you give payments of PAYMENT every year for N years, and the money you have paid earns interest at RATE per year, then this function tells you what your investment would be worth at the end of the period. (The actual interval doesn't have to be years, as long as N and RATE are expressed in terms of the same intervals.) This function assumes payments occur at the *end* of each interval. The `I b F' [`fvb'] command does the same computation, but assuming your payments are at the beginning of each interval. Suppose you plan to deposit $1000 per year in a savings account earning 5.4% interest, starting right now. How much will be in the account after five years? `fvb(5.4%, 5, 1000) = 5870.73'. Thus you will have earned $870 worth of interest over the years. Using the stack, this calculation would have been `5.4 M-% 5 RET 1000 I b F'. Note that the rate is expressed as a number between 0 and 1, *not* as a percentage. The `H b F' [`fvl'] command computes the future value of an initial lump sum investment. Suppose you could deposit those five thousand dollars in the bank right now; how much would they be worth in five years? `fvl(5.4%, 5, 5000) = 6503.89'. The algebraic functions `fv' and `fvb' accept an optional fourth argument, which is used as an initial lump sum in the sense of `fvl'. In other words, `fv(RATE, N, PAYMENT, INITIAL) = fv(RATE, N, PAYMENT) + fvl(RATE, N, INITIAL)'. To illustrate the relationships between these functions, we could do the `fvb' calculation "by hand" using `fvl'. The final balance will be the sum of the contributions of our five deposits at various times. The first deposit earns interest for five years: `fvl(5.4%, 5, 1000) = 1300.78'. The second deposit only earns interest for four years: `fvl(5.4%, 4, 1000) = 1234.13'. And so on down to the last deposit, which earns one year's interest: `fvl(5.4%, 1, 1000) = 1054.00'. The sum of these five values is, sure enough, $5870.73, just as was computed by `fvb' directly. What does `fv(5.4%, 5, 1000) = 5569.96' mean? The payments are now at the ends of the periods. The end of one year is the same as the beginning of the next, so what this really means is that we've lost the payment at year zero (which contributed $1300.78), but we're now counting the payment at year five (which, since it didn't have a chance to earn interest, counts as $1000). Indeed, `5569.96 = 5870.73 - 1300.78 + 1000' (give or take a bit of roundoff error). File: calc.info, Node: Present Value, Next: Related Financial Functions, Prev: Future Value, Up: Financial Functions Present Value ------------- The `b P' (`calc-fin-pv') [`pv'] command computes the present value of an investment. Like `fv', it takes three arguments: `pv(RATE, N, PAYMENT)'. It computes the present value of a series of regular payments. Suppose you have the chance to make an investment that will pay $2000 per year over the next four years; as you receive these payments you can put them in the bank at 9% interest. You want to know whether it is better to make the investment, or to keep the money in the bank where it earns 9% interest right from the start. The calculation `pv(9%, 4, 2000)' gives the result 6479.44. If your initial investment must be less than this, say, $6000, then the investment is worthwhile. But if you had to put up $7000, then it would be better just to leave it in the bank. Here is the interpretation of the result of `pv': You are trying to compare the return from the investment you are considering, which is `fv(9%, 4, 2000) = 9146.26', with the return from leaving the money in the bank, which is `fvl(9%, 4, X)' where X is the amount of money you would have to put up in advance. The `pv' function finds the break-even point, `x = 6479.44', at which `fvl(9%, 4, 6479.44)' is also equal to 9146.26. This is the largest amount you should be willing to invest. The `I b P' [`pvb'] command solves the same problem, but with payments occurring at the beginning of each interval. It has the same relationship to `fvb' as `pv' has to `fv'. For example `pvb(9%, 4, 2000) = 7062.59', a larger number than `pv' produced because we get to start earning interest on the return from our investment sooner. The `H b P' [`pvl'] command computes the present value of an investment that will pay off in one lump sum at the end of the period. For example, if we get our $8000 all at the end of the four years, `pvl(9%, 4, 8000) = 5667.40'. This is much less than `pv' reported, because we don't earn any interest on the return from this investment. Note that `pvl' and `fvl' are simple inverses: `fvl(9%, 4, 5667.40) = 8000'. You can give an optional fourth lump-sum argument to `pv' and `pvb'; this is handled in exactly the same way as the fourth argument for `fv' and `fvb'. The `b N' (`calc-fin-npv') [`npv'] command computes the net present value of a series of irregular investments. The first argument is the interest rate. The second argument is a vector which represents the expected return from the investment at the end of each interval. For example, if the rate represents a yearly interest rate, then the vector elements are the return from the first year, second year, and so on. Thus, `npv(9%, [2000,2000,2000,2000]) = pv(9%, 4, 2000) = 6479.44'. Obviously this function is more interesting when the payments are not all the same! The `npv' function can actually have two or more arguments. Multiple arguments are interpreted in the same way as for the vector statistical functions like `vsum'. *Note Single-Variable Statistics::. Basically, if there are several payment arguments, each either a vector or a plain number, all these values are collected left-to-right into the complete list of payments. A numeric prefix argument on the `b N' command says how many payment values or vectors to take from the stack. The `I b N' [`npvb'] command computes the net present value where payments occur at the beginning of each interval rather than at the end. File: calc.info, Node: Related Financial Functions, Next: Depreciation Functions, Prev: Present Value, Up: Financial Functions Related Financial Functions --------------------------- The functions in this section are basically inverses of the present value functions with respect to the various arguments. The `b M' (`calc-fin-pmt') [`pmt'] command computes the amount of periodic payment necessary to amortize a loan. Thus `pmt(RATE, N, AMOUNT)' equals the value of PAYMENT such that `pv(RATE, N, PAYMENT) = AMOUNT'. The `I b M' [`pmtb'] command does the same computation but using `pvb' instead of `pv'. Like `pv' and `pvb', these functions can also take a fourth argument which represents an initial lump-sum investment. The `H b M' key just invokes the `fvl' function, which is the inverse of `pvl'. There is no explicit `pmtl' function. The `b #' (`calc-fin-nper') [`nper'] command computes the number of regular payments necessary to amortize a loan. Thus `nper(RATE, PAYMENT, AMOUNT)' equals the value of N such that `pv(RATE, N, PAYMENT) = AMOUNT'. If PAYMENT is too small ever to amortize a loan for AMOUNT at interest rate RATE, the `nper' function is left in symbolic form. The `I b #' [`nperb'] command does the same computation but using `pvb' instead of `pv'. You can give a fourth lump-sum argument to these functions, but the computation will be rather slow in the four-argument case. The `H b #' [`nperl'] command does the same computation using `pvl'. By exchanging PAYMENT and AMOUNT you can also get the solution for `fvl'. For example, `nperl(8%, 2000, 1000) = 9.006', so if you place $1000 in a bank account earning 8%, it will take nine years to grow to $2000. The `b T' (`calc-fin-rate') [`rate'] command computes the rate of return on an investment. This is also an inverse of `pv': `rate(N, PAYMENT, AMOUNT)' computes the value of RATE such that `pv(RATE, N, PAYMENT) = AMOUNT'. The result is expressed as a formula like `6.3%'. The `I b T' [`rateb'] and `H b T' [`ratel'] commands solve the analogous equations with `pvb' or `pvl' in place of `pv'. Also, `rate' and `rateb' can accept an optional fourth argument just like `pv' and `pvb'. To redo the above example from a different perspective, `ratel(9, 2000, 1000) = 8.00597%', which says you will need an interest rate of 8% in order to double your account in nine years. The `b I' (`calc-fin-irr') [`irr'] command is the analogous function to `rate' but for net present value. Its argument is a vector of payments. Thus `irr(PAYMENTS)' computes the RATE such that `npv(RATE, PAYMENTS) = 0'; this rate is known as the "internal rate of return". The `I b I' [`irrb'] command computes the internal rate of return assuming payments occur at the beginning of each period. File: calc.info, Node: Depreciation Functions, Next: Definitions of Financial Functions, Prev: Related Financial Functions, Up: Financial Functions Depreciation Functions ---------------------- The functions in this section calculate "depreciation", which is the amount of value that a possession loses over time. These functions are characterized by three parameters: COST, the original cost of the asset; SALVAGE, the value the asset will have at the end of its expected "useful life"; and LIFE, the number of years (or other periods) of the expected useful life. There are several methods for calculating depreciation that differ in the way they spread the depreciation over the lifetime of the asset. The `b S' (`calc-fin-sln') [`sln'] command computes the "straight-line" depreciation. In this method, the asset depreciates by the same amount every year (or period). For example, `sln(12000, 2000, 5)' returns 2000. The asset costs $12000 initially and will be worth $2000 after five years; it loses $2000 per year. The `b Y' (`calc-fin-syd') [`syd'] command computes the accelerated "sum-of-years'-digits" depreciation. Here the depreciation is higher during the early years of the asset's life. Since the depreciation is different each year, `b Y' takes a fourth PERIOD parameter which specifies which year is requested, from 1 to LIFE. If PERIOD is outside this range, the `syd' function will return zero. The `b D' (`calc-fin-ddb') [`ddb'] command computes an accelerated depreciation using the double-declining balance method. It also takes a fourth PERIOD parameter. For symmetry, the `sln' function will accept a PERIOD parameter as well, although it will ignore its value except that the return value will as usual be zero if PERIOD is out of range. For example, pushing the vector `[1,2,3,4,5]' (perhaps with `v x 5') and then mapping `V M ' [sln(12000,2000,5,$), syd(12000,2000,5,$), ddb(12000,2000,5,$)] RET' produces a matrix that allows us to compare the three depreciation methods: [ [ 2000, 3333, 4800 ] [ 2000, 2667, 2880 ] [ 2000, 2000, 1728 ] [ 2000, 1333, 592 ] [ 2000, 667, 0 ] ] (Values have been rounded to nearest integers in this figure.) We see that `sln' depreciates by the same amount each year, `syd' depreciates more at the beginning and less at the end, and `ddb' weights the depreciation even more toward the beginning. Summing columns with `V R : +' yields `[10000, 10000, 10000]'; the total depreciation in any method is (by definition) the difference between the cost and the salvage value. File: calc.info, Node: Definitions of Financial Functions, Prev: Depreciation Functions, Up: Financial Functions Definitions ----------- For your reference, here are the actual formulas used to compute Calc's financial functions. Calc will not evaluate a financial function unless the RATE or N argument is known. However, PAYMENT or AMOUNT can be a variable. Calc expands these functions according to the formulas below for symbolic arguments only when you use the `a "' (`calc-expand-formula') command, or when taking derivatives or integrals or solving equations involving the functions. These formulas are shown using the conventions of "Big" display mode (`d B'); for example, the formula for `fv' written linearly is `pmt * ((1 + rate)^n) - 1) / rate'. n (1 + rate) - 1 fv(rate, n, pmt) = pmt * --------------- rate n ((1 + rate) - 1) (1 + rate) fvb(rate, n, pmt) = pmt * ---------------------------- rate n fvl(rate, n, pmt) = pmt * (1 + rate) -n 1 - (1 + rate) pv(rate, n, pmt) = pmt * ---------------- rate -n (1 - (1 + rate) ) (1 + rate) pvb(rate, n, pmt) = pmt * ----------------------------- rate -n pvl(rate, n, pmt) = pmt * (1 + rate) -1 -2 -3 npv(rate, [a, b, c]) = a*(1 + rate) + b*(1 + rate) + c*(1 + rate) -1 -2 npvb(rate, [a, b, c]) = a + b*(1 + rate) + c*(1 + rate) -n (amt - x * (1 + rate) ) * rate pmt(rate, n, amt, x) = ------------------------------- -n 1 - (1 + rate) -n (amt - x * (1 + rate) ) * rate pmtb(rate, n, amt, x) = ------------------------------- -n (1 - (1 + rate) ) (1 + rate) amt * rate nper(rate, pmt, amt) = - log(1 - ------------, 1 + rate) pmt amt * rate nperb(rate, pmt, amt) = - log(1 - ---------------, 1 + rate) pmt * (1 + rate) amt nperl(rate, pmt, amt) = - log(---, 1 + rate) pmt 1/n pmt ratel(n, pmt, amt) = ------ - 1 1/n amt cost - salv sln(cost, salv, life) = ----------- life (cost - salv) * (life - per + 1) syd(cost, salv, life, per) = -------------------------------- life * (life + 1) / 2 book * 2 ddb(cost, salv, life, per) = --------, book = cost - depreciation so far life In `pmt' and `pmtb', `x=0' if omitted. These functions accept any numeric objects, including error forms, intervals, and even (though not very usefully) complex numbers. The above formulas specify exactly the behavior of these functions with all sorts of inputs. Note that if the first argument to the `log' in `nper' is negative, `nper' leaves itself in symbolic form rather than returning a (financially meaningless) complex number. `rate(num, pmt, amt)' solves the equation `pv(rate, num, pmt) = amt' for `rate' using `H a R' (`calc-find-root'), with the interval `[.01% .. 100%]' for an initial guess. The `rateb' function is the same except that it uses `pvb'. Note that `ratel' can be solved directly; its formula is shown in the above list. Similarly, `irr(pmts)' solves the equation `npv(rate, pmts) = 0' for `rate'. If you give a fourth argument to `nper' or `nperb', Calc will also use `H a R' to solve the equation using an initial guess interval of `[0 .. 100]'. A fourth argument to `fv' simply sums the two components calculated from the above formulas for `fv' and `fvl'. The same is true of `fvb', `pv', and `pvb'. The `ddb' function is computed iteratively; the "book" value starts out equal to COST, and decreases according to the above formula for the specified number of periods. If the book value would decrease below SALVAGE, it only decreases to SALVAGE and the depreciation is zero for all subsequent periods. The `ddb' function returns the amount the book value decreased in the specified period. The Calc financial function names were borrowed mostly from Microsoft Excel and Borland's Quattro. The `ratel' function corresponds to `@CGR' in Borland's Reflex. The `nper' and `nperl' functions correspond to `@TERM' and `@CTERM' in Quattro, respectively. Beware that the Calc functions may take their arguments in a different order than the corresponding functions in your favorite spreadsheet. File: calc.info, Node: Binary Functions, Prev: Financial Functions, Up: Arithmetic Binary Number Functions ======================= The commands in this chapter all use two-letter sequences beginning with the `b' prefix. The "binary" operations actually work regardless of the currently displayed radix, although their results make the most sense in a radix like 2, 8, or 16 (as obtained by the `d 2', `d 8', or `d 6' commands, respectively). You may also wish to enable display of leading zeros with `d z'. *Note Radix Modes::. The Calculator maintains a current "word size" `w', an arbitrary positive or negative integer. For a positive word size, all of the binary operations described here operate modulo `2^w'. In particular, negative arguments are converted to positive integers modulo `2^w' by all binary functions. If the word size is negative, binary operations produce 2's complement integers from `-(2^(-w-1))' to `2^(-w-1)-1' inclusive. Either mode accepts inputs in any range; the sign of `w' affects only the results produced. The `b c' (`calc-clip') [`clip'] command can be used to clip a number by reducing it modulo `2^w'. The commands described in this chapter automatically clip their results to the current word size. Note that other operations like addition do not use the current word size, since integer addition generally is not "binary." (However, *note Simplification Modes::., `calc-bin-simplify-mode'.) For example, with a word size of 8 bits `b c' converts a number to the range 0 to 255; with a word size of -8 `b c' converts to the range -128 to 127. The default word size is 32 bits. All operations except the shifts and rotates allow you to specify a different word size for that one operation by giving a numeric prefix argument: `C-u 8 b c' clips the top of stack to the range 0 to 255 regardless of the current word size. To set the word size permanently, use `b w' (`calc-word-size'). This command displays a prompt with the current word size; press RET immediately to keep this word size, or type a new word size at the prompt. When the binary operations are written in symbolic form, they take an optional second (or third) word-size parameter. When a formula like `and(a,b)' is finally evaluated, the word size current at that time will be used, but when `and(a,b,-8)' is evaluated, a word size of -8 will always be used. A symbolic binary function will be left in symbolic form unless the all of its argument(s) are integers or integer-valued floats. If either or both arguments are modulo forms for which `M' is a power of two, that power of two is taken as the word size unless a numeric prefix argument overrides it. The current word size is never consulted when modulo-power-of-two forms are involved. The `b a' (`calc-and') [`and'] command computes the bitwise AND of the two numbers on the top of the stack. In other words, for each of the `w' binary digits of the two numbers (pairwise), the corresponding bit of the result is 1 if and only if both input bits are 1: `and(2#1100, 2#1010) = 2#1000'. The `b o' (`calc-or') [`or'] command computes the bitwise inclusive OR of two numbers. A bit is 1 if either of the input bits, or both, are 1: `or(2#1100, 2#1010) = 2#1110'. The `b x' (`calc-xor') [`xor'] command computes the bitwise exclusive OR of two numbers. A bit is 1 if exactly one of the input bits is 1: `xor(2#1100, 2#1010) = 2#0110'. The `b d' (`calc-diff') [`diff'] command computes the bitwise difference of two numbers; this is defined by `diff(a,b) = and(a,not(b))', so that `diff(2#1100, 2#1010) = 2#0100'. The `b n' (`calc-not') [`not'] command computes the bitwise NOT of a number. A bit is 1 if the input bit is 0 and vice-versa. The `b l' (`calc-lshift-binary') [`lsh'] command shifts a number left by one bit, or by the number of bits specified in the numeric prefix argument. A negative prefix argument performs a logical right shift, in which zeros are shifted in on the left. In symbolic form, `lsh(a)' is short for `lsh(a,1)', which in turn is short for `lsh(a,n,w)'. Bits shifted "off the end," according to the current word size, are lost. The `H b l' command also does a left shift, but it takes two arguments from the stack (the value to shift, and, at top-of-stack, the number of bits to shift). This version interprets the prefix argument just like the regular binary operations, i.e., as a word size. The Hyperbolic flag has a similar effect on the rest of the binary shift and rotate commands. The `b r' (`calc-rshift-binary') [`rsh'] command shifts a number right by one bit, or by the number of bits specified in the numeric prefix argument: `rsh(a,n) = lsh(a,-n)'. The `b L' (`calc-lshift-arith') [`ash'] command shifts a number left. It is analogous to `lsh', except that if the shift is rightward (the prefix argument is negative), an arithmetic shift is performed as described below. The `b R' (`calc-rshift-arith') [`rash'] command performs an "arithmetic" shift to the right, in which the leftmost bit (according to the current word size) is duplicated rather than shifting in zeros. This corresponds to dividing by a power of two where the input is interpreted as a signed, twos-complement number. (The distinction between the `rsh' and `rash' operations is totally independent from whether the word size is positive or negative.) With a negative prefix argument, this performs a standard left shift. The `b t' (`calc-rotate-binary') [`rot'] command rotates a number one bit to the left. The leftmost bit (according to the current word size) is dropped off the left and shifted in on the right. With a numeric prefix argument, the number is rotated that many bits to the left or right. *Note Set Operations::, for the `b p' and `b u' commands that pack and unpack binary integers into sets. (For example, `b u' unpacks the number `2#11001' to the set of bit-numbers `[0, 3, 4]'.) Type `b u V #' to count the number of "1" bits in a binary integer. Another interesting use of the set representation of binary integers is to reverse the bits in, say, a 32-bit integer. Type `b u' to unpack; type `31 TAB -' to replace each bit-number in the set with 31 minus that bit-number; type `b p' to pack the set back into a binary integer. File: calc.info, Node: Scientific Functions, Next: Matrix Functions, Prev: Arithmetic, Up: Top Scientific Functions ******************** The functions described here perform trigonometric and other transcendental calculations. They generally produce floating-point answers correct to the full current precision. The `H' (Hyperbolic) and `I' (Inverse) flag keys must be used to get some of these functions from the keyboard. One miscellanous command is shift-`P' (`calc-pi'), which pushes the value of `pi' (at the current precision) onto the stack. With the Hyperbolic flag, it pushes the value `e', the base of natural logarithms. With the Inverse flag, it pushes Euler's constant `gamma' (about 0.5772). With both Inverse and Hyperbolic, it pushes the "golden ratio" `phi' (about 1.618). (At present, Euler's constant is not available to unlimited precision; Calc knows only the first 100 digits.) In Symbolic mode, these commands push the actual variables `pi', `e', `gamma', and `phi', respectively, instead of their values; *note Symbolic Mode::.. The `Q' (`calc-sqrt') [`sqrt'] function is described elsewhere; *note Basic Arithmetic::.. With the Inverse flag [`sqr'], this command computes the square of the argument. *Note Prefix Arguments::, for a discussion of the effect of numeric prefix arguments on commands in this chapter which do not otherwise interpret a prefix argument. * Menu: * Logarithmic Functions:: * Trigonometric and Hyperbolic Functions:: * Advanced Math Functions:: * Branch Cuts:: * Random Numbers:: * Combinatorial Functions:: * Probability Distribution Functions:: File: calc.info, Node: Logarithmic Functions, Next: Trigonometric and Hyperbolic Functions, Prev: Scientific Functions, Up: Scientific Functions Logarithmic Functions ===================== The shift-`L' (`calc-ln') [`ln'] command computes the natural logarithm of the real or complex number on the top of the stack. With the Inverse flag it computes the exponential function instead, although this is redundant with the `E' command. The shift-`E' (`calc-exp') [`exp'] command computes the exponential, i.e., `e' raised to the power of the number on the stack. The meanings of the Inverse and Hyperbolic flags follow from those for the `calc-ln' command. The `H L' (`calc-log10') [`log10'] command computes the common (base-10) logarithm of a number. (With the Inverse flag [`exp10'], it raises ten to a given power.) Note that the common logarithm of a complex number is computed by taking the natural logarithm and dividing by `ln(10)'. The `B' (`calc-log') [`log'] command computes a logarithm to any base. For example, `1024 RET 2 B' produces 10, since `2^10 = 1024'. In certain cases like `log(3,9)', the result will be either `1:2' or `0.5' depending on the current Fraction Mode setting. With the Inverse flag [`alog'], this command is similar to `^' except that the order of the arguments is reversed. The `f I' (`calc-ilog') [`ilog'] command computes the integer logarithm of a number to any base. The number and the base must themselves be positive integers. This is the true logarithm, rounded down to an integer. Thus `ilog(x,10)' is 3 for all `x' in the range from 1000 to 9999. If both arguments are positive integers, exact integer arithmetic is used; otherwise, this is equivalent to `floor(log(x,b))'. The `f E' (`calc-expm1') [`expm1'] command computes `exp(x)-1', but using an algorithm that produces a more accurate answer when the result is close to zero, i.e., when `exp(x)' is close to one. The `f L' (`calc-lnp1') [`lnp1'] command computes `ln(x+1)', producing a more accurate answer when `x' is close to zero. File: calc.info, Node: Trigonometric and Hyperbolic Functions, Next: Advanced Math Functions, Prev: Logarithmic Functions, Up: Scientific Functions Trigonometric/Hyperbolic Functions ================================== The shift-`S' (`calc-sin') [`sin'] command computes the sine of an angle or complex number. If the input is an HMS form, it is interpreted as degrees-minutes-seconds; otherwise, the input is interpreted according to the current angular mode. It is best to use Radians mode when operating on complex numbers. Calc's "units" mechanism includes angular units like `deg', `rad', and `grad'. While `sin(45 deg)' is not evaluated all the time, the `u s' (`calc-simplify-units') command will simplify `sin(45 deg)' by taking the sine of 45 degrees, regardless of the current angular mode. *Note Basic Operations on Units::. Also, the symbolic variable `pi' is not ordinarily recognized in arguments to trigonometric functions, as in `sin(3 pi / 4)', but the `a s' (`calc-simplify') command recognizes many such formulas when the current angular mode is radians *and* symbolic mode is enabled; this example would be replaced by `sqrt(2) / 2'. *Note Symbolic Mode::. Beware, this simplification occurs even if you have stored a different value in the variable `pi'; this is one reason why changing built-in variables is a bad idea. Arguments of the form `x' plus a multiple of `pi/2' are also simplified. Calc includes similar formulas for `cos' and `tan'. The `a s' command knows all angles which are integer multiples of `pi/12', `pi/10', or `pi/8' radians. In degrees mode, analogous simplifications occur for integer multiples of 15 or 18 degrees, and for arguments plus multiples of 90 degrees. With the Inverse flag, `calc-sin' computes an arcsine. This is also available as the `calc-arcsin' command or `arcsin' algebraic function. The returned argument is converted to degrees, radians, or HMS notation depending on the current angular mode. With the Hyperbolic flag, `calc-sin' computes the hyperbolic sine, also available as `calc-sinh' [`sinh']. With the Hyperbolic and Inverse flags, it computes the hyperbolic arcsine (`calc-arcsinh') [`arcsinh']. The shift-`C' (`calc-cos') [`cos'] command computes the cosine of an angle or complex number, and shift-`T' (`calc-tan') [`tan'] computes the tangent, along with all the various inverse and hyperbolic variants of these functions. The `f T' (`calc-arctan2') [`arctan2'] command takes two numbers from the stack and computes the arc tangent of their ratio. The result is in the full range from -180 (exclusive) to +180 (inclusive) degrees, or the analogous range in radians. A similar result would be obtained with `/' followed by `I T', but the value would only be in the range from -90 to +90 degrees since the division loses information about the signs of the two components, and an error might result from an explicit division by zero which `arctan2' would avoid. By (arbitrary) definition, `arctan2(0,0)=0'. The `calc-sincos' [`sincos'] command computes the sine and cosine of a number, returning them as a vector of the form `[COS, SIN]'. With the Inverse flag [`arcsincos'], this command takes a two-element vector as an argument and computes `arctan2' of the elements. (This command does not accept the Hyperbolic flag.) File: calc.info, Node: Advanced Math Functions, Next: Branch Cuts, Prev: Trigonometric and Hyperbolic Functions, Up: Scientific Functions Advanced Mathematical Functions =============================== Calc can compute a variety of less common functions that arise in various branches of mathematics. All of the functions described in this section allow arbitrary complex arguments and, except as noted, will work to arbitrarily large precisions. They can not at present handle error forms or intervals as arguments. NOTE: These functions are still experimental. In particular, their accuracy is not guaranteed in all domains. It is advisable to set the current precision comfortably higher than you actually need when using these functions. Also, these functions may be impractically slow for some values of the arguments. The `f g' (`calc-gamma') [`gamma'] command computes the Euler gamma function. For positive integer arguments, this is related to the factorial function: `gamma(n+1) = fact(n)'. For general complex arguments the gamma function can be defined by the following definite integral: `gamma(a) = integ(t^(a-1) exp(t), t, 0, inf)'. (The actual implementation uses far more efficient computational methods.) The `f G' (`calc-inc-gamma') [`gammaP'] command computes the incomplete gamma function, denoted `P(a,x)'. This is defined by the integral, `gammaP(a,x) = integ(t^(a-1) exp(t), t, 0, x) / gamma(a)'. This implies that `gammaP(a,inf) = 1' for any `a' (see the definition of the normal gamma function). Several other varieties of incomplete gamma function are defined. The complement of `P(a,x)', called `Q(a,x) = 1-P(a,x)' by some authors, is computed by the `I f G' [`gammaQ'] command. You can think of this as taking the other half of the integral, from `x' to infinity. The functions corresponding to the integrals that define `P(a,x)' and `Q(a,x)' but without the normalizing `1/gamma(a)' factor are called `g(a,x)' and `G(a,x)', respectively (where `g' and `G' represent the lower- and upper-case Greek letter gamma). You can obtain these using the `H f G' [`gammag'] and `H I f G' [`gammaG'] commands. The `f b' (`calc-beta') [`beta'] command computes the Euler beta function, which is defined in terms of the gamma function as `beta(a,b) = gamma(a) gamma(b) / gamma(a+b)', or by `beta(a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, 1)'. The `f B' (`calc-inc-beta') [`betaI'] command computes the incomplete beta function `I(x,a,b)'. It is defined by `betaI(x,a,b) = integ(t^(a-1) (1-t)^(b-1), t, 0, x) / beta(a,b)'. Once again, the `H' (hyperbolic) prefix gives the corresponding un-normalized version [`betaB']. The `f e' (`calc-erf') [`erf'] command computes the error function `erf(x) = 2 integ(exp(-(t^2)), t, 0, x) / sqrt(pi)'. The complementary error function `I f e' (`calc-erfc') [`erfc'] is the corresponding integral from `x' to infinity; the sum `erf(x) + erfc(x) = 1'. The `f j' (`calc-bessel-J') [`besJ'] and `f y' (`calc-bessel-Y') [`besY'] commands compute the Bessel functions of the first and second kinds, respectively. In `besJ(n,x)' and `besY(n,x)' the "order" parameter `n' is often an integer, but is not required to be one. Calc's implementation of the Bessel functions currently limits the precision to 8 digits, and may not be exact even to that precision. Use with care!