Troubleshooting

Most AutoZyme problems are ordinary environment, activation, or benchmarking issues. If your pipeline runs and the results look normal, there is nothing special to troubleshoot.

First checks

Is the patch active?

import autozyme
autozyme.activate("scanpy")
autozyme.status()
autozyme.inspect("scanpy")
library(autozyme)
activate("seurat")
status()
inspect("seurat")

If inspect() says the target is not bound to the fast function, the patch did not activate for that upstream package/version.

Does vanilla fail too?

Run the same call with AutoZyme disabled:

with autozyme.disabled():
    sc.tl.pca(adata)
autozyme::with_disabled({
  Seurat::RunPCA(obj)
})

If vanilla fails, fix the upstream package, data, or environment first. AutoZyme is not the cause.

Is the benchmark measuring startup?

Some patches pay a one-time import, JIT, or worker startup cost. If a run looks slower than expected, time the same operation twice in the same process and report both numbers. The first call is the honest cold-start number; later calls show steady-state speed.

Are you using worker processes?

On Windows, macOS, joblib, and loky, child processes start fresh. Activate AutoZyme inside each worker initializer. See Threading & multiprocessing.

When results differ

Use the same input object, the same random seed, and compare one small call:

sc.pp.normalize_total(adata_fast)
sc.pp.normalize_total(adata_base, zyme=False)
Seurat::NormalizeData(obj_fast)
Seurat::NormalizeData(obj_base, zyme = FALSE)

Small floating-point differences are expected for some numeric kernels. Large changes, missing rows, changed labels, or crashes are bugs.

What to send us

Include:

  • the patch name, for example scanpy or seurat
  • the activation banner printed by AutoZyme
  • package versions for AutoZyme and the upstream tool
  • OS, CPU, and thread count
  • whether the same call works with AutoZyme disabled
  • cold-start and second-call timings, if the issue is speed
  • the smallest code snippet that reproduces the problem