airy(k,x) documentation and implementation

[simonp0420]

1. The Julia docs state that airy(k,x) returns the k'th derivative of the Airy function Ai(x). Looking at the code in math.jl, one sees that airy(k,x) is a utility function used to implement the four Airy functions provided by Julia. In particular:

airyai(x) = airy(0,x)
airyaiprime(x) = airy(1,x)
airybi(x) = airy(2,x)
airybiprime(x) = airy(3,x)

0, 1, 2, and 3 are the only valid values that the first argument of airy(k,x) can take. I suggest that airy(k,x) not be exported to the global name space and that it be removed from the documentation.
2. Depending on the value of k, airy(k,x) calls one of the Amos collection routines ZAIRY or ZBIRY via a ccall to the openlibm_extras library using the symbol :zairy_ or :zbiry_. Both calls specify that there are 8 arguments to the subroutines. However, the Fortran signatures of these two Amos routines read as follows:

SUBROUTINE ZAIRY(ZR, ZI, ID, KODE, AIR, AII, NZ, IERR)
SUBROUTINE ZBIRY(ZR, ZI, ID, KODE, BIR, BII, IERR)

Since ZBIRY has only 7 arguments, it appears to me that the ccall to :zbiry_ should be corrected to specify only 7 arguments.

I am currently working on Issue #4172, and I had planned on modifying the Airy function routines as well as the complex-argument Bessel function routines to check the underflow and error flags returned by the Amos routines. So it seems logical that I should also address the two items listed above in this issue. But before touching the code for airy(k,x) I would like to request some help in understanding why it was globally declared and defined inside of a let block that also defines variables ai and ae, which IIUC are local to the let block. However, similarly named variables are defined and used in exactly the same way outside of this let block. Could someone ( @staticfloat,perhaps) enlighten me on the purpose of this let block, so I don't accidentally break something I don't understand?

[ViralBShah]

See: http://docs.julialang.org/en/latest/manual/variables-and-scoping/

let blocks restrict the scope of the variables defined in them to within the block. Making something global inside a let block lets it escape and be available in global scope. Without having looked into the details of these functions, it seems that ai and ae are temporary work arrays that airy needs. This way they are defined only once, and available only for the airy function.

[ViralBShah]

Let's add some more tests that detect this issue.

[simonp0420]

@ViralBShah , thanks for the pointers and explanation. I see the utility of this construction--it beats making the temporary arrays local by declaring them inside the function definition, where they would have to be allocated every time the function is executed.

I'll take a stab at the modifications I outlined above and submit the initial pull request as a work-in-progress.

[nolta]

Thanks @simonp0420 for spotting the zbiry issue.

airy(k,x) is the matlab compatible function, whereas airyai, airybi, airyaiprime, & airybiprime are the mathematica names. We should probably pick one or the other, but that's why we have both.

[simonp0420]

@nolta Ah, it never occurred to me to compare to Matlab's calling convention. I'm almost done with the changes, which to date include eliminating the global function airy(k,x) in favor of the specific functions. But I'd be happy to put it back in if that is what you'd prefer.

[nolta]

Yeah, probably best to leave airy(k,x) in for now.

[simonp0420]

Will do. Also, while I’m modifying the manual to document the new optional arguments, I’ll fix up the description of airy(k,x) to reflect its actual behavior.

From: Mike Nolta [mailto:notifications@github.com]
Sent: Tuesday, November 26, 2013 2:01 PM
To: JuliaLang/julia
Cc: simonp0420
Subject: Re: [julia] airy(k,x) documentation and implementation (#4915)

Yeah, probably best to leave airy(k,x) in for now.

—
Reply to this email directly or view it on GitHub #4915 (comment) . https://github.com/notifications/beacon/4kPCveyhxub6xNf4ifJeMvfoJ45fiz2T7VSxYU7NV9YVVWWhx6lldfRrAaaRHXS4.gif

[simonp0420]

Fixed by commit 870dd27