Frequently asked questions

SushiStack is the applications, and the workspace that holds them. SushiHub is the tool that installs and manages them: the hub terminal command, a desktop application that gives each hub command a screen, and the repository that carries both.

hub is published on PyPI as sushihub. It provisions the toolchains and libraries the modules need into one dependencies/ directory and manages the module checkouts beside it. The glossary fixes the other words the manual uses.

The catalog names four modules. Each has its own CLI, which builds, tests and runs it.

Module	Its CLI
sushiruntime	sr
sushiblas	sb
sushiai	sa
sushiengine	se

sushiblas depends on sushiruntime, and sushiai depends on both. Each module’s CMake looks first for an installed package and then for a sibling checkout next to itself, such as ../sushiruntime, which is why every module sits directly under the workspace root. See The workspace.

sushicore is not a module. It is the Python engine under hub and every module CLI, it is never built, and it installs from PyPI. sushidsp and sushitrack left the stack on 2026-09-22: they are their own products with their own CLIs, sd and st, and hub add sushidsp reports an unknown module.

Run the installer. It puts Python and Git in place if they are missing, installs hub from PyPI with pipx, and runs hub init and hub install in the directory you choose. Setting SUSHISTACK_DIR names that directory and skips the prompt.

curl -fsSL https://sushisystems.io/install.sh | bash      # Linux / WSL

irm https://sushisystems.io/install.ps1 | iex             # Windows (PowerShell)

The installer clones no module unless you pass a list: install.sh --add "sushiruntime sushiblas" or install.ps1 -Add "sushiruntime sushiblas". Afterwards hub add all clones every module, installs each one’s CLI and provisions what they declare. Installing gives the same steps one command at a time, starting from pipx install sushihub.

The manual gives two installer scripts: install.sh for Linux and WSL, and install.ps1 for Windows PowerShell. It names no other operating system.

On Windows use irm, not curl. In PowerShell curl is an alias for Invoke-WebRequest and does not pipe a script the same way. See Installing.

A workspace is any directory hub init has marked. hub init writes the .sushistack directory, which holds workspace.toml, and adds dependencies/ to .gitignore. An empty folder is enough; a workspace does not have to be a clone of the SushiHub repository.

<workspace>/
  .sushistack/workspace.toml   written by `hub init`
  dependencies/                filled by `hub install`
  sushiruntime/                added by `hub add sushiruntime`
  sushiblas/                   added by `hub add sushiblas`

Every hub and module CLI walks up from the current directory to .sushistack and derives dependencies/ from it. hub home prints the workspace root and the dependencies/ path. The workspace describes the layout, and the hub README lists every file hub reads and writes.

What the modules in the workspace need to build, into <workspace>/dependencies: toolchains, vcpkg, and portable cmake and ninja. In an empty workspace that is the base fragment alone: cmake, ninja, gtest, opencl and pkgconf. A toolchain arrives with the module that requires it, so hub add sushiruntime is what brings a SYCL toolchain.

sushiruntime declares three toolchains that provide the same capability: intel/llvm, AdaptiveCpp and oneAPI. One is enough to build. When the machine already holds one, hub install downloads none; otherwise it installs intel/llvm, the first the fragment declares. hub install --customize adds the others.

hub install also detects the machine’s GPU and installs that vendor’s toolkit without being asked; on Windows the CUDA installer asks once for administrator rights. hub install --dry-run is available, and --customize drops the GPU toolkit. See Installing.

No. A module CLI provisions its own checkout with setup and reports on it with doctor, through the same sushicore code hub install runs. A module checked out on its own, with no .sushistack marker above it, falls back to a dependency tree of its own.

hub does that for several checkouts at once and fetches the engine’s binary. It builds one thing itself, the desktop application, through hub gui build. Building, testing and running a module belong to that module’s CLI, for example cd sushiruntime && sr build.

hub add <module> brings a module into the workspace, installs its CLI and provisions what it declares. It takes sushiruntime, sushiengine, sushiai, sushiblas, their aliases sr, se, sa, sb, or all. --skip-install leaves the dependencies to a later hub install.

If the checkout already exists elsewhere on the machine, register it instead of cloning a second copy:

hub link sushiruntime D:/Projects/sushiruntime
hub install-cli sushiruntime            # point `sr` at that checkout

hub link writes the name and path into [modules] in .sushistack/workspace.toml. From then on hub status, hub update, hub sync and hub install treat the linked checkout like a cloned one. A checkout that carries sushi-module.toml is recognised without a catalog entry, so hub link sushidsp <path> works, but a name only a manifest knows cannot be added with hub add. See Linking checkouts and the module manifest.

sushiengine is sold; the other three modules are not. hub add sushiengine first asks the private repository whether this machine’s Git identity reaches it. If it does, the module is cloned like any other. If it does not, hub needs a Sushi Account session: with one it downloads the release, and without one it names both ways in and stops. hub add sushiengine --binary goes straight to the release.

hub login opens the session. It prints a device code, opens the Sushi Account page in the browser, waits for you to approve it there, and stores the session in the operating system’s credential store. hub license then prints one row per product licence on the account.

A release brings its own sushiruntime and sushiblas, so nothing is provisioned after it and no SYCL toolchain is downloaded; se arrives inside the package. hub writes the product licence token beside it as sushi-licence.jwt, which the engine reads at start-up and verifies offline. The detail is under “Signing in” and “Binary installs” in the hub README.

The source in the SushiHub repository is source-available under the PolyForm Noncommercial License 1.0.0, free for non-commercial use. LICENSE is the binding text and lists the permitted purposes: personal, non-commercial use, and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. COMMERCIAL.md says how to ask: write to hello@sushisystems.io with what you want to build and who will use it. sushihub 0.1.0 on PyPI and the commits before the one that replaced LICENSE were published under the Apache License 2.0 and stay available under it.

This is the licence of the source. The licence hub license reports is a different thing: the product licence Sushi Account issues for sushiengine.

Known issues lists the open defects with the file each sits in. The ones a new user meets first:

