Performance Optimization
Read ../../../docs/performance-optimization.md completely before inspecting or changing runtime code. That document
is the canonical shared workflow for Albucore and AlbumentationsX.
When the sibling AlbumentationsX checkout is available, verify the fallback copy with
cmp -s docs/performance-optimization.md ../AlbumentationsX/.codex/skills/performance-optimization/references/performance-optimization.md.
A mismatch blocks completion.
Workflow
- Establish correctness and public-router performance baselines before editing.
- Run every stage of the canonical optimization pass. Do not stop after finding the first plausible improvement.
- Treat delete-first, vectorization, LUT, random generation,
bincount, backend selection, routing thresholds, and
in-place mutation as benchmark questions.
- Compare the complete public path, including dispatch, dtype conversion, contiguity, allocation, clipping, and shape
repair.
- Read
../albucore-benchmarks/SKILL.md completely before measuring. Extend the matrix along the dimension that
controls the candidate.
- Add or preserve correctness tests for every accepted route and its boundary cases.
- Update benchmark evidence and route documentation when public routing changes.
Albucore Boundary
Accept reusable atomic array operations with stable image semantics. Keep augmentation policy, stochastic parameter
sampling, target dispatch, and annotation rules in AlbumentationsX.
Before adding an atom:
- search Albucore for an existing router or lower-level operation;
- search AlbumentationsX for duplicate local implementations;
- define dtype, shape, channel, contiguity, aliasing, and error contracts;
- benchmark all viable backends before exposing a route.
Albucore routers are called after the upstream validation boundary. The caller owns container type, rank/layout,
dtype, device, contiguity, autograd, and operation-control validation. Do not duplicate those checks in the runtime
router; retain only backend dispatch and kernel-required normalization. Invalid direct calls are outside the low-level
contract and must not add hot-path branches.
Required Handoff
Report:
- work deleted or avoided;
- full-array passes, copies, conversions, and allocations removed;
- vectorization and grouped-reduction candidates evaluated;
- LUT, random-generator, and backend candidates compared;
- routing thresholds and safe in-place decisions;
- AlbumentationsX duplicates replaced or follow-up extraction opportunities;
- correctness evidence, benchmark matrix, regressions, and rejected candidates.
1---2name: performance-optimization-23description: Systematic performance audit for Albucore runtime code. Use whenever implementing, reviewing, profiling, or optimizing atomic image operations, backend routing, reductions, label maps, LUTs, random generation, dtype conversions, allocation-heavy paths, batch or volume kernels, or in-place behavior.4---56# Performance Optimization78Read `../../../docs/performance-optimization.md` completely before inspecting or changing runtime code. That document9is the canonical shared workflow for Albucore and AlbumentationsX.1011When the sibling AlbumentationsX checkout is available, verify the fallback copy with12`cmp -s docs/performance-optimization.md ../AlbumentationsX/.codex/skills/performance-optimization/references/performance-optimization.md`.13A mismatch blocks completion.1415## Workflow16171. Establish correctness and public-router performance baselines before editing.182. Run every stage of the canonical optimization pass. Do not stop after finding the first plausible improvement.193. Treat delete-first, vectorization, LUT, random generation, `bincount`, backend selection, routing thresholds, and20 in-place mutation as benchmark questions.214. Compare the complete public path, including dispatch, dtype conversion, contiguity, allocation, clipping, and shape22 repair.235. Read `../albucore-benchmarks/SKILL.md` completely before measuring. Extend the matrix along the dimension that24 controls the candidate.256. Add or preserve correctness tests for every accepted route and its boundary cases.267. Update benchmark evidence and route documentation when public routing changes.2728## Albucore Boundary2930Accept reusable atomic array operations with stable image semantics. Keep augmentation policy, stochastic parameter31sampling, target dispatch, and annotation rules in AlbumentationsX.3233Before adding an atom:3435- search Albucore for an existing router or lower-level operation;36- search AlbumentationsX for duplicate local implementations;37- define dtype, shape, channel, contiguity, aliasing, and error contracts;38- benchmark all viable backends before exposing a route.3940Albucore routers are called after the upstream validation boundary. The caller owns container type, rank/layout,41dtype, device, contiguity, autograd, and operation-control validation. Do not duplicate those checks in the runtime42router; retain only backend dispatch and kernel-required normalization. Invalid direct calls are outside the low-level43contract and must not add hot-path branches.4445## Required Handoff4647Report:4849- work deleted or avoided;50- full-array passes, copies, conversions, and allocations removed;51- vectorization and grouped-reduction candidates evaluated;52- LUT, random-generator, and backend candidates compared;53- routing thresholds and safe in-place decisions;54- AlbumentationsX duplicates replaced or follow-up extraction opportunities;55- correctness evidence, benchmark matrix, regressions, and rejected candidates.
albumentations-team