help for ^ridder^             [STB-17: ssi5.2; STB-19: ssi5.3; STB-24: ssi5.4]

Equation solving by Ridders' Method -----------------------------------

 ^ridder^ fcnmask ^=^ exp_y ^from^ exp_0 ^to^ exp_1 [^tol^ exp_t] [^ltol^ exp_l > ]

where exp_y, exp_0, exp_1, exp_t, and exp_l refer to expressions (but are typically specified as numbers) and where fcnmask is either:

(1)    an expression containing ^X^

(2)    progname [args] ^X^ [args] ^returns^ {^exp^|^macro^} name

If one of ^tol^ or ^ltol^ is omitted, ^ridder^ ignores that constraint. ^tol 1e-6^ is assumed if neither ^tol^ nor ^ltol^ is specified.

Description -----------

^ridder^ finds the value of X such that

         f(X) = exp_y

or, more precisely:

|f(X) - exp_y| < e   and   |x - x_hat| < exp_t

where e = exp_y*max(|exp_y|,1).

The search is carried out over the range exp_0 <= X <= exp_1.  The function f() may be specified on the command line (first syntax for fcnmask) or as a user-written program (second sytnax).

Example 1 ---------

Find the value of chi-square with 2 degrees of freedom that is just signif- icant at the 5% level.

Solution:  Stata's ^chiprob(^d^,^x^)^ function returns the reverse cumulative f > or chi-square value x with d degrees of freedom (e.g., ^chiprob(2,3)^ is .2231, meaning chi-square 2 with 3 degrees of freedom is significant at the 22.3% percent level).  Thus, we want to find X such that ^chiprob(2,^X^)^=.05.  From knowledge of the chi-square distribution, we know the answer lies between 3 and 20.  We type:

. ^ridder chiprob(2,X)=.05 from 3 to 20^

Example 1, second solution --------------------------

We define the following program:

^program define mychi^ ^global S_1 = chiprob(`1',`2')^ ^end^

and then type

. ^ridder mychi 2 X returns macro S_1 =.05 from 3 to 8^

Alternatively, we define the program

^program define mychi^ ^scalar answer = chiprob(`1',`2')^ ^end^

and then type

. ^ridder mychi 2 X returns exp answer =.05 from 3 to 8^

Example 2 ---------

Given                        a                         t-1              1.1       -2 S   =  [ ( -----------   - 2 ) ( ------- ) ]         t          sqrt(S   )             a                          t-1               t

Let a[1] = 1.5 and a[2], a[3], ..., be 1.  Find S[1] such that S[19]=1/22^^2.

A program to calculate S[t], t=1,...,19 is given S[1] is:

^program define simul^ ^drop _all^ ^set obs 19^ ^gen a = cond(_n==1,1.5,1)^ ^gen S = `1' in 1^ ^replace S=((a[_n-1]/sqrt(S[_n-1])-2)*(1.1/a))^^-2 in 2/l^ ^end

Typing "^simul .1^" would create the series based on S[1]=.1.

Example 2, continued --------------------

We can find S[1] such that S[19]==1/22^^2 by typing:

. ^ridder simul X returns exp S[19] =1/22^^2 from .001 to .75^


"^simul X^" means ^ridder^ can calculate values of the function by issuing the command ^simul^ followed by the number at which it wants the function evaluated.  ^X^ is a placeholder.

"^returns exp S[19]^" means simul returns the answer as the expression S[19], meaning the 19th observation of the data variable S.

"^=1/22^^2^" means we want the answer to be 1/22^^2.

"^from .001 to .75^" means we want to search over the range .001 to .75 for the solution.

Author ------

       Tim McGuire, Stata Corporation        EMAIL  tech-support@@stata.com

Also see --------

   STB:  ssi5.4 (STB-24), ssi5.3 (STB-19), ssi5.2 (STB-17),          ssi5 (STB-16), ssi5.1 (STB-16) On-line:  ^help^ for @fcnplot@ (if ssi5.1 installed)