• v0.2.0 has its release commit of 2026-10-07 and no tag, so it is not published; PyPI serves 0.1.0. The changelog lists hub migrate under Unreleased.
• hub gui build, test, run and clean are listed for every user and work only when the workspace root is a clone of the SushiHub repository. An install made with the installer never clones it, so there is no desktop application in that install until you run git clone https://github.com/SushiSystems/SushiHub.git.
• There is no hub unlink. To undo a link, remove the line from [modules] in .sushistack/workspace.toml and run hub install-cli <module> again.
• Under hub --json, git and pipx write plain text into the event stream.
• After a vcpkg port’s feature set changes, hub install fails at the vcpkg step, because it cannot pass --recurse. The same page gives the command to run by hand.

Not yet. Contributing says contributions from outside Sushi Systems are not accepted.

Cloning the repository is still how you work on hub or get the desktop application’s source. After the clone, python cli/install.py points the hub command at your checkout instead of the published package.

SushiCore is the shared core of the Sushi developer CLIs. It is one Python package, sushicore, and seven CLIs import it: hub, sr, se, sa, sb, sd and st. They use it to locate a workspace, load layered TOML configuration, print to a terminal or to a JSON stream, draw their help screens, drive cmake and ctest, and install and check what a repository needs to build.

It is a library for those CLIs. It installs no console script, and it registers commands on their Typer applications without having an application of its own. It knows nothing about SYCL, a renderer, or any one module’s schema. The architecture overview lists what each module of the package owns.

SushiCore is published on PyPI as sushicore.

pip install sushicore            # workspace, configuration, console, cmake driver
pip install "sushicore[typer]"   # the same, plus Typer

Typer is an optional extra. A CLI that uses help_group, the root options, the diagnostic commands or the provisioning commands needs it; import sushicore alone does not. All seven Sushi CLIs require sushicore>=0.7.0.

To work from a checkout, clone https://github.com/SushiSystems/SushiCore and run pip install -e ".[typer]" in it. A CLI installed with pipx has its own environment, so the checkout goes into that environment with pipx inject --editable <cli-package> /path/to/SushiCore. Installing also covers the tests and the checkers.

SushiCore needs Python 3.10 or later. CI runs the test suite on Ubuntu and Windows with Python 3.10 and 3.11. The checkers under tools/ need Python 3.11.

A platform override table in a config file is named after platform.system() in lower case: windows, linux or darwin. A dependency fragment pins download digests for two platforms, windows and linux. See Installing, Configuration and Dependency fragment.

The CLI is a Typer application and installs SushiCore with the typer extra. It builds its console through LazyConsole on first use, not at import, so that --help runs outside a checkout. It passes help_group as the class of its Typer application and of every add_typer sub-application. Its console script names a main function that hands the application to sushicore.entry.run, which turns a SushiCoreError into one line and exit code 1.

Every Sushi CLI then registers the same surfaces, each with one call:

• register_root_options gives --version and --describe, the command catalogue as JSON.
• register_diagnostic_commands gives config and env.
• register_provision_commands gives setup, doctor, link and unlink.
• AliasTable keeps old command spellings running, hidden, and names their replacement.

build, test, run and clean stay in each CLI. CLI integration has the code for each step.

A CLI hands SushiCore its config files, by convention cli/config.toml and cli/config.local.toml in the repository the CLI builds. The second is machine-local and not committed. Appearance comes from the [cli] table only: theme, icons, color and background. From lowest to highest precedence:

1. The built-in preset.
2. Each config file in the order given, so config.local.toml wins over config.toml.
3. SUSHI_CLI_THEME, SUSHI_CLI_ICONS, SUSHI_CLI_COLOR and SUSHI_CLI_BACKGROUND.
4. NO_COLOR, which forces color = "never" whenever it is set.

The same files can hold the [tool] build configuration. A [tool] table is merged with its [tool.<platform>] override, and a <PREFIX>_<TOOL> environment variable such as SR_CMAKE then overrides one tool path of one CLI. Configuration lists every key and variable, and what a bad value does.

The dependency root is the one folder per machine that holds installed toolchains and tools. It is the folder SUSHISYSTEMS_HOME names, and ~/.sushisystems when that variable is unset. registry.toml in it records what is installed and which modules use it.

New installs go to the dependency root. Toolchains and vcpkg are looked up there first, then in the folder SUSHISTACK_DEPS_DIR names and in a legacy <workspace>/dependencies tree; a legacy tree is read and never written. sushicore/provision/README.md describes the root and how it is moved to another directory.

setup installs what a module needs to build and then runs doctor. It reads the module’s dependency fragment, cli/sushistack.deps.toml by default, and through [module] depends_on the fragment of every module it builds on. It never clones. --dry-run shows the run and changes nothing, --toolchain NAME also installs that toolchain, and --no-gpu skips the GPU toolkit.

doctor is a read-only report. It checks the build tools, the checkouts of the modules this one builds on, the toolchain capabilities, the fragments, the toolchain stamps and the download digests, then the module’s own checks. --for GROUP restricts the report to one group: build, test, infer or eval. It exits with code 1 when a required check fails.

No module needs hub installed to use either command. The options and exit codes are in sushicore/provision/README.md.

link records a module in a workspace’s [modules] table and writes a [link] workspace pointer into the module’s cli/config.local.toml. unlink removes both. A workspace is a folder holding .sushistack/workspace.toml, which records the modules linked to it and the tools they share.

Linking copies nothing. Config loading follows the pointer and layers the linked workspace’s [tool] table at read time. SUSHISTACK_HOME wins over the pointer, and a pointer to a deleted workspace is ignored. The workspace link uses is --workspace PATH, else SUSHISTACK_HOME, else the first folder above the project root that holds .sushistack. See sushicore/provision/README.md.

In machine mode a console writes one JSON object per line to stdout, in UTF-8, for a program to read. The SushiHub desktop application is the reader it was designed for. The event kinds are line, command, header, panel, table, progress, result and prompt, and event is always the first key:

{"event": "line", "level": "info", "message": "..."}
{"event": "result", "ok": true, "payload": {}}

A CLI turns the stream on with build_console(paths, machine=True), or by setting LazyConsole.machine = True while it parses its command line. Of the seven CLIs only hub offers the stream, as --json. A prompt event is answered by one line on stdin. JSON events gives the fields of every event.

