The special-functions Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The special-functions Reference Manual

This is the special-functions Reference Manual, version 1.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 17:51:29 2021 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

# See https://github.com/alphapapa/emacs-package-dev-handbook/blob/master/README.org
# For a good example of a README in org mode

#+TITLE: Special Functions

  This library implements numerical special functions in common
  lisp with a focus on high accuracy double-float calculations.

* Contents                                                         :noexport:
:PROPERTIES:
:TOC:      :include siblings :ignore this :depth 1 :force depth
:END:
:CONTENTS:
- [[#Installation][Installation]]
- [[#Numerical Domain][Numerical Domain]]
- [[#API][API]]
- [[#Tests][Tests]]
- [[#Status][Status]]
- [[#Contributing][Contributing]]
:END:


* Installation

  Until the project is in Quicklisp, you'll need clone the repository
  into your =~/common-lisp/= directory and then use quicklisp to load
  it, like so =(ql:quickload "special-functions")=.

** Dependencies
   Most dependencies are in Quicklisp. Until we get our version of
   numerical utilities in Quicklisp, you will also need to clone or
   download it.

* Numerical Domain

  The library assumes working with double-floats. It will probably
  work with single-float as well. Whilst we would prefer to handle the
  complex domain, the majority of the source algorithms do not handle
  this.

* The API

** Special Functions

   | function     | source |
   |--------------+--------|
   | erf          | libm   |
   | erfc         | libm   |
   | inverse-erf  | Boost  |
   | inverse-erfc | Boost  |
   | log-gamma    | libm   |


** Accuracy

   The following table shows the peak and mean errors using Boost test
   data. Tests run on MS Windows 10 with SBCL 2.0.10. Boost results
   taken from the Boost [[https://www.boost.org/doc/libs/1_69_0/libs/math/doc/html/math_toolkit/sf_erf/error_function.html][error function, ]][[https://www.boost.org/doc/libs/1_68_0/libs/math/doc/html/math_toolkit/sf_erf/error_inv.html][inverse error function]] and
   [[https://www.boost.org/doc/libs/1_74_0/libs/math/doc/html/math_toolkit/sf_gamma/lgamma.html][log-gamma]] pages.

*** Error rates for erf

   | Data Set          | Boost (MS C++)                | Special-Functions                |
   |-------------------+-------------------------------+----------------------------------|
   | erf small values  | Max = 0.841ε (Mean = 0.0687ε) | Max = 6.10e-5ε (Mean = 4.58e-7ε) |
   | erf medium values | Max = 1ε     (Mean = 0.119ε)  | Max = 1ε       (Mean = 0.003ε)   |
   | erf large values  | Max = 0ε     (Mean = 0ε)      |     N/A erf range 0 < x < 6      |

*** Error rates for erfc

   | Data Set           | Boost (MS C++)                | Special-Functions                  |
   |--------------------+-------------------------------+------------------------------------|
   | erfc small values  | Max = 0ε (Mean = 0)           | Max = 1ε        (Mean = 0.00667ε)  |
   | erfc medium values | Max = 1.65ε (Mean = 0.373ε)   | Max = 1.71ε     (Mean = 0.182ε)    |
   | erfc large values  | Max = 1.14ε (Mean = 0.248ε)   | Max = 2.31e-15ε (Mean = 8.86e-18ε) |

*** Error rates for inverse-erf/c

   | Data Set     | Boost (MS C++)              | Special-Functions        |
   |--------------+-----------------------------+--------------------------+
   | inverse-erf  | Max = 1.09ε (Mean = 0.502ε) | Max = 2ε (Mean = 0.434ε) |
   | inverse-erfc | Max = 1ε    (Mean = 0.491ε) | Max = 2ε (Mean = 0.425ε) |

*** Error rates for log-gamma

   | Data Set   | Boost (MS C++)               | Special-Functions                |
   |------------+------------------------------+----------------------------------|
   | factorials | Max = 0.914ε (Mean = 0.175ε) | Max = 2.10ε   (Mean = 0.569ε)    |
   | near 0     | Max = 0.964ε (Mean = 0.462ε) | Max = 1.93ε   (Mean = 0.662ε)    |
   | near 1     | Max = 0.867ε (Mean = 0.468ε) | Max = 0.50ε   (Mean = 0.0183ε)   |
   | near 2     | Max = 0.591ε (Mean = 0.159ε) | Max = 0.0156ε (Mean = 3.83d-4ε)  |
   | near -10   | Max = 4.22ε  (Mean = 1.33ε)  | Max = 4.83d+5ε (Mean = 3.06d+4ε) |
   | near -55   | Max = 0.821ε (Mean = 0.419ε) | Max = 8.16d+4ε (Mean = 4.53d+3ε) |

   The results for log gamma are good near 1 and 2, bettering those of
   Boost, however are much worse (relatively speaking) at values of ~x
   > 8~. I don't have a good explanation for this, since the libm
   values match Boost more closely. For example:

   #+BEGIN_EXAMPLE
   (spfn:log-gamma -9.99999237060546875d0) = -3.3208925610275326d0
   (libm:lgamma    -9.99999237060546875d0) = -3.3208925610151265d0
    Boost test answer                        -3.320892561015125097640948165422843317137
   #+END_EXAMPLE

   libm:lgamma provides an additional 4 digits of accuracy over
   spfn:log-gamma when compared to the Boost test answer, despite
   using idential computations. log-gamma is still within 12 digits of
   agreement though, and likely good enough for most uses.

** NaN and Infinity

   The lisp specification mentions neither NaN nor infinity, so any
   proper treatment of these is going to be either implementation
   specific or using a third party library.

   We are using the [[https://github.com/Shinmera/float-features][float-features]] library. It works well, but doesn't
   support NaN. At some point we need to rationalize infinity and NaN
   throughout Common Lisp Statistics. There is some support for
   infinity in the extended-reals package of [[https://github.com/Common-Lisp-Statistics/numerical-utilities][numerical-utilities]], but
   it is not comprehensive. Openlibm and Cephes have definitions, but
   we don't want to introduce a large dependency just to get these
   definitions.


* Tests

  The test data is based on Boost test data. You can run all the tests
  using the ASDF test op:

  #+BEGIN_SRC lisp
  (asdf:test-system :special-functions)
  #+END_SRC

  By default the test summary values (the same as in Boost) are
  printed after each test, along with the key epsilon values.

* Status

** SBCL

  Most development is done on SBCL 2.0.10.

** ACL

  Allegro Common Lisp 10.1 has underflow issues on some of the test
  data, but otherwise works at a somewhat reduced accuracy on the
  erf/c inverse functions.

** CCL

  The system was developed primarily on CCL until we implemented the
  Boost-style test harness. There is an [[https://github.com/Symbolics/select/issues/3][issue with representations]] on
  CCL that has not be tracked down. It's likely safe to use CCL, but
  we can't be certain until the issue is fixed and we can run the test
  suite.


* Contributing
  When contributing to this repository, please first discuss major
  changes to the existing code you wish to make via a github
  issue. Minor changes and major additions are welcome. Please [[https://chris.beams.io/posts/git-commit/][write
  good commit messages]].


* License
  The Special-Functions library is available under the [[https://opensource.org/licenses/MS-PL][Microsoft
  Public License]].


* Copyright
  Copyright (c) 2020 Symbolics Pte. Ltd. All rights reserved.



Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

The main system appears first, followed by any subsystem dependency.


Previous: , Up: Systems   [Contents][Index]

2.1 special-functions

Author

Steve Nunez <steve@symbolics.tech>

License

MS-PL

Description

Special functions in Common Lisp

Version

1.1

Dependencies
Source

special-functions.asd (file)

Components

Next: , Previous: , Up: Top   [Contents][Index]

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


Previous: , Up: Files   [Contents][Index]

3.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.1 special-functions.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/special-functions-20210411-git/special-functions.asd

Systems

special-functions (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.2 special-functions/pkgdcl.lisp

Parent

special-functions (system)

Location

pkgdcl.lisp

Packages

special-functions


Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.3 special-functions/utils.lisp

Dependency

pkgdcl.lisp (file)

Parent

special-functions (system)

Location

utils.lisp

Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

3.1.4 special-functions/erf.lisp

Dependency

utils.lisp (file)

Parent

special-functions (system)

Location

erf.lisp

Exported Definitions
Internal Definitions

inverse-error (function)


Previous: , Up: Lisp files   [Contents][Index]

3.1.5 special-functions/log-gamma.lisp

Dependency

erf.lisp (file)

Parent

special-functions (system)

Location

log-gamma.lisp

Exported Definitions

log-gamma (function)

Internal Definitions

sin-pi (function)


Next: , Previous: , Up: Top   [Contents][Index]

4 Packages

Packages are listed by definition order.


Previous: , Up: Packages   [Contents][Index]

4.1 special-functions

Source

pkgdcl.lisp (file)

Nicknames
Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Top   [Contents][Index]

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


Next: , Previous: , Up: Definitions   [Contents][Index]

5.1 Exported definitions


Previous: , Up: Exported definitions   [Contents][Index]

5.1.1 Functions

Function: erf N

Returns the error function of n

Package

special-functions

Source

erf.lisp (file)

Function: erfc X

Returns the complementary error function of x

Package

special-functions

Source

erf.lisp (file)

Function: inverse-erf X

Return the inverse function of erf: (erf (inverse-erf x)) = x, -1 < x < 1

Package

special-functions

Source

erf.lisp (file)

Function: inverse-erfc X

Return the inverse function of erfc: (erfc (inverse-erfc x)) = x, 0 < x < 2

Package

special-functions

Source

erf.lisp (file)

Function: log-gamma N

Return the logarithm of gamma(x)

Package

special-functions

Source

log-gamma.lisp (file)


Previous: , Up: Definitions   [Contents][Index]

5.2 Internal definitions


Previous: , Up: Internal definitions   [Contents][Index]

5.2.1 Functions

Function: decode-float64 X

Convert the (unsigned-byte 64) bit representation into a native double-float

Package

special-functions

Source

utils.lisp (file)

Function: encode-float64 X

Returns the bit representation of the double-float X as an (unsigned-byte 64)

Package

special-functions

Source

utils.lisp (file)

Function: inverse-error P Q

Return value of inverse error function: erf_inv(p) if p <= 0.5, erfc_inv(q) otherwise

Package

special-functions

Source

erf.lisp (file)

Function: sin-pi X

Returns (sin (* pi x))

Package

special-functions

Source

log-gamma.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   F   L   S  
Index Entry  Section

F
File, Lisp, special-functions.asd: The special-functions․asd file
File, Lisp, special-functions/erf.lisp: The special-functions/erf․lisp file
File, Lisp, special-functions/log-gamma.lisp: The special-functions/log-gamma․lisp file
File, Lisp, special-functions/pkgdcl.lisp: The special-functions/pkgdcl․lisp file
File, Lisp, special-functions/utils.lisp: The special-functions/utils․lisp file

L
Lisp File, special-functions.asd: The special-functions․asd file
Lisp File, special-functions/erf.lisp: The special-functions/erf․lisp file
Lisp File, special-functions/log-gamma.lisp: The special-functions/log-gamma․lisp file
Lisp File, special-functions/pkgdcl.lisp: The special-functions/pkgdcl․lisp file
Lisp File, special-functions/utils.lisp: The special-functions/utils․lisp file

S
special-functions.asd: The special-functions․asd file
special-functions/erf.lisp: The special-functions/erf․lisp file
special-functions/log-gamma.lisp: The special-functions/log-gamma․lisp file
special-functions/pkgdcl.lisp: The special-functions/pkgdcl․lisp file
special-functions/utils.lisp: The special-functions/utils․lisp file

Jump to:   F   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

Jump to:   D   E   F   I   L   S  
Index Entry  Section

D
decode-float64: Internal functions

E
encode-float64: Internal functions
erf: Exported functions
erfc: Exported functions

F
Function, decode-float64: Internal functions
Function, encode-float64: Internal functions
Function, erf: Exported functions
Function, erfc: Exported functions
Function, inverse-erf: Exported functions
Function, inverse-erfc: Exported functions
Function, inverse-error: Internal functions
Function, log-gamma: Exported functions
Function, sin-pi: Internal functions

I
inverse-erf: Exported functions
inverse-erfc: Exported functions
inverse-error: Internal functions

L
log-gamma: Exported functions

S
sin-pi: Internal functions

Jump to:   D   E   F   I   L   S  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables


Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   P   S  
Index Entry  Section

P
Package, special-functions: The special-functions package

S
special-functions: The special-functions system
special-functions: The special-functions package
System, special-functions: The special-functions system

Jump to:   P   S