Numerical Utilities

For statistical computing and numerical methods
Explore the docs »

Report Bug · Request Feature · Reference Manual

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Roadmap
5. Resources
6. Contributing
7. License
8. Contact

About the Project

This library is a collection of packages useful in numerical applications, each big enough to be its own package, but too small to split out into a separate ASDF system. Included are:

• num=, a comparison operator for floats
• simple arithmetic functions, like sum and l2norm
• element-wise operations for arrays and vectors
• intervals
• special matrices and shorthand for their input
• sample statistics
• Chebyshev polynomials
• quadratures
• univariate root finding

Built With

• anaphora
• alexandria
• array-operations
• select
• let-plus

Getting Started

To get a local copy up and running follow these steps:

Prerequisites

An ANSI Common Lisp implementation. Developed and tested with SBCL and CCL.

Installation

To make the system accessible to ASDF (a build facility, similar to make in the C world), clone the repository in a directory ASDF knows about. By default the common-lisp directory in your home directory is known. Create this if it doesn't already exist and then:

1. Clone the repositories

cd ~/common-lisp && \
git clone https://github.com/Lisp-Stat/numerical-utilities.git && \
git clone https://gitlab.common-lisp.net/alexandria/alexandria.git && \
git clone https://github.com/tokenrove/anaphora.git && \
git clone https://github.com/Lisp-Stat/array-operations.git && \
git clone https://github.com/Lisp-Stat/select && \
git clone https://github.com/sharplispers/let-plus.git

2. From the REPL reset the ASDF source-registry to find the new systems:

   (asdf:clear-source-registry)

3. Load the system

   (asdf:load-system :num-utils)

If you have installed the slime ASDF extensions, you can invoke this with a comma (',') from the slime REPL.

Getting dependencies

To get the third party systems that these system may depend on, you can use a dependency manager, such as Quicklisp or CLPM Once installed, get the dependencies with either of:

(clpm-client:sync :sources "clpi") ;sources may vary

(ql:quickload :num-utils)

You need do this only once. After obtaining the dependencies, you can load the system with ASDF as described above without first syncing sources.

Documentation

The API documentation is in the docs/ directory and is available in emacs info format, PDF and HTML. You can also view the documentation online.

Usage

(nu:median '(1 2 3 4 5 6 7 8 9 10)) ; -> 11/2

Note a ratio is returned. This is a feature and Lisp-Stat leverages the Common Lisp numerical tower.

For more examples, please refer to the Reference Manual

Roadmap

See the open issues for a list of proposed features (and known issues).

Origin

This library is a fork of cl-num-utils. Changes include:

1. Make work with Genera
2. Convert to fiveam for unit tests (clunit seems abandoned)
3. Restore quadrature tests
4. Fix SBCL compiler warnings

Although the project has been renamed to distinguish it from the original, the package names are the same and should work as a drop-in replacement.

Status

It appears that this library was in the midst of a reorganization when released. As near as I can tell from the github history, all the files in cl-num-utils were moved to src/old/, and then selectively moved into src/ as they were cleaned up and unit tests written. Some, such as data-frame, were moved by Papp into separate projects. Several of the files in old/ could be dusted off and moved into src/ to be used. Check in data-frames project first because I think some were moved there without being removed from cl-num-utils.

There was a fair amount of code commented out by the original author. Where we have commented code, we use the block comment syntax #| ... |#, and noted the person performing the removal. We have also added comments throughout the code to make it more readable, or to include our research notes.

Known Issues

Test Failures

Issue 1 describes a problem with the wrapped-bivariate-to-array test in tests/matrix.lisp. This fails under fiveam, but passes on clunit. I believe there to be a bug, either in fiveam or num-utils (or, possibly, clunit). The fiveam reason-arg is misleading, it will print the two values, and they are equal. However this only happens after the second call. For example, given this code

(is (num= (funcall op a b)
      (funcall op (funcall convert a) b));)
"Expected ~A to be equal to ~A" (funcall op a b) (funcall op (funcall convert a) b))

The sequence

(funcall op a b)
(funcall op (funcall convert a) b)

is called twice, once as part of the test and once as part of the reason-args output. The first time, the results are different. The second time they are the same, making it appear that the result is a false negative. It is not.

This test needs to be looked into further. The test code will not win any 'most readable code of the year' awards, and the answer is buried below several layers of macro expansions, funcalls and currying.

Until this is resolved, use this function with caution.

Papp's issue #16 is no longer a problem. The functionality was moved to SELECT (Papp's CL-SLICE). It should have been closed but was not before Papp abandoned the library.

Implementation Support

Development is primarily done with SBCL and CCL on MS Windows. Issue papp15 reports that generic function definitions may not work on other implementations. Please report any such problems on the Github issue tracker.

Symbol conflicts with alexandria

Importing both num-utils and alexandria will result in symbol conflicts. There are two solutions for this: either import only parts of num-utils (see the packages named in each file), or shadow some symbols, e.g.

(cl:defpackage #:my-package
  (:use #:cl
    #:alexandria
    #:num-utils)
  (:shadowing-import-from #:alexandria #:mean #:variance #:median))

This is what the top-level ls-user package does.

Resources

This system is part of the Lisp-Stat project; that should be your first stop for information. Also see the resources and community pages for more information.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. Please see CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests.

License

Distributed under the MS-PL License. See LICENSE for more information.

Contact

Project Link: https://github.com/lisp-stat/numerical-utilities