SushiCore is source-available. It is free for non-commercial use under the PolyForm Noncommercial License 1.0.0, and LICENSE is the binding text. The permitted purposes it lists are personal, non-commercial use and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. COMMERCIAL.md says how to ask for one: write to hello@sushisystems.io with what you want to build and who will use it.

Versions 0.1.0 to 0.4.0 were published under the Apache License 2.0 and stay available under it; 0.7.0 is the first version under the licence above. The README gives the commit boundary, and NOTICE.md lists the third-party software.

Known issues records the open defects. Those a user of a CLI meets first:

• With the emoji, minimal or none icon set, every warning and error in the JSON stream is reported with level info.
• A child process inherits stdout, so in machine mode stdout carries more than events.
• setup, link and unlink end without a result event, and config and env emit no table or prompt event.
• No fragment entry pins a sha256 yet, so every download is extracted or run unverified, with a warning. Downloads inside a shell pipeline and git clones are not verified at all.
• The CUDA installer runs silently, the oneAPI installer runs with --eula accept, and winget runs with --accept-package-agreements, each on the user’s behalf.
• link --workspace PATH does not check the path for the workspace marker and creates .sushistack/workspace.toml there.

The limits of the help screen are in sushicore/help/README.md.

Contributions from outside Sushi Systems are not accepted yet. The README states this beside the licence.

SushiRuntime is a C++17 runtime library for task-based parallel computing on CPUs and GPUs through SYCL. You describe work as a graph of tasks and declare which memory each task reads and writes. The runtime detects the read-after-write, write-after-read and write-after-write hazards between tasks, orders only the tasks that conflict, and runs the rest in parallel on the devices it discovers.

The entry point is the fluent API under include/SushiRuntime/api/. You allocate data as Buffer<T> or State<T> handles, add work with Graph::add(), and call run(). The graph compiles on its first run and the compiled plan is replayed for every later step. The introduction has complete programs, and the architecture describes the layers underneath.

The README lists the requirements:

• a SYCL 2020 compiler, one of the three toolchains named below
• CMake 3.20 or newer, and 3.25 or newer for the Intel oneAPI toolchain
• hwloc, for topology discovery
• GoogleTest, for the test suite
• a C++17 standard library

sr setup installs the C++ libraries and the SYCL toolchain that cli/sushistack.deps.toml declares into ~/.sushisystems, and writes the paths it found to cli/config.local.toml. sr doctor then reports whether the machine is ready to build, and each failed row names the command that fixes it. Both commands are covered in the CLI guide.

Install the sr CLI, pick a toolchain, then build and test:

hub install-cli sushiruntime
sr toolchain intel-llvm
sr build
sr test

hub install-cli comes from SushiStack. Without it, pipx install ./cli installs the same package from this checkout. sr build makes a release build by default, and --type accepts debug, relwithdebinfo and asan. sr test runs the functional suite by default, and --suite selects benchmark, package, all or one of the finer labels. The CLI guide lists every command and flag.

Yes to both. The CLI only runs CMake and CTest for you, and the “Building with CMake directly” section of the README gives the configure line and the presets intel-llvm, adaptivecpp and oneapi. SR_BUILD_TESTS is OFF in a direct CMake build, so pass -DSR_BUILD_TESTS=ON if you want test binaries.

The repository also carries a Dockerfile with an intel/llvm nightly SYCL bundle and the Intel OpenCL CPU runtime. sr container build builds the image and sr container run starts it with the repository mounted. GPU passthrough needs the NVIDIA Container Toolkit on the host.

Three SYCL toolchains, selected with sr toolchain or the CMake option SR_SYCL_TOOLCHAIN:

• intel-llvm (clang++ -fsycl from the intel/llvm nightly bundle): the primary toolchain, the default, and the one the Docker image uses
• AdaptiveCpp (acpp): the secondary toolchain
• Intel oneAPI DPC++ (icpx on Linux, icx-cl on Windows): supported, and kept for the Intel profiling tools

The GPU backend comes from -DSR_GPU_BACKEND, which takes auto, cuda, rocm, intel, cpu or none. The default auto detects the installed GPU toolkit and otherwise builds the portable CPU/OpenCL path. sr build --no-cuda builds that CPU/OpenCL path directly. The build-time options are in §14 of the architecture.

Install the built tree to a prefix, point CMAKE_PREFIX_PATH at it, and link the exported target:

find_package(SushiRuntime REQUIRED)
target_link_libraries(my_simulation PRIVATE SushiRuntime::SushiRuntime)

The runtime’s kernels are header templates, so they are compiled in your translation units and not in the library. Every translation unit of yours that touches the graph API must therefore be compiled by a SYCL compiler, and the headers and the library must come from the same release. SushiRuntime::version_matches() checks the second at start-up.

The package uses SameMinorVersion compatibility while the project is before 1.0: find_package(SushiRuntime 0.3 REQUIRED) accepts 0.3.x and rejects 0.4.0. tests/package/ in the repository is a working consumer. The integration guide covers the build split, the flags you inherit and the troubleshooting cases.

For a fixed graph topology the runtime guarantees schedule-independent results: the same inputs give the same outputs however the work was spread across workers. Replay with the same binary on the same device is byte-equal. Equality across architectures is not claimed.

The guarantee depends on floating-point settings. SR_DETERMINISTIC_FP is ON by default and forbids fast-math and FMA contraction in the runtime’s translation units and, through the installed package, in yours. Kernels in a translation unit you build with -ffast-math or /fp:fast are outside the guarantee. The rebalancer is off by default, and turning it on trades run-to-run reproducibility for throughput on long batch work. See the integration guide for the flags and the introduction for add_reduce, which folds fixed 256-element tiles so a reduction gives the same bits at any worker count.

Yes, through an optional master-worker layer that offloads individual tasks to remote workers over TCP, without MPI. It is off by default. sr build --distributed or -DSR_ENABLE_DISTRIBUTED=ON turns it on, and with it off none of the distributed code is compiled.

Compiled code does not cross the network. A task ships an OpID that names a kernel already compiled into every worker binary, plus buffer handles that each worker resolves to its own memory, so every node runs the same binary. A task the policy declines runs its local fallback on the master. A task whose worker dies is sent to a surviving worker, or runs locally when none remains. The distributed guide has the demo, the wire protocol and the failure model.

