Skip to main content

copyengine

Deliver optimal copy performance effortless.

Hand the copies scattered through your code (copy_, gather / scatter, host ↔ GPU transfers, layout changes, casts) to copyengine. It merges them, decides where to reorder and convert, and tunes itself to the hardware it runs on. Existing code mostly stays as it is.

Before / after

# Before: layers × blocks small copies, each its own call (tens of thousands of calls)
for layer in range(L):
    for blk in blocks:
        scale_k[layer][blk].copy_(k_qs_buf[blk].expand(N, S))

# After: one line of wrapping. The loop is unchanged; its copies are merged
# into a few transfers and kernels.
with ce.scope():
    for layer in range(L):
        for blk in blocks:
            scale_k[layer][blk].copy_(k_qs_buf[blk].expand(N, S))

Loops like this are usually rewritten by hand into a few vectorized copies or a custom kernel. copyengine aims to get that result without the rewrite, and without a new kernel for every new model or cache layout.

Where it helps

  • Inference: loading and offloading KV cache blocks between host and GPU, paged caches (gather / scatter by block id), quantizing or dequantizing KV on the way (FP8 or int8 with a scale), swapping LoRA weights in and out.
  • Training: offloading optimizer state and activations, dataloader H2D, checkpoint save / load and resharding (pure reordering).
  • Model code: x.permute(...).contiguous().cuda(), copying after index_select, permute-then-cast: write it as one ce.copy_ into the destination (with ce.lazy for gathers), and it happens in one pass, with the reordering done on the GPU.

copyengine moves and converts data. Computation such as reductions is out of scope: it runs as usual, ordered correctly around the copies.

What it guarantees

  1. Not slower than the original. Wherever torch has the same copy, torch's own copy_ is always a candidate. Anything else is measured against it, including the time copyengine itself spends planning and submitting, and is kept only if it is clearly faster. Decisions keep being re-checked while your program runs. A scope as a whole is held to the same rule: each scope call site compares running intercepted with not intercepting at all (host and GPU time), and stops intercepting where that does not clearly win, for example around ops copyengine does not take (index_copy_) or copies torch already does best (stats()["scopes"]). The explicit API has the same protection where torch can express the copy: ce.lazy views, ce.gather, ce.scatter_, ce.segments and ce.indices are measured against the same copy written with torch ops (indexing, index_copy_, slices) from the same host indices. Conversions with fn= and views torch has no form for (a reversed slice) have no torch equivalent: there copyengine picks the fastest of its own strategies. Either way it cannot beat torch code that does less work, for example indices already on the GPU, and each explicit call costs a few microseconds of host time: for a few small copies per step, freeze() or a CUDA graph is the fast path.
  2. The same results. copyengine only takes a copy when it can produce exactly torch's result; otherwise torch runs it. Host and GPU conversions are bit-identical. (NaN stays NaN, but its sign and payload bits are not kept: torch's own differ between its CPU and CUDA conversions.)
  3. Easy to turn off. CE_DISABLE=1 turns copyengine's choices off: every copy runs through torch's own copy_, or exactly as submitted where torch has no equivalent.
  4. Bounded resources. With torch installed, copyengine's own device memory (staging, copy tables) comes from torch's caching allocator, so it shows in torch.cuda.memory_allocated() and obeys torch's limits. Device staging has a budget (CE_STAGING_MB), and Engine(max_sms=N) (or CE_MAX_SMS) keeps copy kernels on at most N SMs per GPU, leaving the rest to your compute. Where the driver supports green contexts the limit is hard (checked on start); otherwise copyengine launches at most N thread blocks. DMA copies use the copy engines and no SMs; memory bandwidth is still shared.

The first runs of each new copy pattern are a warmup: copyengine measures its options, then locks the fastest. Save the result with eng.save_profile(path) to skip the warmup next time on the same machine.

Install

pip install copyengine

The wheels include the GPU kernels and the torch integration; they use the torch you already have. To build from source instead:

pip install .                      # needs CMake >= 3.26 and a C++20 compiler
                                   # GPU support: CUDA toolkit headers + nvcc at build time
pip install --no-build-isolation . # same, with torch already installed: also builds the torch integration

dtypes: float64/32/16, bfloat16, float8 (e4m3fn, e5m2, e8m0fnu), int64/32/16/8, uint8 and bool convert into each other; packed FP4 (float4_e2m1fn_x2) is copied unconverted.

Requirements: Linux on x86_64 or aarch64 (server ARM such as Grace: GH200, GB200, GB10; not Jetson), Python ≥ 3.10. GPU support runs on CUDA 12.x and 13.x drivers; the driver is loaded at runtime, nothing links against libcuda or cudart.

The torch integration is built against the torch you have installed. If you later switch torch versions, the part that intercepts copy_ is recompiled once on import (needs a C++ compiler, takes seconds, cached). If that is not possible, scopes fall back to a pure-Python interception with the same results, only slower, and a warning says so.

