Performance Optimization

Performance Optimization

Read references/performance-optimization.md completely before inspecting or changing runtime code. It is the in-repository fallback copy of Albucore's canonical docs/performance-optimization.md, so the guide remains available when the Albucore checkout is absent.

When changing the guide, update the canonical Albucore document first and keep the bundled copy synchronized. When both repositories are available, verify exact synchronization with cmp -s ../albucore/docs/performance-optimization.md .codex/skills/performance-optimization/references/performance-optimization.md. A mismatch blocks completion.

Workflow

1. Establish correctness and performance baselines before editing.
2. Run every stage of the guide's optimization pass. Do not stop after finding the first plausible improvement.
3. Treat every backend, vectorization, LUT, random-generation, bincount, and in-place proposal as a benchmark hypothesis.
4. Check the repository boundary. Move a reusable image-processing atom into Albucore instead of duplicating it in transforms.
5. Read ../benchmark/SKILL.md completely and benchmark both the isolated kernel and the Compose route on its required size, channel, and dtype matrix.
6. Add correctness tests before accepting a faster path. Preserve shapes, dtypes, values, annotations, aliasing, and seeded-replay contracts unless the change explicitly documents a compatibility break.
7. Run the project validation workflow after the final implementation.

Torch Runtime Contract

Torch is already an externally managed, soft-required AlbumentationsX runtime dependency: package metadata does not select a CPU, CUDA, or MPS build, but importing albumentations requires an installed Torch runtime. Do not reject a Torch-backed implementation on the grounds that it would introduce a new runtime dependency. Benchmark the complete route, including NumPy/Tensor bridges, layout conversions, allocations, and return conversion.

Compose Execution Changes

For composition.py, transforms_interface.py, or invocation-state work, keep configured graph policy separate from per-call state. Sampled parameters, applied records, processor sessions, Tensor bridge metadata, grayscale repair, and instance-binding bookkeeping belong to InvocationContext; a configured transform or Compose must not become a mailbox for any of them.

• Reserve a default DataLoader seed only at the root. The reservation lock may cover the counter and configured RNG source; array conversion, preprocessing, transform execution, tracing, and finalization must remain outside it.
• Preserve one root prepare/finalize boundary. Nested Compose nodes run focused additional-target and shape checks without opening a second processor, grayscale, Tensor, or restoration boundary.
• Keep BaseCompose._apply_child() as the sole configured-graph dispatcher. run_with_trace() may attach an invocation-local observer, but it must not introduce a second node-selection or execution traversal.
• Schedule bbox/keypoint filtering from declared target effects. Image-only nodes must not pay for shape discovery, clipping, filtering, or instance re-alignment; a final conversion must not repeat a filter already current for the invocation.
• Optimize repeated application before construction. Compose.__init__() may compile the graph and eagerly prepare root-owned execution state when that removes work from the per-sample path. Report construction cost only as context; do not reject a call-time speedup because pipeline construction becomes slower.
• Keep invocation_seed sample-keyed and side-effect free with respect to the worker stream.
• Measure root skip, no-op, probabilistic no-op, always-applied cheap transform, applied-configuration capture, trace, Tensor, processor, and concurrent-call routes. Include the complete before/after cells in the handoff.
• Exercise tests/test_compose_reentrancy.py, tests/test_per_worker_seed.py, tests/test_composition_tracing.py, and the affected Tensor, processor, replay, and instance-binding suites.