SushiStack provisions several checkouts at once, and its command line is hub. hub install fetches every toolchain and library the modules of a workspace declare, and SushiRuntime declares its own in cli/sushistack.deps.toml. hub install-cli sushiruntime installs the sr CLI. sr link and sr unlink record this checkout in a workspace’s module registry or remove it.

sushicore is the Python package the sr CLI takes its shared commands and help page from: setup, doctor, link and unlink come from it and work the same in every module CLI. SushiRuntime does not need a workspace. With only this checkout, install the CLI and run sr setup. See the CLI guide.

SushiRuntime is before 1.0. The API is not frozen, a minor version may break a consumer, and security fixes go to the latest main with no long-term support branch. The limits the manual states today:

• A kernel runs in one device context. A task whose buffers sit on different devices fails the run with an invalid_graph error, and execution across devices is deferred.
• The distributed layer has no master failover, keeps nothing between runs, and needs the same binary, architecture and endianness on every node.
• The TCP transport has no encryption and no authentication. It is meant for a trusted LAN.
• A distributed worker that drops mid-run cannot rejoin.

Known issues lists the recorded defects that are not yet fixed, and §12 of the distributed guide lists that layer’s v1 limits.

SushiRuntime is source-available and free for non-commercial use under the PolyForm Noncommercial License 1.0.0. LICENSE is the binding text and lists the permitted purposes: personal, non-commercial use, and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. COMMERCIAL.md says how to ask: write to hello@sushisystems.io with what you want to build and who will use it. Third-party components keep their own licences, listed in NOTICE.md.

Check known issues first. For anything that is not sensitive, open a GitHub issue or Discussion.

Do not open a public issue for a security problem. Email mustafagarip@sushisystems.io, or use GitHub’s private vulnerability reporting under the repository’s Security tab. The security policy promises an acknowledgement within 72 hours and an initial assessment within 7 days. It asks for the affected component, the version or commit hash, reproduction steps, and the platform, toolchain and build configuration.

SushiBLAS is a C++17 tensor and BLAS library built on SushiRuntime’s task graph. You create tensors and queue operations on them through an Engine; the runtime tracks the dependencies between the queued tasks and runs them on a CPU or a GPU through SYCL. No kernel calls a vendor math library: there is no oneMKL and no cuBLAS behind it.

Operations are recorded, then run. A call such as engine.blas().gemm(A, B, C) registers a task and runs nothing; engine.execute() compiles and runs the graph. Engine has eight accessors: blas(), elementwise(), nonlinear(), logic(), reductions(), random(), spatial() and io(). The root README has a complete example, and the architecture describes each layer.

The README’s requirements list five things:

• A SYCL 2020 compiler: the intel-llvm clang++ -fsycl that sb setup or SushiStack provisions.
• CMake 3.20 or newer, and 3.22 for the test suite.
• GoogleTest for the test suite.
• A SushiRuntime checkout or installed package.
• C++17 or later. The library is built at C++17; a C++20 consumer is supported.

SushiBLAS selects no toolchain of its own. It builds with the one in the workspace dependencies/ tree or under ~/.sushisystems.

SushiStack’s bootstrap script installs Python and Git, installs hub, then runs hub install to fetch every toolchain and library the workspace’s modules declare. SushiBLAS declares its own in cli/sushistack.deps.toml.

curl -fsSL https://sushisystems.io/install.sh | bash

On Windows, run irm https://sushisystems.io/install.ps1 | iex in PowerShell. In PowerShell curl is an alias for Invoke-WebRequest and does not pipe a script the same way.

To use an existing checkout of the repository, link it into a workspace with hub link. hub doctor and hub status show what is installed. See the README’s quick start.

Install the CLI through hub, run sb setup once before the first build, then build and test:

hub install-cli sushiblas
sb setup
sb build
sb test

hub install-cli sushiblas puts two equivalent commands on the PATH, sb and sushiblas. sb build makes a release build by default; --type debug and --type relwithdebinfo select the others, and --clean wipes the build tree first. sb test runs the functional suite by default, and --suite selects unit, integration, regression, all or package.

Inside a SushiStack workspace, or with a SushiRuntime checkout beside this one, no local configuration is needed. The README also shows a build with CMake directly, and the CLI’s README describes every command.

Call find_package(SushiBLAS REQUIRED) and link SushiBLAS::sushiblas:

find_package(SushiBLAS REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE SushiBLAS::sushiblas)

CMAKE_PREFIX_PATH must name both install prefixes, SushiBLAS’s and SushiRuntime’s, unless both were installed to the same prefix. You must also supply the same SYCL compiler SushiBLAS was built with, C++17 or later, and SushiRuntime’s shared library on the loader path at run time. add_subdirectory(path/to/sushiblas) gives the same SushiBLAS::sushiblas target.

While the project is pre-1.0 the package uses SameMinorVersion compatibility: find_package(SushiBLAS 0.1 REQUIRED) accepts 0.1.x and rejects 0.2.0. tests/package/ in the repository is a complete consumer. The integration guide covers what a consumer inherits, what it must supply and how to read common build errors.

Yes. The kernels are compiled into the library, so your compiler never sees the GEMM kernel’s source and produces no device code for it. The public headers still include <sycl/sycl.hpp> and use sycl::event and sycl::device in their signatures, so every translation unit that includes <SushiBLAS/SushiBLAS.h> needs a compiler that can parse those types. Linking SushiBLAS::sushiblas carries -fsycl as a PUBLIC compile and link option for that reason.

A parse error inside <sycl/sycl.hpp> or <SushiBLAS/tensor.hpp> means the file is being compiled by a non-SYCL compiler. See section 1 of the integration guide.

By default the device image is SPIR-V, compiled by the runtime for the device it finds. That reaches every OpenCL and Level Zero device and no NVIDIA GPU, because NVIDIA’s OpenCL driver cannot ingest SPIR-V. For an NVIDIA GPU the CUDA image is compiled ahead of time:

sb build --type release -D SB_SYCL_TARGETS="spir64;nvidia_gpu_sm_86"

