Top K — Machine Learning/Postprocessing

Top K

Machine Learning / Postprocessing

Reduces a column of scores to its k largest entries, ranked:

idx_p = the position of the p-th largest entry, plus Index Base; val_p = that entry's value, for p = 1 … K.

This is Argmax Decision generalised: where that block names the one winning class, this one names the shortlist – the top-5 a recogniser reports, the two candidate modes a supervisor arbitrates between, the runners-up a confidence margin is measured against (val₁ − val₂).

Ties rank by lowest index first, which is Argmax Decision's rule extended to an order: equal scores come out in the order they appear in u. The result is exactly a stable descending sort truncated to its first K rows.

Ports

• u – the scores, a column [m,1] with m ≥ K – logits, probabilities or any comparable quantity.
• idx – a column [K,1]: the ranked positions, best first, each plus Index Base. Carried as real numbers like every other signal in the model; they are always whole ones.
• val – a column [K,1]: the corresponding values, in whatever units u carried, in descending order. Row p of idx and row p of val always describe the same entry.

Parameters

• K – how many entries to report, and the height of both outputs. A count: it is rounded to the nearest whole number, so a value arriving as 2.9999999 means 3. It must be at least 1 and no larger than the width of u – a shortlist longer than the list it is drawn from is refused at run start rather than padded, because there is no honest value to pad it with. Default 3.
• Index Base – what the first element is called:
  • Zero-based (PyTorch, numpy) – the first class is 0. The default, and what a model exported from a Python framework expects.
  • One-based (MATLAB) – the first class is 1, for a graph whose downstream lookup or switch is written in MATLAB's convention.
  It shifts the reported indices and nothing else – the comparisons, the tie rule, the ranking and the val output are identical either way.
• Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.

Code export

All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text. K and the index base are baked into the body at export time – K sizes the output ports, so it could not be tunable on the generated core – and there is no tunable parameter.

The six software targets emit two nested loops. The three HDL targets and PLC ST emit the K passes unrolled, K×m comparisons in all, because a pass reads the previous pass's output row and neither the pass count nor the width is a run-time quantity. The HDL targets are genuine Q16.16 fixed point: the block only compares and copies, with no transcendental and no division in it, and the selection deliberately avoids the data-dependent array write a mask-out-the-winner formulation would need. See the Notes for what fixed point costs at a near-tie.

Simulink bridge

None. The closest block on this installation is dspstat3/Sort, and it was probed in R2026a rather than read from documentation: its dialog offers otype (Value / Index / Value and Index), dir and sortAlg, and no k of any kind. It sorts the whole vector and emits two full-length outputs, so a Top K with K < m – the only interesting case – has no parameter to map onto, and there is nowhere for the row count to cross. Its sortAlg choice (Quick sort / Insertion sort) is a tie-order-visible knob this block does not have either. The bridge reports the block rather than dropping it silently, and it has no parity testbench, which is the documented consequence of Support::None rather than a gap. Code export verification still covers it across all ten languages.

Notes

• Algebraic and stateless: the outputs depend only on the current input, so the block cannot break an algebraic loop.
• Nonlinear and discontinuous, and deliberately carries no state space. The indices step rather than vary, so no A/B/C/D describes the block and model reduction correctly refuses it.
• The ranking is by value alone. Equal values are ordered by index, and nothing else breaks a tie – so the output is deterministic even when the scores are not distinct, which is the property a downstream switch depends on.
• At a near-tie the HDL targets can rank differently. They compare Q16.16 values, one quantum of which is about 1.5e-5, where the in-app run compares doubles – so two scores closer together than that can come out the other way round. Here that transposes two adjacent rows of both outputs rather than changing one number slightly. This is inherent to reducing a continuous quantity to a discrete ranking in fixed point, not a codegen defect: if your application must agree bit for bit with the simulation at a tie, separate the scores or rank downstream in floating point.