Use torch 2.10 or newer for the best performance. Every torch from 2.9 on gives the same results, but from 2.10 the explicit API (ce.copy_, ce.lazy, ...) runs as a compiled torch op; on 2.9 it goes through Python and costs a few more microseconds per call, which matters for many small copies. scope() interception is compiled on every supported version.

Use

import copyengine as ce
import torch

# 1. Unchanged torch code: copy_ inside a scope is queued and merged.
with ce.scope():
    for l in range(num_layers):
        for i, b in enumerate(block_ids):
            kv_cache[l, b].copy_(host_slot[l, i])

# 2. A copy torch cannot express as one view: gather + permute + cast in one pass.
src = ce.lazy(cache).index_select(0, ids).permute(0, 2, 1, 3)
ce.copy_(out_fp16, src)

# 3. Quantize / dequantize on the way.
ce.copy_(q_int8, x, fn=ce.Elementwise(scale=1 / qs, round=True, clamp=(-127, 127)))

# 4. Ragged or CSR layouts: many segments in one call.
ce.segments(src, dst, src_off, dst_off, length)

# 5. Overlap copies with compute: run them on a copy stream, the host never waits.
with ce.scope(stream="copy") as h:      # or stream=<a torch.cuda.Stream>
    for l in range(num_layers):
        next_kv[l].copy_(host_kv[l, ids])
...                                     # compute keeps running on the current stream
h.wait()                                # the current stream waits for the copies (GPU side)

# 6. Replay a planned copy without planning again.
eng = ce.Engine()
with eng.scope():
    ...
plan = eng.freeze()
plan.run()

More: ce.gather / ce.scatter_ for index-based copies, ce.barrier() to wait for queued work, ce.probe() to see which copy mechanisms this machine supports (each verified by a real copy). C and C++ callers use include/copyengine/copyengine.h (a stable C ABI) or copyengine::copyengine from CMake.

To see what copyengine did: eng.stats()["last"]["decisions"] lists each group of the last flush with its strategy and why (still exploring, the A/B result it locked on, an online re-check, a CUDA graph capture), and stats()["declined"] counts the intercepted copies it left to torch, by reason. In Nsight Systems every group is an NVTX range named copyengine:<strategy>.

To compare against torch on your GPU: python bench/bench_torch.py.

With an AI coding agent

Two Agent Skills teach coding agents (Claude Code, Codex, Cursor, ...) to adopt and debug copyengine: copyengine-adopt finds copy hotspots, picks the integration, warms it up and proves same results and the measured gain; copyengine-diagnose explains slow, declined or failing copies from copyengine's own stats.

npx skills@1 add https://github.com/itdevwu/copyengine/tree/v0.2.2/skills/copyengine-adopt --global
npx skills@1 add https://github.com/itdevwu/copyengine/tree/v0.2.2/skills/copyengine-diagnose --global

How it works

Copies issued inside a scope are queued instead of run. When the scope ends, copyengine looks at them together: which ones depend on each other (exact address ranges), which can be merged across tensors, and what structure they form (2-D blocks, strides, broadcasts). For each group it picks among merged DMA calls, batched DMA (cuMemcpyBatchAsync), 2-D copies, copy kernels that also cast and scale, moving data densely over the link and reordering it on the GPU, or pinned bounce buffers for pageable memory, and measures which is fastest.

Rules worth knowing

  • Inside a scope, every other op is ordered after the queued copies whose memory it reads or writes, so code in the scope sees the copied data. Memory read without going through torch (.numpy(), raw pointers) needs ce.barrier() first.
  • GPU work runs on the current stream, like torch's own copies. GPU-to-GPU copies are not waited for; intercepted copy_ keeps its non_blocking behavior; the explicit ce.copy_ returns with any host-side copy complete (unless the engine was created with allow_async=True).
  • Threads: ce.scope() and ce.copy_ use a per-thread default engine. An Engine you share between threads works while none of them has a scope open on it; a copy or scope from another thread during one raises an error.
  • Buffers of copies that are not waited for (intercepted non_blocking copies, allow_async) are kept alive until the GPU is done with them.
  • CUDA Graphs: copies inside torch.cuda.graph (scopes, ce.copy_, FrozenPlan.run()) are recorded and replay correctly. Copies torch has no equivalent for must run once before capturing.
  • scope(stream=...): the scope's work (its copies, and any other op written in it) runs on that stream, after what the current stream had queued. The host waits for none of it, even for copies that would otherwise block; the returned handle (wait(), synchronize(), done(), event) orders it against the rest. Its buffers stay alive until the copies are done. Inside a CUDA graph capture this is a fork, and h.wait() the join. Copies copyengine leaves to torch (for example a float-to-int cast) keep torch's own semantics.
  • Index tensors (ce.lazy(...).index_select, ce.gather, ce.scatter_) are read on the host: a CUDA index tensor costs one device synchronization per call. Pass host indices on hot paths.
  • Each destination element must be written once per copy: duplicate scatter indices and a source overlapping its own destination raise UnsafeCopy in the explicit API (an intercepted copy_ leaves those to torch).