Keep spir64 in the list to keep the CPU device reachable from the same build. The compiler must be an intel-llvm built with --cuda; a stock oneAPI release has no CUDA backend and rejects the triple. intel-llvm documents support for sm_75 and newer.

None of the GPU path has run on hardware yet. See Targeting an NVIDIA GPU in the README.

SushiBLAS owns no execution engine, no scheduler and no memory pool; all three are SushiRuntime’s. SushiBLAS adds a domain layer on top: the Tensor abstraction, the Engine facade that turns method calls into graph tasks, and the kernels. It does not vendor SushiRuntime. The build looks for it in three places, in order: a target a superproject already brought in, an installed package through find_package(SushiRuntime), then a sibling ../sushiruntime checkout. Section 8 of the architecture describes the resolution.

SushiStack is the workspace: a folder that holds several module checkouts and one dependencies/ tree. Its CLI, hub, provisions the toolchains and libraries of a workspace. sb is this repository’s own CLI. The glossary defines these words.

• No release is tagged. The version in the build files is 0.1.0, and the project is pre-1.0.
• None of the GPU path has run on hardware.
• SparseBLAS is reachable through engine.blas(), but every method is a stub: there is no SparseTensor, no SpMV and no SpMM.
• LinalgOps (SVD, QR, eigendecomposition) and TransformsOps (FFT, DFT) are declared under include/SushiBLAS/experimental/ and are not exposed through Engine. There is no engine.linalg() or engine.signal() accessor.

Defects that are recorded and not yet fixed are in known issues. The changelog lists what has changed.

SushiBLAS is source-available, free for non-commercial use under the PolyForm Noncommercial License 1.0.0. LICENSE is the binding text and lists the permitted purposes.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. To ask for one, write to hello@sushisystems.io with what you want to build and who will use it; see COMMERCIAL.md.

The GEMM and SYRK tiling is ported from portBLAS and stays under Apache-2.0. NOTICE.md lists it with the other third-party parts.

For anything that is not sensitive, open a GitHub issue or Discussion.

Do not open a public issue for a security problem. Report it privately by email to mustafagarip@sushisystems.io, to the maintainer on the community Discord server, or through GitHub’s private vulnerability reporting under the repository’s Security tab. The security policy says what to include and what is in scope; it promises an acknowledgement within 72 hours and an initial assessment within 7 days. Security fixes go to the latest main, so test against the current main before reporting.

Conduct in project spaces is covered by the code of conduct, which names the same email address and Discord server for reports.

SushiAI is the AI/ML head of SushiStack: a C++17 library with a graph-native autograd core, a memory planner, a fusion pass and mixed-precision dtype plumbing. It traces a model once into its own graph IR, differentiates that IR into more IR, fuses it, plans every buffer’s address, lowers the result to a SushiRuntime TaskGraph once, compiles it once and replays it per batch. A regression test pins compile_count() == 1 however many batches run.

The tree today holds Linear, ReLU, GELU, Tanh and Sigmoid layers, Sequential, CrossEntropyLoss, the SGD and AdamW optimizers, a seeded synthetic dataset, an MNIST IDX loader, the SACP checkpoint format and the sa CLI. The root README lists each part with its header, and the tutorial walks from an empty checkout to a trained model.

SushiAI is built on SushiBLAS’s tensor and BLAS layer, and SushiBLAS runs on SushiRuntime’s task graph. SushiAI writes no SYCL: no file names a sycl:: type or submits to a queue, every compute call goes through SushiBLAS::Engine, and one file, src/graph/lowering.cpp, turns IR into those calls. The library target SushiAI::sushiai links SushiRuntime::SushiRuntime and SushiBLAS::sushiblas PUBLIC.

The glossary defines SushiStack as the set of repositories SushiRuntime, SushiBLAS, SushiEngine, SushiAI and the hub. hub is the workspace CLI that installs module CLIs and provisions several checkouts. The sa CLI is modelled on SushiEngine’s se and shares the stack’s bundled toolchain. Section 2 of the architecture page describes how the two dependencies are resolved.

The root README lists the requirements:

• A SYCL 2020 compiler: the bundled intel-llvm clang++ -fsycl, provisioned by SushiStack. SushiAI selects no SYCL toolchain of its own.
• CMake 3.20 or newer, and 3.22 for the test suite’s gtest_discover_tests.
• GoogleTest for the test suite.
• SushiRuntime and SushiBLAS checkouts, most often as siblings ../sushiruntime and ../sushiblas.
• C++17.

sa setup provisions the C++ library dependencies and the SYCL toolchain into the shared root, ~/.sushisystems or the directory SUSHISYSTEMS_HOME names. sa doctor reports whether the machine can build SushiAI.

Place the sushiruntime, sushiblas and sushiai checkouts side by side in one workspace, then run:

hub install-cli sushiai   # puts `sa` and `sushiai` on your PATH
sa setup                  # provisions the toolchain and writes cli/config.local.toml
sa build                  # release build, the default
sa test                   # unit, integration and regression suites

sa and sushiai are the same program. If a sibling checkout cannot be found, sa build stops and names which one and where it looked; sa config prints what the CLI resolved and where each value came from. sa build --type debug and sa build --type relwithdebinfo select the other build types, and -D VAR=VALUE passes a CMake cache variable through to the configure step.

The CLI guide covers every command. The root README also gives a one-script quick start and the plain CMake invocation for building without the CLI.

Run sa demo mlp after a build. It trains a two-layer MLP end to end and prints the compile count, the loss per epoch, the final accuracy and the wall clock. sa demo mlp --help prints the full flag list.

The demo trains on MNIST when the training split’s two IDX files are under data/mnist, or under the directory --mnist-dir names. Those files are not shipped and not downloaded, so without them the demo trains on a seeded synthetic classification problem and says so in its header and its result block. The tutorial explains each line of the output.

Install SushiAI to a prefix, then call find_package and link the exported target:

find_package(SushiAI REQUIRED)

add_executable(my_app main.cpp)
target_link_libraries(my_app PRIVATE SushiAI::sushiai)

You must supply the same SYCL compiler every library in the chain was built with, a CMAKE_PREFIX_PATH that names the install prefixes of SushiAI, SushiBLAS and SushiRuntime unless all three share one prefix, and SushiRuntime’s shared library on the loader path at run time. The SYCL requirement holds even for a translation unit that only calls SushiAI::version_string(), because linking SushiAI::sushiai brings in SushiBLAS’s -fsycl option.

add_subdirectory(path/to/sushiai) gives the same target; set SA_BUILD_TESTS=OFF before it to keep SushiAI’s suite out of your CTest run. tests/package/ in the repository is a working consumer. The integration guide holds the detail and a troubleshooting section.

C++17, the same standard SushiAI, SushiBLAS and SushiRuntime are built to. A later standard does not work for code that calls the library. SushiRuntime::span is std::span at C++20 and SushiRuntime’s own shim at C++17, and SushiAI exports out-of-line functions whose parameter type is that span, among them Autograd::differentiate, Core::allocate_tensor and Optim::StepScalars::write. A caller compiled at C++20 mangles those names differently and gets an unresolved external at link time. Train::build_classifier calls Autograd::differentiate for you, so the error can appear without a span in your own code.

The headers compile under C++20, and a translation unit that only builds or inspects a graph links under either standard. If the rest of your program must be C++20, section 3 of the integration guide describes putting the code that calls SushiAI in its own C++17 target, and states that this is a workaround and not a supported configuration.

Yes. sushiai train and sushiai inference read JSON:

sushiai train      examples/heavy_mlp/train.json
sushiai inference  examples/heavy_mlp/model.json \
                   examples/heavy_mlp/heavy_mlp.ckpt \
                   examples/heavy_mlp/eval.json

model.json describes the architecture, train.json the objective, data, optimizer, epochs and checkpoint, and eval.json the data to evaluate on. Each document leads with a version key. An unknown key or type is an error that lists what is accepted, and relative paths resolve against the configuration file’s own directory. The CLI guide shows both schemas.

A checkpoint written by a hand-written Sequential loads into a LayerStack built from the equivalent model.json, and the reverse.

Yes. --precision mixed runs the matrix products, and the bias and activation a fused GEMM folds into them, in fp16. The master weights, gradients, reductions and the optimizer update stay fp32. --loss-scale S adds gradient loss scaling: the backward seed is multiplied by S, which must be a power of two, every gradient is screened for infinities and NaNs, and the scale halves on overflow.

The documents make no speed claim for it. On the machine the README measured, which has no fp16 matrix unit, half arithmetic is emulated and the mixed run took 9364.9 ms against 2105.9 ms for fp32. Both runs ended at a loss of 0.000380 and 100% accuracy. A GELU layer is not folded into its GEMM under mixed precision. Section 5.3 of the architecture page gives the reasons.

The architecture page names the open work in its section 7: packing the lowering’s scratch, the log-softmax and NLL_LOSS fusions, the standalone LOG_SOFTMAX rule, the whole-step overflow skip, bfloat16, and the Dataset and Trainer seams among them. Known issues records what behaves wrongly or narrowly today:

• In mixed precision an overflowed gradient skips that parameter’s update only; the other parameters still step.
• Differentiating LOG_SOFTMAX on its own throws. It differentiates only as the fused LOG_SOFTMAX and NLL_LOSS pair.
• gradcheck cannot verify a mixed-precision graph. Check the rule in FLOAT64.
• NVIDIA Pascal GPUs (GTX 1060, compute capability 6.1) fail when the OpenCL loader ingests SPIR-V. The workaround is to set ONEAPI_DEVICE_SELECTOR to opencl:cpu.

SushiAI is source-available and free for non-commercial use under the PolyForm Noncommercial License 1.0.0. LICENSE is the binding text and lists the permitted purposes: personal, non-commercial use, and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. COMMERCIAL.md says how to ask for one: write to hello@sushisystems.io with what you want to build and who will use it. Third-party components are listed in NOTICE.md.

For anything that is not sensitive, open a GitHub issue or Discussion. Known issues lists the defects already recorded.

Do not open a public issue for a security problem. Report it privately by email to mustafagarip@sushisystems.io, through the community Discord, or with GitHub’s private vulnerability reporting under the repository’s Security tab. The security policy promises an acknowledgement within 72 hours and an initial assessment within 7 days, and asks that a security bug specific to SushiBLAS or SushiRuntime go to that repository.

SushiDSP is a C++17 library of guitar amplifier and pedal models. Each model solves its circuit sample by sample in real time, at 4x or 8x the host rate: the schematic’s own nodal equations, with the triode and pentode laws in the loop. No stage is a trained network, and no stage is fitted to a recording. The repository calls this a white box model.

A graph of IAudioNodes, the rig, chains the models in any order, the way a pedalboard does. The core depends on the C++17 standard library and SIMD intrinsics and on nothing else. Getting started introduces the library, and the glossary fixes the words the manual uses.

Six circuits. The amplifiers are the Marshall JCM800 2203, the Mesa/Boogie Mark IIC+ in lead mode, the Peavey 5150 (lead channel) and the Diezel VH4 (channel 3). The pedals are the Ibanez Tube Screamer and the Boss DD-3. Cabinet impulse-response convolution, a room model and the splitter, mixer and pan nodes that wire a rig together sit beside them.

Modules lists each module with the id it registers under, such as sushidsp.jcm800, and links to its README. That README says where each constant comes from and lists, in a stand-in table, every figure nobody has published. The manufacturer and product names say which circuit a model was written against; none of those companies is affiliated with SushiDSP, and NOTICE.md holds the trademark position.

• Windows or Linux.
• A C++17 compiler and CMake 3.20 or newer.
• Python 3.10, for sd, the repository’s CLI.
• sushicore 0.7.0 or newer. It is not on PyPI, so it is installed from its own checkout.

cli/sushistack.deps.toml lists what sd setup provisions beyond those. GoogleTest comes through CMake FetchContent, so nothing has to be installed for the test suite. Getting started has the first-run sequence.

Run these from the repository root:

python -m pip install -e <sushicore checkout>
python -m pip install -e ./cli
sd setup --dry-run   # report what is missing and what would be written
sd setup             # provision it and write the tool paths to cli/config.local.toml
sd doctor            # report whether this machine can build
sd build             # configure if needed, then build every target
sd test              # build if needed, then run the unit suite

