Swift for TensorFlow

Disclaimer

Note: Swift for TensorFlow is an early stage research project. It has been released to enable open source development and is not yet ready for general use by machine learning developers.

Architecture

Projects built with this template will have the following traits:

Build output is a deployable Docker image with an entrypoint to a release-built executable

Quick and easy REPL access against the project's Swift for Tensorflow code and third-party libraries

Easily unit testable

Runs anywhere Docker is available with no additional setup necessary - zero conflicts with existing Swift or TensorFlow installations.

Swift code is hot-reloaded on change; third-party libraries are downloaded automatically as well. See the --live flag.

This will enable both ease of use during the research phase and a rapid transition to a scalable training solution and beyond (production deployment).

Docker

The project is fully Dockerized via the swift-tensorflow image, meaning you don't need to worry about setting up local dependencies or conflicts with existing Xcode/Swift installations when developing Swift+TF applications unless you really want to - all build/run tasks can be accomplished from within the container.

More information on the base docker image and avanced usage examples can be found in its README.

Note: The initial Docker build may take some time; Docker needs to download intermediate layers for the Ubuntu16 image if you haven't used it previously. However, subsequent builds should complete in under 10 seconds on a reasonable machine.*

Clone the swift-tensorflow-starter Repository

Optionally, you may reset git so you can commit and push to your own repository:

rm -rf .git
git init && git commit -am "initial"

The Easy Way

Users on macOS and Linux can take advantage of the supplied run script for easy usage - no Docker expertise required!

1) Build and Run with Hot Reload enabled

After cloning, you can start the project in a single command using the sts executable that's included:

./sts run app --build --live

After this, any changes you make to the project will result in the Swift code being rebuilt in the container and the executable started. You can exit with CTRL+C.

2) Add your Swift TensorFlow code

Add your Swift source files to the to Sources/STSLibary directory

If you'd like them to be part of the runnable application, add the appropriate calls to the run() method of Application.swift. Assuming you wire up valid code, you'll see your output.

If you'd rather just run the REPL, CTRL-C out of this session and run ./sts run repl --build

That's it! However, it's recommended to continue reading and learn more about the underlying Docker container.

The Other Way

The following 4 steps describe how to add your code, build, and run the project with nothing other than the Docker binary; this should be relatively accurate cross-platform.

1) Add your Swift TensorFlow code

Add your Swift source files to the to Sources/STSLibary directory

If you'd like them to be part of the runnable application, add the appropriate calls to the run() method of Application.swift. If you only want to access this code from the REPL, no further work is required now.

2) Build

Debug:

docker build -t sts-application .

Release:

docker build --build-arg CONFIG=release -t sts-application .

Note: you may tag your built container as anything you'd like; if you use a different tag, be sure to use it instead of sts-application in the following bash commands.

./sts run repl --build --name myrepl -v - run a REPL in a container named myrepl, mounting the current directory as a volume, building the project first

./sts run test, ./sts run tests --name testcontainer - run unit tests

./sts run xcode - generate and opens a new xcode project

./sts run app -b - run the application, building the container first

./sts run app -v - runs an app tagged myapp with the current directory mounted as a volume to /usr/src.

./sts run app -n mycontainer -b - build and tag the current image mycontainer and then run it.

NOTE: if you don't include the -b|--build flag to app run then the previously built image with that tag/name will be started. If an image with this tag is not found, one will be built.

Usage

Writing TensorFlow Code

Something to keep in mind when writing your TensorFlow code, as to avoid issues with send/receive (from the official FAQ):

We recommend separating functions that do tensor computation from host code in your programs. Those functions should be marked as @inline(never) (and have public access, to be safe). Within those functions, tensor computation should not be interrupted by host code. This ensures that the arguments and results of the extracted tensor program will be values on the host, as expected.

SwiftPM Project Settings

By default the following names are used:

Executable: STSApplication

Library: STSLibrary

SwiftPM project: STSProject

If desired, you can easily override these values with a simple find/replace in the root directory. The files which need changes are Package.swift and the Dockerfile, the example test classes and run scripts, and a few directory names in Sources and Tests.

Third-party Libraries

Third-party Swift libraries can be added to the dependencies collection in Package.swift and then imported for use.

System Dependencies

The project's Dockerfile is based on Ubuntu 16, so you can simply add RUN apt-get install -y ... entries to fetch additional dependencies.

Writing Unit Tests

See STSLibraryTests.testApplicationPrefix() in Tests/STSLibraryTests/STSLibraryTests.swift for an example test.

Note: TensorFlow is not yet supported in Unit Tests.

Generate .xcodeproj

If desired, users on macOS can generate a .xcodeproj that you can open with an IDE (Xcode, AppCode, CLion). This is optional, and the xcodeproj is ignored in .gitignore by default. Also note that you'll want to swap out your xctoolchain as described here if you go this route.

The following command mounts a volume in the current directory and generates the project, resulting in the file being written to your host's disk.