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.
• Unsupported pimsim-nn operations must 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.
• Adapt compiler inputs to the oracle instead. For YOLO, use validation/networks/pimcomp_models/yolo11n/yolo11n-pimsim-nn.onnx, the dedicated pimsim-ready performance artifact with Softmax operations removed. Use validation/networks/yolo11n/depth_51/yolo11n_depth_51.onnx for YOLO functional validation; removing Softmax changes the model's numerical behavior, so the pimsim-ready artifact is not a correctness reference.

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