Raptor/.agents/invariants/PIMSIM_NN_ORACLE_INVARIANT.md

pimsim-nn Oracle Invariant

backend-simulators/pim/pimsim-nn is the performance oracle. Its simulation behavior defines the hardware model used for Raptor/PIMCOMP comparisons.

Required invariant

• Do not add instruction or operator support to pimsim-nn.
• Changes to pimsim-nn must preserve simulation behavior exactly. Acceptable changes are limited to behavior-neutral maintenance proven not to alter simulated timing, scheduling, power, energy, or supported input programs.
• Other unsupported or unknown pimsim-nn operations remain unsupported. Do not approximate their timing or map them onto another operation.
• Validation must report an explicit unsupported-op diagnostic as UNSUPPORTED, not as a simulator failure.
• A compiled artifact with zero active PIM cores has no meaningful non-functional simulation and must be reported as SKIP.

Explicit vsoftmax exception

vsoftmax has no Pimsim-nn hardware timing model. This one explicitly authorized exception does not permit other simulator approximations.

• Pimsim-nn omits vsoftmax while loading JSON or binary instructions, before fetch. Omitted instructions consume no fetch, issue, execution, memory, or dynamic-energy service.
• Pimsim-nn warns once per process that Softmax timing and energy are excluded.
• Functional simulation executes Softmax normally.
• Raptor's queue estimator applies the same zero-cost omission. All surrounding instructions, materialization, transfers, and synchronization remain modeled.
• state.instructions intentionally counts vsoftmax: it is a real encoded PIM instruction, although Pimsim-nn does not simulate it.
• No additional Pimsim-nn behavior changes are authorized.

Current comparisons use the full YOLO11n model, including both Softmax operations, at validation/networks/yolo11n/depth_51/yolo11n_depth_51.onnx. GoogLeNet uses validation/networks/pimcomp_models/googlenet/googlenet-12-no-lrn.onnx, with only its two unsupported LRN nodes bypassed. Terminal Softmax is retained. Historical Softmax-free artifacts are not matched baselines for these graphs.

Any proposed pimsim-nn behavior change requires explicit user authorization and must not be introduced as part of a compiler optimization.