Commit 1113e156 authored by Raymond Toy's avatar Raymond Toy
Browse files

Merge branch 'issue-17-update-readme' into 'master'

Fix #17: Update README

Closes #17

See merge request !15
parents d0758610 c2bffa25
Pipeline #2327 passed with stage
in 1 minute and 50 seconds
# Oct
A Lisp Implementation of Quad-Double Float
## Introduction
Oct is a portable Lisp implementation of quad-double arithmetic. This
gives about 65 digits of precision. Quad-double arithmetic uses four
double-float numbers to represent an extended precision number.
The implementation is modeled on the [quad-double package](https://www.davidhbailey.com/dhbpapers/quad-double.pdf) by Yozo
Hida. This package is in C++, but we have translated parts of it and
extended it to use Lisp. The intent is to provide all of the CL
arithmetic functions with a quad-double implementation.
The implementation is modeled on the [quad-double
package](http://www.cs.berkeley.edu/~yozo/papers/LBNL-46996.ps.gz) by
[Yozo Hida](http://www.cs.berkeley.edu/~yozo/). This package is in
C++, but we have translated parts of it and extended it to use
Lisp. The intent is to provide all of the CL arithmetic functions with
a quad-double implementation.
Further information will be provided at a later date. This is
currently a work in progress, but the current code has the basic
functionality implemented and includes all of the special functions
specified by CL. There are, undoubtedly, many bugs.
## Supported Lisps
This package has been tested with CMUCL, SBCL, Clisp, and Allegro. All
tests pass. Note that development is primarily done using CMUCL.
See the [wiki](https://gitlab.common-lisp.net/oct/oct/-/wikis/home) for more information.
## Building Oct
1. Obtain a copy of Oct:
- For a fresh checkout:
- Users:
```
git clone --recurse-submodules https://gitlab.common-lisp.net/oct/oct.git
```
- Developrs:
```
git clone --recurse-submodules git@common-lisp.net:oct/oct.git
```
- To update a copy:
```
git pull --recurse-submodules
```
1. Make sure you have asdf. This is now commonly available with all
supported lisps, but if not, use
[Quicklisp](https://www.quicklisp.org/beta/) to get it.
1. To compile the package, assuming you've started lisp in the same
directory as oct:
```
(pushnew "./" asdf:*central-registry*)
(asdf:oos 'asdf:load-op :oct)
```
1. If desired, you can also run the test suite:
```
(asdf:test-system :oct)
```
This should pass with some known test failures.
## Using Oct
Everything in Oct resides in the `NET.COMMON-LISP.OCT` package, with a
nickname of `OCT`. The basic arithmetic operations of CL are shadowed
in this package so you can use natural Lisp expressions to operate on
quad-doubles. Special functions are included.
There are two types added:
* `QD-REAL`
A quad-double type. This has about 65 digits of precision, or about 212 bits.
* `QD-COMPLEX`
A complex type consisting of two `QD-REAL` values.
The reader is also modified to make it easier to enter quad-double
values. `#q` is used to enter both `QD-REAL` and `QD-COMPLEX`
types. For example `#q1.25q5` is the `QD-REAL` with the value
125000. The exponent marker is `q`. To enter a `QD-COMPLEX` value,
use `#q(r i)` where `r` and `i` are the real and imaginary parts. The
parts will be coerced to `QD-REAL` type if necessary.
## Examples
Here are a few examples:
```
* (in-package "OCT")
* (named-readtables:in-readtable oct:oct-readtable)
OCT> (/ (sqrt #q3) 2)
#q0.866025403784438646763723170752936183471402626905190314027903489696q0
OCT> (sin (/ +pi+ 3))
#q0.86602540378443864676372317075293618347140262690519031402790348972q0
OCT> (sqrt #q-1)
#q(#q0.0q0 #q1.0q0)
OCT> (coerce 7 'qd-complex)
#q(#q7.0q0 #q0.0q0)
OCT> (integer-decode-float +pi+)
165424160919322423196824703508232170249081435635340508251270944637
-215
1
OCT> +pi+
#q3.1415926535897932384626433832795028841971693993751058209749445923q0
OCT> (* 4 (atan #q1))
#q3.1415926535897932384626433832795028841971693993751058209749445923q0
```
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`
- `incomplete-gamma-upper`
- `fresnel-s`
- `fresnel-c`
- `sin-integral`
- `cos-integral`
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