Environment

Variable Effect
CE_DISABLE=1 turn copyengine's choices off: torch's own copy, or each copy as submitted
CE_EXPLORE=0 never measure: use the loaded profile; copy patterns it does not cover run natively (or with copyengine's default where torch has no equivalent) and are listed in the profile for the next warmup
CE_STAGING_MB device staging budget in MB (default 256)
CE_LOG=plan print plans to stderr
CE_SYNC=1 wait for every copy to finish (debugging)
CE_MAX_SMS at most this many SMs per GPU for copy kernels (see guarantee 4)
CE_SHIM=0 skip the compiled copy_ interception; scopes intercept in Python
CE_TORCH_ALLOCATOR=0 take copyengine's device memory from cuMemAlloc instead of torch's allocator
CE_CACHE_DIR where interception builds compiled on import are cached (default ~/.cache/copyengine)

Licensed under Apache-2.0.

Metadata

Release files for copyengine 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for copyengine 0.2.2
File Size Uploaded Provenance Actions
copyengine-0.2.2.tar.gz 172.7 kB With provenance Details for copyengine-0.2.2.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for copyengine 0.2.2
File Actions
copyengine-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for copyengine-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
copyengine-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl CPython 3.12 abi3 Linux glibc 2.26+ ARM64, Linux glibc 2.28+ ARM64 Details for copyengine-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
copyengine-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for copyengine-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
copyengine-0.2.2-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ ARM64, Linux glibc 2.26+ ARM64 Details for copyengine-0.2.2-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
copyengine-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for copyengine-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
copyengine-0.2.2-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ ARM64, Linux glibc 2.26+ ARM64 Details for copyengine-0.2.2-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Total release size: 36.3 MB

Release files / copyengine-0.2.2.tar.gz

Download URL copyengine-0.2.2.tar.gz
Size 172.7 kB
Tags Source
SHA-256 checksum
How to use checksums
2fd4dff29e2c4aea5929ef6cba19ff664ba2e8beb17db93914ed374719aefe00
BLAKE2b-256 checksum
How to use checksums
873ec6e18f88855b48bc489fccb928ef3e819257425f4b8d621e213da5ad284e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / copyengine-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL copyengine-0.2.2-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 6.1 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
9222e0adb892aa5f4eee21b58a4d07889f594074eb7dd9aca818a847c131a738
BLAKE2b-256 checksum
How to use checksums
34401439c376c0abd2ce7406ec63078a60d9d9ae169c7e9b546a519c2edcc504
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / copyengine-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Download URL copyengine-0.2.2-cp312-abi3-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Size 6.0 MB
Tags CPython 3.12 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
543f425caf2651624ae184b590dac920d695b0cebaa432cc645fcbadf8ce9dbc
BLAKE2b-256 checksum
How to use checksums
02584db1f19beafa3fbacda3781d4e8e659632946d5061b29c851f798dcd994f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / copyengine-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL copyengine-0.2.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 6.1 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
4f8338be795aa2758e4dd59b03fbb7ac62f7ed45944a50e66d7fda03859f2527
BLAKE2b-256 checksum
How to use checksums
389d29132a86d78fa6330ae90c94edfa75e3decff453193f31c73ce1d5da53b1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / copyengine-0.2.2-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Download URL copyengine-0.2.2-cp311-cp311-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Size 6.0 MB
Tags CPython 3.11 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
f53a43ae6387b388242a40c0b3134f77e2bcd6abff8ef5d1286ad53361b8a217
BLAKE2b-256 checksum
How to use checksums
5ce4593fe5be1c24b654e988f8251a296e95e80af5e85935fccebe05f06ffbc5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / copyengine-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL copyengine-0.2.2-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 6.1 MB
Tags CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
c5d9768d8d44546e498931cee6da558dea53db8a1307d223cabe5786ed9c5dc4
BLAKE2b-256 checksum
How to use checksums
c2fb3cc51ae4907b82bce2a6670686402d4139d444d7c954f67833a1831d9ef3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / copyengine-0.2.2-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl

Download URL copyengine-0.2.2-cp310-cp310-manylinux_2_26_aarch64.manylinux_2_28_aarch64.whl
Size 6.0 MB
Tags CPython 3.10 Linux glibc 2.26+ ARM64 Linux glibc 2.28+ ARM64
SHA-256 checksum
How to use checksums
1dc753991a9bef18e095d76b00fb546593f5fe71ed126c1462e5968721c65285
BLAKE2b-256 checksum
How to use checksums
29e8909f572c5a57c632875d117222cc836d438bcf37e88b7a8a164617d78757
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for copyengine 0.2.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 7 files in this release have been uploaded with provenance metadata.

Select from 7 files

Attestation for copyengine-0.2.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page