flopscope-client

Lightweight drop-in replacement for flopscope that proxies all operations to a remote flopscope-server over ZMQ + msgpack.

flopscope-client provides the same import flopscope Python module as the main flopscope distribution, but with no NumPy dependency — it forwards every counted operation to a flopscope-server process. Use this in constrained environments where you want flopscope's FLOP-counting API but cannot ship numpy + the full library (e.g. sandboxed participant containers in the ARC Whitebox Estimation Challenge).

Install instead of, not alongside

flopscope-client occupies the same flopscope Python import namespace as the main package. The two are mutually exclusive — installing both leads to file-overlap in flopscope/. Choose one:

# Lightweight: client-only, no numpy
pip install flopscope-client

# Heavy: full library on the local machine
pip install flopscope

# Server-side: both flopscope + flopscope-server, pinned together
pip install "flopscope[server]"

Quick start

The client connects to a flopscope-server instance specified by the FLOPSCOPE_SERVER_URL environment variable:

export FLOPSCOPE_SERVER_URL=tcp://flopscope-server.example.com:15555
# or for a local UNIX socket:
export FLOPSCOPE_SERVER_URL=ipc:///tmp/flopscope.sock

Then use flopscope normally — the import path and API are identical to the main distribution:

import flopscope as flops
import flopscope.numpy as fnp

with flops.BudgetContext(flop_budget=1_000_000):
    a = fnp.array([1.0, 2.0, 3.0])
    b = fnp.array([4.0, 5.0, 6.0])
    result = fnp.add(a, b)  # round-trips to the server, runs there
    flops.budget_summary()

On the first request, the client performs a version handshake with the server. A version mismatch raises ConnectionError with both versions in the error message — keep flopscope-server and flopscope-client on the same release.

Differences from NumPy

The API mirrors NumPy, with one semantic difference worth knowing up front: flopscope arrays are immutable (like JAX). Item assignment and indexed in-place updates raise TypeError:

arr[i] = value  # TypeError: flopscope arrays are immutable
arr[i] += value  # same error — desugars to arr[i] = arr[i] + value

Build results functionally instead — collect the pieces in a list and fnp.stack(...) them, or use a whole-array update (arr = arr + x, which rebinds rather than mutates). See the Immutable arrays guide for the accumulation recipe.

When to choose this over the main flopscope install

Architecture overview

┌─────────────────────────────┐         ZMQ + msgpack         ┌──────────────────────────────┐
│  flopscope-client process   │ ───────────────────────────▶  │  flopscope-server process    │
│  (sandbox; no numpy)        │                                │  (full flopscope + numpy)    │
│  `import flopscope as flops`│ ◀───────────────────────────  │  Executes ops, tracks budget │
└─────────────────────────────┘                                └──────────────────────────────┘

The client serializes each operation (op name, args, kwargs) as msgpack, sends it over the ZMQ REQ/REP socket, and decodes the response. Budget tracking, symmetry-aware FLOP counting, and operation-cost analytics all happen on the server side; the client just relays calls.

Related

• flopscope — full NumPy-backed library (alternative install)
• flopscope-server — the server-side runtime this client connects to
• Documentation — full guides
• GitHub — source, CHANGELOG, contributor guide

License

MIT