Commit 330675e5 authored by Raymond Toy's avatar Raymond Toy
Browse files

Merge branch 'issue-19-more-api-doc' into 'master'

Fix #19: Add more API documentation

Closes #19

See merge request !16
parents 5a7c3f72 a78f0675
Pipeline #2392 passed with stage
in 2 minutes and 22 seconds
# Oct
A Lisp Implementation of Quad-Double Float
Oct, A Lisp Implementation of Quad-Double Float
[[_TOC_]]
## Introduction
Oct is a portable Lisp implementation of quad-double arithmetic. This
......@@ -107,30 +108,77 @@ Note that `+pi+` is the `QD-REAL` value for pi.
## API
Oct has implementations for all of the numeric functions in
COMMON-LISP updated to support quad-doubles. In addition, Oct
supports these:
- `make-qd`
- `jacobi-sn`
- `jacobi-cn`
- `jacobi-dn`
- `elliptic-k`
- `elliptic-f`
- `elliptic-e`
- `elliptic-ec`
- `carlson-rd`
- `carlson-rf`
- `carlson-rj`
- `elliptic-theta-1`
- `elliptic-theta-2`
- `elliptic-theta-3`
- `elliptic-theta-4`
- `elliptic-theta`
- `erf`
- `erfc`
- `log-gamma`
- `gamma`
- `psi`
- `incomplete-gamma-lower a z &key normalized-p`
supports additional special functions
### Utilities
- [function] **`MAKE-QD`** _`X`_
Creates a quad-double from `X` where `X` can be a rational, float, or a quad-double.
### Gamma
- [function] **`GAMMA`** _`Z`_
Computes the gamma function [defined by](https://dlmf.nist.gov/5.2.E1)
```math
\Gamma(z) = \int_0^{\infty} t^{z-1} e^{-t} dt
```
for complex `Z`.
- [function] **`LOG-GAMMA`** _`Z`_
Computes $`\log \Gamma(z)`$
- [function] **`PSI`** _`Z`_
Computes the logarithmic derivative of $`\Gamma(z)`$ [defined by](https://dlmf.nist.gov/5.2.E2)
```math
\psi(z) = \frac{\Gamma'(z)}{\Gamma(z)}
```
### Exponential, Logarithmic, Sine, and Cosine Integrals
- [function] **`SIN-INTEGRAL`** _`Z`_
Computes the sin integral [defined by](https://dlmf.nist.gov/6.2.E9)
```math
\mathrm{Si}(z) = \int_0^z \frac{\sin t}{t} dt
```
- [function] **`COS-INTEGRAL`** _`Z`_
Computes the cosine integral [defined by](https://dlmf.nist.gov/6.2.E13)
```math
\mathrm{Ci}(z) = \int_0^z \frac{1 - \cos t}{t} dt + \log z + \gamma
```
### Error Functions, Dawson's and Fresnel Integrals
- [function] **`ERF`** _`Z`_
Computes the error function [defined by](https://dlmf.nist.gov/7.2.E1)
```math
\mathrm{erf} z = \frac{2}{\sqrt\pi} \int_0^z e^{-t^2} dt
```
- [function] **`ERFC`** _`Z`_
Computes the complementary error function [defined by](https://dlmf.nist.gov/7.2.E2):
```math
\mathrm{erfc} z = \frac{2}{\sqrt\pi} \int_z^{\infty} e^{-t^2} dt = 1 - \mathrm{erf} z
```
- [function] **`FRESNEL-C`** _`Z`_
Computes the Fresnel integral $`C(z)`$ [defined by](https://dlmf.nist.gov/7.2.E7):
```math
C(z) = \int_0^z \cos\frac{\pi t^2}{2} dt
```
- [function] **`FRESNEL-S`** _`Z`_
Computes the Fresnel integral $`S(z)`$ [defined by](https://dlmf.nist.gov/7.2.E8):
```math
S(z) = \int_0^z \sin\frac{\pi t^2}{2} dt
```
### Incomplete Gamma and Related Functions
- [function] **`INCOMPLETE-GAMMA-LOWER`** _`A`_ _`Z`_ _`&KEY`_ _`NORMALIZED-P`_
If `normalized-p` is `NIL`, return the [value](https://dlmf.nist.gov/8.2.E1):
```math
\gamma(a, z) = \int_0^z t^{a-1} e^{-t} dt
......@@ -139,7 +187,8 @@ supports these:
```math
P(a, z) = \frac{1}{\Gamma(a)} \int_0^z t^{a-1} e^{-t} dt
```
- `incomplete-gamma-upper`
- [function] **`INCOMPLETE-GAMMA-UPPER`** _`A`_ _`Z`_
If `normalized-p` is `NIL`, return the [value](https://dlmf.nist.gov/8.2.E2):
```math
\Gamma(a, z) = \int_z^{\infty} t^{a-1} e^{-t} dt
......@@ -148,17 +197,125 @@ supports these:
```math
Q(a, z) = \frac{1}{\Gamma(a)} \int_z^{\infty} t^{a-1} e^{-t} dt
```
- `incomplete-gamma-lower-normalized a z`
- [function] **`INCOMPLETE-GAMMA-LOWER-NORMALIZED`** _`A`_ _`Z`_
Returns the [value](https://dlmf.nist.gov/8.2.E4):
```math
P(a, z) = \frac{1}{\Gamma(a)} \int_0^z t^{a-1} e^{-t} dt
```
- `incomplete-gamma-upper-normalized a z`
- [function] **`INCOMPLETE-GAMMA-UPPER-NORMALIZED`** _`A`_ _`Z`_
Returns the [value](https://dlmf.nist.gov/8.2.E4):
```math
Q(a, z) = \frac{1}{\Gamma(a)} \int_z^{\infty} t^{a-1} e^{-t} dt
```
- `fresnel-s`
- `fresnel-c`
- `sin-integral`
- `cos-integral`
### Elliptic Integrals
The elliptic integrals are defined in terms of $`m`$ where $`m = k^2`$
where $`k`$ is the [modulus](https://dlmf.nist.gov/19.1).
- [function] **`ELLIPTIC-K`** _`M`_
Computes the complete elliptic integral of the first kind [defined
by](https://dlmf.nist.gov/19.2.E8):
```math
K(m) = F\left(\frac{\pi}{2}\biggr\rvert m\right) = \int_0^{\frac{\pi}{2}} \frac{dt}{\sqrt{1-m\sin^2 t}}
```
- [function] **`ELLIPTIC-F`** _`X`_ _`M`_
Computes the elliptic integral of the first kind [defined by](https://dlmf.nist.gov/19.2.E4):
```math
F(x|m) = \int_0^m \frac{dt}{\sqrt{1-m\sin^2 t}} = \int_0^{\sin x} \frac{dt}{\sqrt{1-t^2}\sqrt{1-mt^2}}
```
- [function] **`ELLIPTIC-E`** _`X`_ _`M`_
Computes the elliptic integral of the second kind [defined by](https://dlmf.nist.gov/19.2.E5):
```math
E(x|m) = \int_0^x \sqrt{1-m\sin^2 t}\, dt = \int_0^{\sin x} \frac{\sqrt{1-mt^2}}{\sqrt{1-t^2}}\, dt
```
- [function] **`ELLIPTIC-EC`** _`X`_ _`M`_
Computes the complete elliptic integral of the second kind [defined by](https://dlmf.nist.gov/19.2.E8)
```math
E(m) = E\left(\frac{\pi}{2}\biggr\rvert m\right) = \int_0^{\frac{\pi}{2}} \sqrt{1-m\sin^2 t}\, dt
```
- [function] **`CARLSON-RD`** _`X`_ _`Y`_ _`Z`_
Computes Carlson's integral $`R_D`$ [defined by](https://dlmf.nist.gov/19.16.E5):
```math
R_D(x,y,z) = \frac{3}{2} \int_0^\infty \frac{dt}{(t+z)\sqrt{t+x}\sqrt{t+y}\sqrt{t+z}}
```
- [function] **`CARLSON-RF`** _`X`_ _`Y`_ _`Z`_
Computes Carlson's integral $`R_F`$ [defined by](https://dlmf.nist.gov/19.16.E1):
```math
R_F(x,y,z) = \frac{1}{2} \int_0^\infty \frac{dt}{\sqrt{t+x}\sqrt{t+y}\sqrt{t+z}}
```
- [function] **`CARLSON-RJ`** _`X`_ _`Y`_ _`Z`_ _`P`_
Computes Carlson's integral $`R_J`$ [defined by](https://dlmf.nist.gov/19.16.E2)
```math
R_J(x,y,z,p) = \frac{3}{2} \int_0^\infty \frac{dt}{(t+p)\sqrt{t+x}\sqrt{t+y}\sqrt{t+z}}
```
### Theta Functions
The theta functions can be defined in terms of the parameter $`\tau`$
but the definitions used here use the nome $`q`$ where $`q =
e^{i\pi\tau}`$.
- [function] **`ELLIPTIC-THETA`** _`N`_ _`Z`_ _`Q`_
Computes the elliptic theta function for $`N = 1,2,3,4`$.
- [function] **`ELLIPTIC-THETA-1`** _`Z`_ _`Q`_
Computes the first theta function as a function of the nome $`q`$ [defined by](https://dlmf.nist.gov/20.2.E1):
```math
\theta_1(z, q) = 2 \sum_{n=0}^{\infty} \left(-1\right)^n q^{\left(n+\frac{1}{2}\right)^2} \sin (2n+1)z
```
- [function] **`ELLIPTIC-THETA-2`** _`Z`_ _`Q`_
Computes the second theta function as a function of the nome $`q`$ [defined by](https://dlmf.nist.gov/20.2.E2):
```math
\theta_2(z, q) = 2 \sum_{n=0}^{\infty} q^{\left(n+\frac{1}{2}\right)^2} \cos (2n+1)z
```
- [function] **`ELLIPTIC-THETA-3`** _`Z`_ _`Q`_
Computes the first theta function as a function of the nome $`q`$ [defined by](https://dlmf.nist.gov/20.2.E3):
```math
\theta_3(z, q) = 1 + 2 \sum_{n=0}^{\infty} q^{n^2} \cos 2nz
```
- [function] **`ELLIPTIC-THETA-4`** _`Z`_ _`Q`_
Computes the fourth theta function as a function of the nome $`q`$ [defined by](https://dlmf.nist.gov/20.2.E4):
```math
\theta_4(z, q) = 1 + 2 \sum_{n=0}^{\infty} \left(-1\right)^n q^{n^2} \cos 2nz
```
### Jacobian Elliptic Functions
For the elliptic functions, [define the _nome_](https://dlmf.nist.gov/22.2.E1) $`q`$ in terms of the parameter $`m`$ by:
```math
q = \mathrm{exp}\left(\frac{-\pi K'(m)}{K(m)}\right)
```
Also [define](https://dlmf.nist.gov/22.2.E3)
```math
\zeta = \frac{\pi u}{2K(m)}
```
- [function] **`JACOBI-SN`** _`U`_ _`M`_
Computes the Jacobi $`\mathrm{sn}`$ function [defined by](https://dlmf.nist.gov/22.2.E4):
```math
\mathrm{sn}(u|m) = \frac{\theta_3(0,q)}{\theta_2(0,q)}\frac{\theta_1(\zeta, q)}{\theta_4(\zeta, q)}
```
- [function] **`JACOBI-CN`** _`U`_ _`M`_
Computes the Jacobi $`\mathrm{cn}`$ function [defined by](https://dlmf.nist.gov/22.2.E5):
```math
\mathrm{cn}(u|m) = \frac{\theta_4(0,q)}{\theta_2(0,q)}\frac{\theta_2(\zeta, q)}{\theta_4(\zeta, q)}
```
- [function] **`jacobi-dn`** _`U`_ _`M`_
Computes the Jacobi $`\mathrm{dn}`$ function [defined by](https://dlmf.nist.gov/22.2.E6):
```math
\mathrm{dn}(u|m) = \frac{\theta_4(0,q)}{\theta_3(0,q)}\frac{\theta_3(\zeta, q)}{\theta_4(\zeta, q)}
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment