Client-Server Model

This page covers the client-server architecture used for competition evaluation, where participant code runs in an isolated container. For how Flopscope wraps NumPy internally, see How Flopscope Works.

Use this page to understand how Flopscope's client-server architecture works and why it exists.

You will learn:

Why Flopscope uses a client-server model for competition evaluation
How arrays, operations, and budgets flow between client and server
How to choose between the local library and client-server packages

Why client-server?

In competition evaluation, participant code runs in an isolated container that cannot import NumPy directly. This prevents participants from bypassing FLOP counting by calling NumPy functions outside flopscope.

The client-server model enforces this isolation:

How it works

Server runs the real flopscope library backed by NumPy. It stores all arrays, enforces budgets, and counts FLOPs.
Client exposes the same public imports (import flopscope as flops plus import flopscope.numpy as fnp) and proxies every operation to the server over ZMQ (msgpack-encoded messages).
Arrays stay on the server. The client holds lightweight RemoteArray handles that reference server-side data. When you call fnp.einsum(...), the client sends the operation and handle IDs to the server, which executes it and returns a new handle.
Budget enforcement happens server-side. The client cannot manipulate FLOP counts.

Communication protocol

Transport: ZMQ (REQ/REP pattern)
Serialization: msgpack with binary-safe array payloads
Default endpoint: ipc:///tmp/flopscope.sock (configurable via FLOPSCOPE_SERVER_URL)
Timeout: 30 seconds per request

API compatibility

Code written for the local library works unchanged with the client:

# This code works with BOTH the local library and the client
import flopscope as flops
import flopscope.numpy as fnp

with flops.BudgetContext(flop_budget=10**6) as budget:
    x = fnp.zeros((256,))
    W = fnp.random.randn(256, 256)
    h = fnp.einsum('ij,j->i', W, x)
    print(budget.summary())

When to use which

Use case	Package	Install path
Development, testing, research	`flopscope` (local library)	`uv add git+...` or `uv sync` from repo
Competition evaluation, sandboxed environments	`flopscope-client` + `flopscope-server`	Docker containers

Three packages in this repo

Package	Location	Description
`flopscope`	`src/flopscope/`	Local library — full NumPy backend, direct execution
`flopscope-client`	`flopscope-client/`	Client proxy — no NumPy dependency, forwards ops to server
`flopscope-server`	`flopscope-server/`	Server — runs real flopscope, manages sessions and arrays

Running with Docker — set up client-server locally
Contributor Guide — source-checkout commands for local development
Quickstart — getting started with the local library