Every build action goes through sd; cmake and ctest are not called by hand. sd also sets the runtime search path, so a binary started any other way will not find its libraries. The sd command line describes every subcommand and its flags.

sd host builds the tree if it is out of date, then starts sushidsp_host_gui. That application opens an audio device, builds a rig out of the registered products, draws their front panels, and records and plays back takes against a timeline.

sd host --type release chooses the build type, --no-run builds and stops there, and everything after -- reaches the host unchanged. The command exits 1 when the tree was configured with SUSHIDSP_BUILD_GUI=OFF. No cabinet impulse response ships in the checkout, so a fresh amplifier slot starts without one. The host’s README says what the host looks for at startup.

Windows and Linux, with a C++17 compiler and CMake 3.20 or newer. SushiDSP pins no toolchain. sd searches for a compiler in this order:

1. An explicit cxx, set in a config.local.toml or as the SD_CXX environment variable.
2. The intel/llvm clang++ that sd setup --toolchain intel-llvm provisions.
3. A clang++ on PATH.
4. CMake’s platform default: MSVC through the Visual Studio generator on Windows, the system compiler elsewhere.

sd config reports which step won and which generator was resolved. The golden-file comparisons hold across compilers because cmake/SushiDSPCompilerFlags.cmake pins FMA contraction off for every toolchain. The detail is under “Compiler resolution order” in the sd command line.

The three hosts under apps/ show the pattern: each owns an IAudioDevice, builds a RigGraph from node_registry(), and drives process() once per audio callback. Every product exposes one NodeDescriptor (an id, a name, parameters, ports and a make() function), so a host instantiates a node through make_node() without naming its concrete class.

The real-time path carries one rule: IAudioNode::process() and everything it calls allocates nothing, locks nothing, makes no system call and throws nothing. Architecture overview describes the layers and the core interfaces. sd docs writes the generated API reference to build/docs/api-site/html/.

You need sushicore. sd depends on it, and it supplies the setup, doctor, link, unlink, config and env commands.

SushiStack is optional: SushiDSP builds and tests without it. sd setup provisions into the shared root, ~/.sushisystems (or SUSHISYSTEMS_HOME), whether or not the checkout sits in a SushiStack workspace. Inside a workspace, sd link records the checkout in the workspace’s module registry, and sushi-module.toml makes it recognisable to hub. The core itself links no SushiRuntime, no SYCL and no game engine. cli/README.md says what the CLI takes from sushicore.

No. A VST3/CLAP plugin wrapper is design intent only: no apps/plugin directory exists in the tree. The same holds for any packaging step beyond what sd build and sd test exercise.

What the tree holds today is three standalone hosts: apps/host, a minimal SDL2-backed host; apps/host_asio, its ASIO-backed counterpart; and apps/host_gui, the rig-editing GUI. Architecture overview lists what is specified and not yet built.

Known issues records each measured defect that is left open, with its figure and what closes it. Some that a first-time user meets:

• The Mesa Mark IIC+ model has no clean setting; it limits at every input level.
• The Mark IIC+ costs 1.852 ms for a 256-frame block against the 1.5 ms budget that block is allowed at 48 kHz, so a rig that includes it can underrun at the smallest USB buffer.
• The Diezel VH4’s phase inverter and power section use the JCM800’s figures as a stand-in.
• A take leaves the host as WAV only; OGG export is deferred.
• A 44.1 kHz WAV dropped on a 48 kHz rig plays 8.8 % slow, because a take’s own sample rate is never read. Imported mp3 files are not affected.
• The ASIO host renders the rig in mono.

Remaining work is the single backlog of what is open.

SushiDSP is source-available, free for non-commercial use under the PolyForm Noncommercial License 1.0.0. LICENSE is the binding text and lists the permitted purposes: personal, non-commercial use, and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. To ask for one, write to hello@sushisystems.io with what you want to build and who will use it; COMMERCIAL.md says the same. NOTICE.md lists the third-party libraries a build links, the third-party data in the tree and the terms of a build with the Steinberg ASIO SDK.

Open an issue on the repository for a bug report or a design discussion. Contributions from outside Sushi Systems are not accepted yet, so an issue is the way in; Contributing says so in its first paragraph.

Do not open a public issue for a security problem. Report it privately by email to mustafagarip@sushisystems.io or through GitHub’s private vulnerability reporting, under the repository’s Security tab. The security policy promises an acknowledgement within 72 hours and an initial assessment within 7 days.

SushiTrack is a multi-object tracking library in C++17. It takes the detections of one frame and returns tracks with stable identities. A detection is a box with a top-left origin, a score and a label: (x, y, width, height, score, label).

The pipeline follows the ByteTrack two-stage association: detections at or above track_thresh are matched first, then the tracks left over try the low-score detections. Appearance ReID, Mahalanobis gating, the NSA and IMM motion estimators, observation-centric momentum and observation-centric re-update are optional and off in the compiled defaults. The architecture overview describes each stage.

The repository also holds a Python binding, the st developer CLI, a MOTChallenge and DanceTrack regression harness and a YOLOX video inference pipeline.

A C++17 compiler, CMake 3.14 or later, Ninja, GoogleTest and Python 3.11. environment.yml defines a conda environment that installs Python, CMake, Ninja, GoogleTest and the Python packages the evaluator and the inference pipeline use:

conda env create -f environment.yml
conda activate sushitrack

Eigen, TrackEval and YOLOX are git submodules, so run git submodule update --init after cloning. Docker is optional; CUDA inference in the container needs Engine 20.10 or later with the NVIDIA Container Toolkit. Installing lists every version.

st is the developer CLI of this repository, also installed as sushitrack. It is a Python package in cli/, installed with pipx:

pipx install cli/

cli/pyproject.toml requires sushicore>=0.7.0, and PyPI carries sushicore 0.1.0 to 0.4.0. Until 0.7.0 is published, pipx install cli/ cannot resolve that requirement. Install sushicore from a checkout into one environment with pip install -e /path/to/sushicore, then the CLI beside it with pip install -e cli. The conda environment pins sushicore==0.4.0, so an environment built from environment.yml needs the same step; see Installing.

