# The ratmath Reference Manual

This is the ratmath Reference Manual, version 1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Wed May 15 06:43:36 2024 GMT+0.

## 2 Systems

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

### 2.1 `ratmath`

Math utilities for working with rational numbers and intervals.

Author

Jesse Off <>

MIT

Version

1

Source
Child Components

## 3 Files

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

### 3.1 Lisp

#### 3.1.1 `ratmath/ratmath.asd`

Source
Parent Component

`ratmath` (system).

ASDF Systems

#### 3.1.2 `ratmath/package.lisp`

Source
Parent Component

`ratmath` (system).

Packages

#### 3.1.3 `ratmath/fifo.lisp`

Dependency

`package.lisp` (file).

Source
Parent Component

`ratmath` (system).

Internals

#### 3.1.5 `ratmath/ratmath.lisp`

Dependency

`pipe.lisp` (file).

Source
Parent Component

`ratmath` (system).

Public Interface
Internals

## 4 Packages

Packages are listed by definition order.

### 4.1 `ratmath`

Source
Use List

`common-lisp`.

Public Interface
Internals

## 5 Definitions

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

### 5.1 Public Interface

#### 5.1.1 Macros

Macro: infsup (&rest args)

Returns infimum/supremum intervals. All strings and numbers in tree are converted keeping everything else intact. Exacts are fuzzified according to :tol and :abstol first, and then potentially widened further with :limd and :limn, which performs a rational approximation. Intervals already present in the structure, whether by explicit cons or via a string, will not be fuzzified further by :abstol and :tol, but they may be widened if rational approximation is called out via :limd/:limn args. Exact rationals will only convert to intervals if 1) their numerators/denominators exceed :limn/:limd or 2) an :open t arg is given. When the arg is an exact and rational approximation is called out, a 2nd value, alpha, is returned which is a number from 0-1 representing the location of the original exact in the returned interval.

Package
Source
Macro: pipe-cons (object pipe)
Package
Source
Macro: pipe-sink-until-condition (pipe &rest conds)

Exposes elements of pipe until one of the condition types in conds is signalled. Returns nil for end of pipe, or 3 values: #1 being the interrupted pipe, #2 being the condition object, and #3 being the particular condition clause type in the original args that matched.

Package
Source
Macro: rat (&rest args)

Performs a rational approximation of an exact number or interval. Takes keyword args :limn and :limd to represent max numerator and max denominator. Also will parse numeric strings into intervals ala parse-interval. Always returns an exact (i.e. not another interval).

Package
Source
Macro: with-interval-math (&rest body)

Replaces arithmetic calls like *-/+ with interval*-/+ and turns ~##.## symbols into literal rational intervals with implied precision based on the number of digits after the decimal point. (as in parse-interval)

Package
Source

#### 5.1.2 Ordinary functions

Function: farey-pipe (order &key test-fn from-cf limn)

Returns a farey sequence; 2nd value is an encapsulated reverse sequence

Package
Source
Function: fractions (arg &key order)

Prints out rational approximations, one per line, with the PPM or PPB error.

Package
Source
Function: hull (&rest args)

Takes exacts and intervals as arguments and returns an interval enclosure containing the min/max. If the range between min and max is 0, hull will return an exact.

Package
Source
Function: interval (l u)

Constructs an interval from the given lower/upper bounds

Package
Source
Function: list-to-pipe (l)

Returns a pipe from a list input argument.

Package
Source
Function: lower (x)

Returns the lower limit of an interval

Package
Source
Function: napiers-constant-generator ()

Returns an infinite/irrational continued fraction expansion of Euler’s number ’e’

Package
Source
Function: parse-interval (s)

Turns strings of rationals or floats into rational intervals. Infers interval radius from number specification. e.g. 1.000 implies an interval of [.9995, 1.0005) whereas just 1 implies [.5, 1.5). Exponent notation is also recognized; 1e3 is [500, 1500) whereas 1000 is [999.5, 1000.5). A rational specified as 22/7 is converted as (43/14, 45/14).

Package
Source
Function: pipe-append (pipe1 pipe2)

Appends two pipes together

Package
Source
Function: pipe-apply (procedure pipe)

Runs procedure on every element as they are exposed, but does not transform the element.

Package
Source
Function: pipe-end-after (test pipe)

Runs test on each element. When it returns t, the pipe is truncated after that element

Package
Source
Function: pipe-end-before (test pipe)

Runs test on each element. When it returns t, the pipe is truncated before that element

Package
Source
Function: pipe-endp (pipe)
Package
Source
Function: pipe-filter (procedure pipe)

If procedure returns t, that particular pipe element is removed from the sequence.

Package
Source
Function: pipe-first (pipe)
Package
Source

Truncates a pipe after n (default: 1) elements

Package
Source
Function: pipe-last (pipe &optional n)
Package
Source
Function: pipe-mapc (procedure pipe)

Runs function on each element. Returns nothing.

Package
Source
Function: pipe-printer (pipe)
Package
Source
Function: pipe-rest (pipe)

Analogous to the rest function except works on a pipe rather than list

Package
Source
Function: pipe-signaler (pipe)

For each condition object in pipe, set up some useful restarts and signal it. If nothing handles it, the default behavior is to ignore. If the use-value restart is invoked, that value will be returned as a pipe datum element.

Package
Source
Function: pipe-sink (pipe)

Exposes elements of pipe forever, ignoring the elements. Similar to pipe-mapc with a no-op procedure. Useful to provoke the pipeline processing of an infinite pipe.

Package
Source
Function: pipe-sink-until (test pipe)

Exposes elements of pipe until test returns t. When that happens, returns the (non-empty) pipe. If the pipe goes empty, returns nil. The test procedure is called with the current element as arg.

Package
Source
Function: pipe-to-list (pipe)

Returns a list from the given pipe input argument. Infinite recursion results if the pipe is infinite.

Package
Source
Function: pipe-transform (procedure pipe)

Runs procedure on each element of pipe; replacing each original element

Package
Source
Function: pipe-uniq (pipe &optional pair-uniq-p carry)

Removes duplicates according to optional predicate func. Only dups in sequence are removed.

Package
Source
Function: rat-pipe (arg &optional mult)

Returns a pipe of best rational approximations for every power-of-mult numerator/denominator. If arg is not a number, assumes it is a continued fraction pipe.

Package
Source
Function: upper (x)

Returns the upper limit of an interval

Package
Source
Function: ~ (&rest args)

Converts intervals into an exacts. :random picks a random value within the interval instead of the midpoint. :rat picks the first convergent rational fraction (which may not be the midpoint) :upper or :lower selects the upper or lower limit. :alpha modifies whats considered the midpoint of the interval. :discrete requests to only return one of either the lower or upper interval limit. By default, returns the midpoint. If passed in a list/tree, recursively modifies everything that looks like an interval and leaves everything else intact.

Package
Source
Function: ~= (a b)

Compares either exacts or intervals for possible equality.

Package
Source

#### 5.1.3 Standalone methods

Method: print-object ((obj `convergent`) stream)
Source

### 5.2 Internals

#### 5.2.1 Macros

Macro: best-convergent-test-fn (&rest args)
Package
Source
Macro: encapsulate (form)
Package
Source
Macro: expose (procedure)
Package
Source
Macro: fifo-get (f)

Removes and returns object from fifo. If fifo becomes empty, struct is destroyed, i.e. setf nil

Package
Source
Macro: fifo-put (f obj)

Adds obj to fifo, instantiating new fifo struct if necessary. Returns new count of fifo

Package
Source
Macro: interval~ (&rest args)

When the ~ function is encounted within a with-interval-math block, it converts exacts to intervals. Outside of the lexical scope of a with-interval-math block, ~ converts intervals into exacts.

Package
Source

#### 5.2.2 Ordinary functions

Function: %infsup (x &key limn limd tol abstol open test-fn)
Package
Source
Function: %rat (x &key limn limd test-fn)
Package
Source
Function: best-convergent (arg &key limn limd test-fn)

From a rationalized continued-fraction-pipe arg, returns best convergent honoring limits. 2nd value being the next best ignoring limits.

Package
Source
Function: calc-stern-brocot (n)
Package
Source
Function: continued-fraction-pipe (f)

Returns a pipe of continued fraction terms from the input rational arg.

Package
Source
Writer: (setf convergent-a) (instance)
Package
Source
Target Slot
Writer: (setf convergent-cf) (instance)
Package
Source
Target Slot
Function: convergent-denominator (c)
Package
Source
Function: convergent-equal (a b)
Package
Source
Function: convergent-fract (c)
Package
Source
Function: convergent-numerator (c)
Package
Source
Function: convergent-p (object)
Package
Source
Function: convergent-q (c)
Package
Source
Writer: (setf convergent-q-offset) (instance)
Package
Source
Target Slot
Writer: (setf convergent-r0) (instance)
Package
Source
Target Slot
Writer: (setf convergent-r1) (instance)
Package
Source
Target Slot
Writer: (setf convergent-rat) (instance)
Package
Source
Target Slot
Function: convergent-ratio (c)
Package
Source
Function: convergent-stern-brocot (c)

From a convergent struct, make a Stern-Brocot struct by calculating the left and right parents

Package
Source
Function: convergents-pipe (cfs &optional r0 r1 a)

From a continued-fraction-pipe return a pipe of the resultant convergents.

Package
Source
Function: copy-convergent (instance)
Package
Source
Function: copy-fifo (instance)
Package
Source
Function: copy-stern-brocot (instance)
Package
Source
Function: eval-constants (args &optional pure-function-symbolp)
Package
Source
Function: fifo-count (f)
Package
Source
Writer: (setf fifo-data) (instance)
Package
Source
Target Slot
Function: fifo-endp (f)
Package
Source
Package
Source
Writer: (setf fifo-n) (instance)
Package
Source
Target Slot
Function: fifo-p (object)
Package
Source
Writer: (setf fifo-tail) (instance)
Package
Source
Target Slot
Function: functionalp (fn &optional args)
Package
Source
Function: infsup-limd (arg &key limd limn test-fn open)

Returns an infimum/supremum interval; 2nd value is alpha (>.5 when supremum is closer)

Package
Source
Function: infsup-tol (x abstol &optional tol)

Returns an infimum/supremum interval given a tolerance.

Package
Source
Function: interval* (&rest args)
Package
Source
Function: interval+ (&rest args)
Package
Source
Function: interval- (&rest args)
Package
Source
Function: interval/ (&rest args)
Package
Source
Function: intervalabs (x)
Package
Source
Function: intervalexp (x)
Package
Source
Function: intervalexpt (x y)
Package
Source
Function: intervallog (x &optional n)
Package
Source
Function: intervalsqrt (x)
Package
Source
Function: make-convergent (cf r0 r1 a &optional q-offset)
Package
Source
Function: make-fifo (&key data tail n)
Package
Source
Function: make-semi-convergent (q-offset c)
Package
Source
Function: make-stern-brocot (left-parent right-parent)
Package
Source
Function: my- (a b)
Package
Source
Function: my-min (&rest rest)
Package
Source
Function: my/ (a b)
Package
Source
Function: rationalize-continued-fraction-pipe (generator-pipe)

The normal continued-fraction-pipes have each term annotated with a lexical closure that returns the remainder to the terminal value. This value is used to qualify visiting iffy semi-convergents in a denominator/numerator limited rational approximation. With irrational numbers there is no end-value so we can give downpipe logic no insight as to whether an iffy semi-convergent is worthy.

Package
Source
Function: semi-convergent-closest-to-lim (cv limn limd)

From a specific convergent, check semi-convergents for one below num/denom limits

Package
Source
Function: semi-convergent-iffy-p (c)

Iffy semi-convergents are the exactly 1/2 CF semi-convergent of even terms.

Package
Source
Function: semi-convergent-p (c)

Semi-convergents are convergents with a truncated (up to 1/2) CF term

Package
Source
Function: stern-brocot-denominator (sb)
Package
Source
Function: stern-brocot-fract (sb)
Package
Source
Writer: (setf stern-brocot-left-parent) (instance)
Package
Source
Target Slot
Function: stern-brocot-numerator (sb)
Package
Source
Function: stern-brocot-p (object)
Package
Source
Function: stern-brocot-ratio (sb)
Package
Source
Writer: (setf stern-brocot-right-parent) (instance)
Package
Source
Target Slot
Function: truncate-within-interval (cf1 cf2)

Takes 2 continued-fraction-pipes and returns one that stops at the simplest rational inbetween

Package
Source

#### 5.2.3 Structures

Structure: convergent

Represents a (semi-)convergent in the rational approximation of a continued fraction.

Package
Source
Direct superclasses

`structure-object`.

Direct methods
Direct slots
Slot: cf
Writers
Slot: r0
Writers
Slot: r1
Writers
Slot: q-offset
Type

`integer`

Initform

`0`

Writers
Slot: a
Writers
Slot: rat
Writers
Structure: fifo
Package
Source
Direct superclasses

`structure-object`.

Direct slots
Slot: data
Type

`list`

Writers
Slot: tail
Type

`list`

Writers
Slot: n
Type

`fixnum`

Initform

`0`

Writers
Structure: stern-brocot

Stern-Brocot left/right parent used to address a node in the Stern-Brocot fraction tree.

Package
Source
Direct superclasses

`structure-object`.

Direct slots
Slot: left-parent