Nifty is a general-purpose numerical computing library for the Swift programming language, made with performance and ease-of-use in mind.
Not sure if Nifty is what you're looking for? Check out a simple demo project or peruse the documentation to help you decide.
There are a number of options when it comes to getting up and running with Nifty. In order of easiness:
- Pull down the Docker image
- Use the included project file in Xcode
- Install with the Swift Package Manager
Nifty is being developed on Ubuntu and macOS; whatever route you go, make sure your version is up to date. Also, our goal is to stay current as Swift develops, so make sure to install the latest release.
The niftyswift/nifty repo on Docker Hub comes with Swift and all the libraries installed! It even has a base project already set up, so you can just start coding with Nifty.
If you don't have Docker set up already, go here.
Once Docker is set up, the remaining steps are easy:
- Pull down the image and start the container:
docker run -it niftyswift/nifty– this will start a shell inside the container, within a preconfigured project folder - Open an editor and start writing code (e.g.
vi main.swift) - Execute
swift run– this will pull down the Nifty library code, compile your code, and run your executable (e.g..build/debug/myapp)
If you've already got a project on your host machine, you can mount it when you start the container and edit locally, e.g. docker run -v /home/myapp:/myapp -it niftyswift/nifty
Xcode users can just use the included project file. Simply drag the project file into your own Xcode project, add Nifty to your target's dependencies, and import Nifty at the top of any files in which you wish to use Nifty!
Nifty uses BLAS and LAPACK. When built with Xcode, these are provided by the Accelerate framework. Since Accelerate is installed on macOS by default, no additional installation steps are needed.
Linux users (and those on macOS who prefer not to use Xcode) can install Nifty using the Swift Package Manager.
Nifty uses BLAS and LAPACK. When built with the Swift Package Manager, Nifty uses the C interface LAPACKE and the optimized library OpenBLAS. These can be installed with the following commands:
- Ubuntu:
sudo apt-get install liblapack3 liblapacke liblapacke-dev libopenblas-base libopenblas-dev - Mac:
brew install homebrew/dupes/lapack homebrew/science/openblas
Once the dependencies are installed, using Nifty in your project simply requires that you create/modify your project manifest file to point to this repository as a dependency, and then import Nifty in whatever files you want to use it. Your project can then be built by simply running swift build.
Refer to the aforementioned demo project to see an example of what your project manifest (the file called Package.swift) should look like and how easy it is to use Nifty!
Nifty is intended to be simple and easy to use. For this reason, we've decided to structure things similarly to MATLAB. In fact, many of the function names in Nifty are the same as MATLAB. The hope is that MATLAB users will feel right at home and that users of similar packages (e.g. NumPy) will have an easy transition as well, making adoption as smooth as possible for as many people as possible. Check out the API!
If you're having troubles, you may find the following helpful:
The system libraries used by Nifty are provided by the Nifty-libs package. This is used internally by Nifty so you shouldn't ever need to reference it. One complication that can arise though is if the installed system libraries are in a location not on your linker search path. In that case, you'll need to tell the linker where to find them when you build, e.g. swift build -Xlinker -L/usr/local/opt/lapack/lib -Xlinker -L/usr/local/opt/openblas/lib.
If you decide to use a different system library for one of the required system modules, you'll need to modify the Nifty-libs module map once the package manager has downloaded the Packages folder.
If you're building with Xcode, you need to compile with NIFTY_XCODE_BUILD defined. Nifty uses different modules for Xcode builds and Swift Package Manager builds. The included project has this defined already, but if you build your own project, you'll need to do this (It used to be in the project settings -> "Build Settings" -> "Other Swift flags", where you would add -DNIFTY_XCODE_BUILD; somewhere around Xcode 9/Swift 4, a setting called "Active Compilation Conditions" was introduced, which should be set to include NIFTY_XCODE_BUILD).
Some users have had problems with the included Xcode project giving the errors: "Undefined OBJROOT" or "Undefined SYMROOT". One possible fix: From the project navigation side bar, click on the project icon to bring up the project settings. SYMROOT (aka Build Products Path) and OBJROOT (aka Intermediate Build Files Path) can be set in the Build Settings tab. From the Build Settings tab, search for SYMROOT or OBJROOT. It should bring up Build Products Path or Intermediate Build Files Path (if not, make sure the search bar is set to search "All", not just "Basic"). From there, you can set the paths as you wish (a reasonable default is $SRCROOT/build). For more info, lookup Apple's "Xcode Build System Guide - Build Setting Reference."
Nifty is new and obviously not complete. The library is constantly expanding—if it doesn't yet have what you need, it will soon! Either come back later and check Nifty out when it's a little farther along or consider contributing!
We are currently working on getting the core set of general math and linear algebra functions finished:
- general functions and definitions used throughout Nifty
- matrix definition and linear algebra functionality
- vector and tensor data structures
- wrappers on glibc/math.h
- basic functions related to statistics and probability
See our status page for details on the implementation status of all features, as well as plans for the future.
Nifty uses the XCTest framework to manage unit tests. Tests can be run directly from Xcode or, if not using Xcode, by executing swift test in the repository root directory.
The goal is for Nifty to provide correctness and performance similar to other numerical computing standards. We'll be testing and benchmarking mainly against MATLAB and NumPy. Check out the status page to see where the test coverage is currently at. You can also check out the results of some simple benchmarks here.
The goals of Nifty can be summarized as follows:
- Provide a viable alternative to packages such as NumPy and MATLAB for those who wish to develop in Swift, whether on macOS or Linux.
- Develop fun and interesting code and algorithms.
- Do as much in Swift as feasible.
- Make exploration of the code as simple as possible.
- Serve as a learning opportunity for those wishing to explore numerical computing.
Nifty is intended to be broad in scope; almost any generally interesting/useful tool related to numerical or scientific computing, data structures, algorithms, etc. is fair game. However, we will prioritize the core functionality as outlined on the status page.
All contributions are welcome—whether suggestions, submissions, requests, or whatever! If you think of a nifty feature we ought to have, let us know. If you'd like to contribute, but aren't sure exactly what, visit the status page for ideas—a lot of things that wouldn't require a great deal of time or expertise remain unimplemented or untested!
To contribute code to this project:
- Fork it!
- Create your feature branch:
git checkout -b my-new-feature - Check out the style guide
- Consider including a test, even if it's super basic
- Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Open a pull request!
For anything else, feel free to open an issue!
We're also on Slack. If you want to join the conversation, let us know.
This project is licensed under the Apache License, Version 2.0, a complete copy of which can found in LICENSE, adjacent to this file.