st --help lists every command and st --version prints the installed version of sushitrack-cli.

st build
st test

st build configures and compiles the library and every test target; st build --no-test compiles the library only. The build type is release unless --type names debug, relwithdebinfo or minsizerel. The library lands at build/bin/{Release,Debug}/sushitrack.{dll,so}.

st test runs the functional suite, which is the unit, integration and regression suites together. st test --suite unit runs one of them. Building holds the CMake options and the command line reference holds every flag.

After st build, put bindings/python on PYTHONPATH. The module finds the library under build/ by itself.

from sushitrack import Tracker

tracker = Tracker(config="auto")              # reads sushitrack.json
tracks = tracker.update([(100.0, 100.0, 50.0, 80.0, 0.9, 0)], dt=1.0 / 30.0)
for t in tracks:
    print(t.track_id, t.x, t.y, t.width, t.height)
tracker.close()

bindings/python/sushitrack.py is a ctypes binding with no dependency outside the standard library. For a project outside this repository, st build --deploy python assembles package/ with the binding and the native library side by side; copy its sushitrack/ directory into your source tree. The binding README lists the constructor arguments and the order in which the module looks for the library, and Deploy packages shows the package layout.

Through the C API in include/SushiTrack/sushitrack_c.h, linked against the compiled sushitrack shared library. The header includes SushiTrack/sushitrack_export.hpp, which holds preprocessor macros only, and nothing else from the library, so a C consumer needs no Eigen and no C++ header. Fill a sushitrack_params_t with sushitrack_get_default_params, create the tracker with sushitrack_create_ex, and call sushitrack_update once per frame with an array of sushitrack_object_t; it returns the number of sushitrack_track_t records written. The C API reference has the status codes and the track fields.

st build --deploy cpp assembles package/ with the headers, the library, a default sushitrack.json and example/example.c with its CMakeLists.txt. Add package/include to the include path and link against package/lib/sushitrack.lib on Windows or package/lib/libsushitrack.so on Linux. Deploy packages covers how the runtime library is found at load time.

SushiTrack builds on Windows and Linux. The compilers listed are MSVC 19.20 or later, GCC 9 or later and Clang 10 or later. The library is built as a shared library with hidden-by-default symbol visibility on every platform; only functions carrying SUSHITRACK_API are exported.

A deploy package is platform-specific: st build --deploy copies the artefacts of the operating system it runs on, a .dll and .lib on Windows or a .so on Linux. There is no cross-compilation, so shipping both platforms means running the deploy once on each.

st container build builds an image from Dockerfile on a CUDA 12.1, Ubuntu 22.04 base, and st container run starts it with the repository mounted at /workspace/sushitrack. See Installing.

Edit sushitrack.json. The library parses the file itself, so a compiled build is retuned with no recompilation. It looks for the file in the SUSHITRACK_CONFIG environment variable first, then searches upward from the working directory for sushitrack.json. A key absent from the file keeps its compiled default.

The shipped sushitrack.json enables the tentative lifecycle, observation-centric momentum and observation-centric re-update. A caller that fills sushitrack_params_t in code and passes it to the create call bypasses the file and gets the compiled defaults, where those three are off. In Python, Tracker(config="auto") resolves the file through the library, and keyword overrides win over the file. Configuration lists every parameter with its default.

Benchmarks records two runs on the MOT17 and MOT20 train sets and on DanceTrack against the bundled ByteTrack and OC-SORT references. In the linear Kalman run (kalman_type=0, with the tentative lifecycle, OCM and ORU on and ReID off) the overall figures are:

Tracker	HOTA	Latency (µs/frame)
SushiTrack	45.7 %	57
ByteTrack	40.8 %	103
OC-SORT	44.3 %	223

On DanceTrack alone, OC-SORT scores 45.6 % HOTA in that run and SushiTrack 44.9 %. The second run changes only kalman_type to 2, the IMM estimator: SushiTrack reaches 45.8 % overall HOTA at 218 µs per frame. Latency is the mean per-frame update() time, single-threaded, excluding I/O. The date, the commit and the machine of the runs were not recorded.

st eval --compare runs all three trackers side by side and prints the same metrics table; see the evaluation pipeline.

The st CLI is built on sushicore, the Sushi Systems package that gives every Sushi CLI (sr, se, sa, sb, sd, hub) its console, configuration layering and build driver. st setup, st doctor, st link and st unlink come from sushicore and behave the same in each of them.

Inside a SushiStack workspace, hub add sushitrack installs the CLI, and st link and st unlink register a checkout in a workspace or remove it. cli/sushistack.deps.toml is the SushiStack dependency fragment; it names GoogleTest, the only port SushiTrack does not vendor. st setup provisions what that fragment lists.

The library itself links Eigen and JSON for Modern C++. The Python binding depends on the compiled library and on nothing else in the repository.

The manual states these limits:

• It does not compute appearance embeddings. With enable_reid=1, each detection carries an external embedding as a seventh tuple element.
• It associates across all detections regardless of label. Partition the detections before update if you need per-class tracking.
• A single tracker instance is not designed for concurrent update calls. Construct one instance per stream.
• The C API does not report which input detection produced each track.
• No Ultralytics adapter is shipped. Ultralytics integration is a recipe whose snippets you copy into your own project.
• No built Docker image is published, and st deploy copies no licence file into package/.

Contributions from outside Sushi Systems are not accepted yet. Recorded defects are in Known issues; among them, sushitrack_update returns 0 both on a caught exception and on a rejected argument, which a caller cannot tell from a frame with no tracks, and no CI workflow exists.

SushiTrack is source-available under the PolyForm Noncommercial License 1.0.0, free for non-commercial use. LICENSE is the binding text and lists the permitted purposes: personal, non-commercial use, and use by the non-commercial organisations it names.

Any commercial purpose needs a separate, paid licence from Sushi Systems. That includes use inside a company, use in paid client work, and use in a product or service that is sold. To ask for one, write to hello@sushisystems.io with what you want to build and who will use it; see COMMERCIAL.md.

Third-party code and data keep their own licences, listed in NOTICE.md. The repository’s licence does not cover the MOT17, MOT20 and DanceTrack files under tests/regression/evaluator/data/.