e9539855

Quick start

{% include_relative install_snippet.md %}

{% include_relative api_key_note.md %}

About

FØCAL is a suite of tools that enable agile software development on specialized compute hardware including GPUs, SBCs, SOCs, and AI co-processors.

Why? Software people – applications architects, developers, data scientists – are demanding more and more of the underlying hardware. FØCAL helps them:

  • Get on-demand access to the latest compute devices.

  • Benchmark their code on lots of hardware/OS combinations all at once.

  • Get key insights into which hardware works best and why.

  • Eliminate the guesswork in hardware acceleration.

How? FØCAL is three things:

  • f0cal/farm – For spinning devices up on our device farm. {% include_relative key.md %}

  • f0cal/my-device – For managing your own fleet of devices.

  • f0cal/my-code – For instrumenting your code and tracking how it performs on different hardware.

Concepts

Each repo above implements a Python package in the f0cal namespace. Each Python package, in turn, implements a command line interface (CLI) for running key workflows. Our packages are installable via pip, making it easy to get started quickly. Throughout, we assume use of python3 and virtual environements according to current best-practices.

SOV

Each f0cal CLI uses a simple “subject-object-verb” (SOV) model to expose its workflows. All commands take the form

f0cal {subject} {object} {verb} {object-ref} [...]

where

  • {subject} maps to the package name, as in my-device.

  • {object} is a noun defined by the package.

  • {verb} is semantically sensible for the object noun, and either CRUD or a “special” action. (See below.)

  • {object-ref} is a user-defined reference to an {object}

  • [...] represents additional arguments, if any.

Example:

f0cal farm instance start my_pi

CRUD

Every object noun has basic CRUD verb semantics:

f0cal farm instance create my_pi [...]
f0cal farm instance retrieve my_pi [...]
f0cal farm instance update my_pi [...] 
f0cal farm instance destroy my_pi [...]

Special verbs

Many object nouns also have special verbs that enable key workflows, for example:

f0cal farm instance start [...]
f0cal farm instance stop [...]

More information can be found by running --help at any level of the f0cal CLI.

Extended style

The f0cal CLI tries to maintain a consistent style beyond SOV and CRUD. Some of our style guidelines include:

  1. {object-ref} must be the only “naked” argument on the CLI.

  2. All additional arguments must be of the form --arg-type={arg}, even required arguments. Shorteners like -a {arg} are allowed.

  3. When applying shorteners, arguments that refer to other {object} nouns should be given priority.

  4. An end-of-args sentinel (a lone --) should be used when arguments will be passed, verbatim, to another command.

For those who prefer a less verbose set of workflows:

pip install f0cal.f0 \
  --index-url https://pkg.f0cal.com/py

Authentication

Some of FØCAL’s features are only available via our web API. In order to authenticate with the API, you’ll need an API key. API keys are available from our key manager app.

Throughout our docs, the key icon ({% include_relative key.md %}) will be used to highlight features that require an API key.