The Per-Set Activation profile_json and the updateFromActJsonFile Consumer

All paths, JSON values, addresses and symbols on this page apply to neuronx_cc 2.24.5133.0+58f8de22 (cp310; the neuronxcc/pwp/ tree is byte-identical across cp310/cp311/cp312). act_info.json md5 aa8ea33a5b7414695fa87ca890f50d6c. Other versions will differ.

Abstract

Every loadable activation set in neuronx_cc ships as three files: two binary blobs (<set>_bkt.bin, <set>_ctrl.bin) and one JSON manifest (<set>.json). This page documents that JSON manifest — the per-set combined profile_json — and the native code that reads it at NEFF-pack time. The manifest is not the activation numerics (those live one tier up, in pwp_jsons/<func>_Np.json, §10.1); nor is it the packed hardware LUT (that is the two blobs, §10.4). It is the index and denormalized control block that fuses every function co-resident in a set into one image: it names the two blobs, counts their entries, records where each function's data begins inside them (coarse and per-exponent-octave), and carries a 30-field scalar hardware-control record per function.

The schema is small and regular: a fixed 9 top-level keys, and a profile_meta_data[] array of exactly 30 fields per function. Both counts are invariant across all 35 shipped sets (21 pwp_bin_trainium + 14 pwp_bin_with_ln). The two index maps that every prior reverse-engineering pass deferred — func_exp_to_bkt_start_idx and func_exp_to_ctl_start_idx — are decoded here: they are per-octave region-base tables whose list length encodes the function's symmetry class (2 = asymmetric, 1 = symmetric/pos-only, 0 = the runtime-alpha parametric_relu).

The consumer story carries one sharp correction. The task that motivated this page named a lookup "FindActInfo." There is no C++ function symbol of that name; the per-set profile_json's keys (profile_meta_data, func_exp_to_*, …) appear in zero decompiled native bodies. What does exist is (a) a Cython module FindActInfo.cpython-3XX.so that merely locates the roster file act_info.json on disk, and (b) NeffFileWriter::updateFromActJsonFile in libwalrus, which matches the module's used set by name against the roster and embeds that set's binary blobs into the NEFF. Neither reads the per-set profile_json. The manifest is a build-time / simulator artifact — its denormalized control fields are baked into the blobs offline, and the runtime addresses functions by func_id against the resident tables, not by re-parsing JSON. See §5 and the GOTCHA there.

What a reimplementer must reproduce

• The 9-key top-level schema of <set>.json and the meaning of each key (§1).
• The 30-field profile_meta_data per-function record, field-by-field with types, and its mapping back to the per-function pwp_jsons schema (§3).
• The two index granularities: func_to_*_start_idx (coarse per-function base) and func_exp_to_*_start_idx (fine per-octave base), including the list-length-encodes-symmetry rule and the constant per-function pos/neg delta (§4).
• The join keys that wire the roster, the per-set profile, the per-function profile, and the two blobs together (§2).
• What the native consumer actually reads (the roster name + the binary blobs) versus what it ignores (the entire per-set profile) (§5).

At a glance

The page draws on the per-set schema decode in D-AG08 and the per-function numerics spec in D-M05.

1. The 9-key top-level schema

jq keys on any pwp_bin_{trainium,with_ln}/<set>.json gives exactly these 9 keys. The key set is verified identical across all 21 trainium + 14 with_ln per-set profiles (for f in *.json; do jq -c 'keys|sort' "$f"; done | sort -u yields a single line).

QUIRK — the three-way ctrl/ctl spelling skew. The control blob is referred to by three different spellings in three places: the roster act_info.json uses key ctrl_bin (with the r); the per-set profile uses key ctl_bin (no r); and the actual file is named <set>_ctrl.bin. Confirmed: exp_and_others.json's ctl_bin value is the string "exp_and_others_ctrl.bin", while act_info.json's set entry has key ctrl_bin. A reader keying off the wrong spelling will silently miss the field. The file-reference string value is authoritative — follow it, not the key name.

NOTE — no version field on the per-set profile. pwp_bin_*/version.json ships separately as {"KaenaPWP":{"brazil_version":"","git_sha":""}} (both fields blank, 80 bytes, both targets). The per-set profiles carry no version; provenance is owned by the roster/version file, not the manifest.

2. "Combined": how N functions share one image

The word combined in "per-set combined profile" means a single loadable set fuses multiple activation functions into one blob pair. The number of fused functions is the same everywhere:

len(profile_meta_data)  ==  |func_to_bkt_start_idx|  ==  |func_to_ctl_start_idx|
                        ==  act_info.json act:{} size for that set

For the exp_and_others set this is 15: the hero exp, plus tanh, plus the 13 always-resident "universal" functions (identity, relu, leaky_relu, parametric_relu, abs, sign, memset_zero, derivative_relu, derivative_leaky_relu, derivative_identity, is_finite, square, copy). Every co-resident function gets exactly one profile_meta_data entry, one func_to_* index, and one func_exp_to_* octave map.

Blob layout (the index points into these)

The two blobs are concatenations of per-function blocks, in act-array order; the per-set JSON is the index that locates each block:

bkt.bin  = [ func0_LUT_sections | func0_4_sat | func1_LUT | func1_4_sat | … ]
           func_to_bkt_start_idx[f] = entry index where func f's whole block starts.
           f's 4 saturation entries sit at the END of f's block, pointed at ABSOLUTELY
           by profile_meta_data[f].{pos,neg}_{small,large}_signal_pwl_control (§3F).

ctrl.bin = [ func0_neg_octaves | func0_pos_octaves | func1_octaves | … ]
           func_to_ctl_start_idx[f] = entry index where f's octave block starts
                                    = profile_meta_data[f].pwl_control_base_neg (§3E).
           f's pos octaves start at  profile_meta_data[f].pwl_control_base_pos.

Verified func_to_bkt_start_idx for the exp set: exp→0, identity→781, copy→785, leaky_relu→789, parametric_relu→793, abs→797, sign→801, memset_zero→805, relu→809, tanh→813, derivative_relu→921, derivative_leaky_relu→925, derivative_identity→929, is_finite→933, square→937. So exp's block spans 0..780 (781 entries = 777 LUT sections + 4 saturation clamps); each lut_size=0 resident occupies just 4 entries (its saturation-only block); square's block is 937..940, and 937 + 4 = 941 = bkt_entry_cnt. ✓

NOTE — self-contained set invariant. Every index inside a per-set profile is absolute within that set's own blobs — func_to_*_start_idx, func_exp_to_* values, pwl_control_base_*, and the four saturation pwl_control pointers all index this set's bkt/ctrl. A loaded set needs nothing else: {bkt blob} + {ctrl blob} + {per-func scalar meta} is complete. This is why the same function's bkt block is byte-identical across sets and targets — only the co-residency order and the ctrl stride differ; the per-set profile just re-indexes shared per-function data.

The pos/neg region split

A function that stores both a positive and a negative table (asymmetric, symmetry_opt_en=0 — exp, softplus, the derivatives) splits its block into a neg sub-block then a pos sub-block: pwl_control_base_pos > pwl_control_base_neg. A function that stores one table — symmetric (symmetry_opt_en=1: tanh, sign, sigmoid, …) or pos-only domain (sqrt, reciprocal, ln) — has base_pos == base_neg. The per-octave maps (§4b) encode this split octave by octave.

Join keys (how the maps cross-reference)

The budget-suffixed func_name is the pwp_jsons/<func>_Np.json filename stem — the link back to the per-function numerics (§10.1). The bare↔suffixed join is a prefix match (strip the trailing _<N>p).

3. The 30-field profile_meta_data record

profile_meta_data is an array with one entry per co-resident function, in act-array order. jq '[.profile_meta_data[]|keys]|unique' returns exactly 30 keys, identical across all 35 sets. The record is a denormalized, silicon-register re-expression of each function's pwp_jsons scalar config — the data the Activation engine programs into per-function control registers when the set is loaded.

The fields below are grouped by role; values are taken verbatim from the shipped exp_400p (asymmetric LUT) and sigmoid_40p (point-symmetric, store-neg) entries.

GOTCHA — every f*_result / *_bound / symmetry_point / fma_const_* is a raw IEEE-754 uint32 bit pattern, NOT a float. The JSON value is the integer reinterpretation of the 32-bit float. fpinf_result: 2139095040 is 0x7f800000 = +inf; fzero_result: 1065353216 is 0x3f800000 = 1.0. A reimplementer must bit_cast<float> these, never read them as decimals. The two *_exp_threshold / *_mantissa_threshold saturation fields are the exception — those are true integers, compared directly against the input's exponent/mantissa.

A. Identity (2 fields)

B. Special-value results (4 fields) — raw uint32 bit patterns

The per-set profile renames the per-function keys with an f prefix and flattens the per-function 6-field float-decomposition box down to its bare .int member (§10.1).

C. Symmetry fold (4 fields)

Confirmed values: exp = {0,0,0,0} → asymmetric, store both regions, evaluate signed v. sigmoid = {1,1,1, 1065353216} → point-symmetric: store neg, evaluate sel = −|v|, negate, add 1.0 ⇒ sigmoid(x) = 1 − sigmoid(−x). tanh = {1,1,0,0} → odd about origin: store pos, evaluate |v|, negate.

D. Input / octave bias (5 fields)

QUIRK — fma_indirection_src_sel=2 is the runtime-α tell. parametric_relu is the sole no-LUT path: it has an empty func_exp_to_* map, exp_offset=128, and fma_const_0=1.0. The fma_indirection_src_sel=2 selects the α/bias indirection register so the slope is supplied at runtime. (Meaning of the 2 is INFERRED from the prelu-only pattern; the exact silicon semantics are not in the wheel.)

E. PWL region pointers (2 fields) — absolute ctrl.bin octave-block bases

Verified: exp base_neg=0 / base_pos=26 (asymmetric: neg block first); tanh 64/64 (symmetric, single region); sigmoid 28/39 (store-neg). The delta base_pos − base_neg equals the per-octave ctl map element pair delta (§4b).

F. Saturation clamp thresholds + pointers (12 fields) — the 4-way clamp

Four signal regions {small,large} × {pos,neg}. The *_signal_exp_threshold and *_mantissa_threshold are true integers (exponent/mantissa comparison thresholds); the *_signal_pwl_control fields are absolute bkt indices of the clamp segment.

The four pwl_control pointers are consecutive (n, n+1, n+2, n+3) in bkt order [pos_small, neg_small, pos_large, neg_large] — they index the 4 saturation entries appended at the end of the function's bkt block (§2). Verified for exp: pos_small@777, neg_small@778, pos_large@779, neg_large@780 (the 4 clamps after exp's 777-section LUT), with large_pos_signal_exp_threshold=133, large_pos_signal_mantissa_threshold=3240472, large_neg_signal_mantissa_threshold=4362891. The map back to pwp_jsons.saturation_points: small ↔ *_low, large ↔ *_high; exp_threshold ↔ sat_point; mantissa_threshold ↔ mantissa_point.

NOTE — small_* field counts as 4, not 6. Group F is 12 fields total because the small regions have no mantissa_threshold (only exp_threshold + pwl_control), while the large regions add a mantissa_threshold. So: small×2 = 4 fields, large×2 = 6 fields, plus the 2 small pointers = 12. (Field arithmetic: A2 + B4 + C4 + D5 + E2 + F12 + G3 = 30. ✓)

G. Bounds + multipass (3 fields)

4. The index maps: func_to_* and func_exp_to_*

Two granularities address the blobs. The coarse one locates a function; the fine one locates one octave of one function. The fine maps are the part every prior reverse-engineering pass deferred to a later codegen report that never landed; they are decoded here from the shipped JSON.

4a. func_to_*_start_idx — the coarse per-function base

func_to_bkt_start_idx[f] = bkt entry index where func f's WHOLE block begins.
func_to_ctl_start_idx[f] = ctrl entry index where f's octave block begins
                         = profile_meta_data[f].pwl_control_base_neg.

In act-array order the blocks are contiguous, so func_to_bkt[f_{i+1}] − func_to_bkt[f_i] is f_i's total block size (LUT sections + 4 saturation). The exp-set func_to_ctl_start_idx is exp→0, identity→52, copy→54, leaky_relu→56, parametric_relu→58, abs→58, sign→60, memset_zero→61, relu→62, tanh→64, …, square→88 (and ctl_entry_cnt=89 = 88 + 1).

4b. func_exp_to_*_start_idx — the fine per-octave map

func_exp_to_{bkt,ctl}_start_idx[func][exponent] = [int, …]

Keyed by the input's unbiased exponent octave (a string, e.g. "-19" … "6" for exp). The value is a list of region start indices for that octave. The list length encodes how many physical regions the function stores — i.e. its symmetry class:

CORRECTION — func_exp is per-EXPONENT, not per-budget. Earlier passes loosely guessed the _exp in func_exp_to_* meant a multi-budget expansion (one entry per precision budget). It does not. No shipped function has multiple budgets in a set; the map is keyed by the input exponent octave, and the list elements are the neg/pos region split. The _exp is the float exponent.

Decoded bkt map — the value is the bkt section base for that octave (the same datum ctrl.bin bits [0:11] pack, pre-resolved). For exp (asymmetric, 2-element):

func_exp_to_bkt_start_idx.exp["-19"] = [0,   406]
                              ["-1"]  = [18,  424]
                              ["0"]   = [20,  426]
                              ["6"]   = [272, 678]

• element[0] = cumulative bkt offset of octave E within the neg block (octaves -19..-1 each have nsec=1 ⇒ +1 each: -19→0 … -1→18; then density doubles toward the origin as num_sections = 2^extract_size grows — §10.1).
• element[1] = element[0] + 406. The neg block spans 406 bkt entries; the pos block starts at +406. This delta is constant across all octaves of the function (it equals the neg block size). Verified: every exp octave has pos − neg == 406.

Decoded ctl map — the value is the octave's own ctrl-word index (one ctrl word per octave):

func_exp_to_ctl_start_idx.exp["-19"] = [0,  26]
                              ["-1"]  = [18, 44]
                              ["0"]   = [19, 45]
                              ["6"]   = [25, 51]

• element[0] = E − exp_offset (one consecutive ctrl word per neg octave: -19→0 … 6→25).
• element[1] = element[0] + 26, where 26 = pwl_control_base_pos − pwl_control_base_neg. Constant per function.

So the two constant deltas have clean meanings: the ctl delta = base_pos − base_neg; the bkt delta = the neg LUT block size. Both are confirmed constant across all of a function's octaves.

Single-region (listlen=1) examples (verified): func_exp_to_bkt.tanh["-14"]=[813], func_exp_to_ctl.tanh["-14"]=[64] (one index, the pos region; evaluated on |v|, negated). func_exp_to_bkt.tanh["-13"]=[814], [65] (octaves advance by one). parametric_relu's map is {} in both func_exp_to_bkt and func_exp_to_ctl.

NOTE — why two granularities. func_to_*_start_idx gives the function's coarse block base (used to locate the function plus its 4 saturation entries). func_exp_to_*_start_idx gives the per-octave base — the same information ctrl.bin holds in packed form, but pre-decoded into JSON so a build tool or simulator can read it without unpacking the u32. The bkt variant pre-resolves the section base; the ctl variant gives the octave's ctrl-word slot. The first key of func_exp_to_*[f] always equals exp_offset (§3D) = pwp_jsons.exponent_offset.

5. The consumer: "FindActInfo," the roster locator, and updateFromActJsonFile

The task that motivated this page named a runtime lookup "FindActInfo" that supposedly walks an op's activation function → its profile entry → the blobs. No such C++ function exists, and nothing native reads the per-set profile_json. Three distinct mechanisms realize the "find the activation info" idea, and none of them parse the manifest documented above.

GOTCHA — FindActInfo is a Python file-locator, not a profile reader; and there is no C++ symbol of that name. A symbol sweep finds zero native functions named FindActInfo (no _Z…FindActInfo…E, nothing in any IDA functions.json/names.json). What does ship is a Cython extension neuronxcc/driver/jobs/support/FindActInfo.cpython-3XX.so. nm -C on it exposes only PyInit_FindActInfo, findActInfoFile, and findDVEInfoFile. Its entire data-string vocabulary is act_info.json, dve_info.json, pwp_bin, dve_bin_gen{2,3,4,5}, and the error "Unable to locate act_info.json in …". It references none of the per-set profile keys — strings … | rg 'profile_meta_data|func_exp_to|bkt_entry_cnt|ctl_entry_cnt' returns nothing. FindActInfo locates the roster file on disk; it never opens a per-set profile.

5a. Compile-time lookup — fillAllActInfos (reads the roster, not the profile)

neuronxcc::backend::LowerPWPImpl::fillAllActInfos @ 0x115af90 (libwalrus) parses act_info.json — its decompiled body reads the literals act_func_sets, name, act, tables, binary — and builds an AllActSetName2ActInfo map (llvm::MapVector<string, ActFuncSetInfo, …>). The op-set lookup is generateInstLoadActFuncSet @ 0x1156510 doing AllActSetName2ActInfo[setName] → an unsigned set index → instruction field +0xF0. This resolves which set an op's activation function belongs to. It reads only the roster act_info.json. The per-set profile's keys (profile_meta_data, bkt_entry_cnt, func_exp_to_*) appear in zero decompiled bodies across the corpus.

GOTCHA — the per-set profile_json is never parsed by the compiler's lowering path. It is a build-time / simulator artifact. The numeric simulator reads the per-function pwp_jsons (§10.1); the per-set profile is the blob manifest, consumed at NEFF-pack time (§5b) and by the offline table generator that produced the blobs. Its 30 denormalized control fields are baked into bkt/ctrl offline, not read at op time.

5b. NEFF-pack — updateFromActJsonFile (CONFIRMED, real body)

neuronxcc::backend::NeffFileWriter::updateFromActJsonFile @ 0x1542db0 (libwalrus; 707-line decompiled body) is the actual "find the act info and embed it" routine. Annotated pseudocode of what it reads — the roster name and the binary blobs, never the profile:

// NeffFileWriter::updateFromActJsonFile @ 0x1542db0  (libwalrus)
// Embeds the module's USED activation set's binary tables into the NEFF BOM.
void NeffFileWriter::updateFromActJsonFile(const std::string &actJsonPath,
                                           const std::string &usedActSet) {
    // (1) Load the act JSON (the ROSTER, act_info.json). Loaded via bir::loadJsonFile.
    json root = bir::loadJsonFile(actJsonPath);            // lines 128 / 152

    // (2) Walk act_func_sets[], matching each set's "name" node against usedActSet.
    std::optional<json> matchedActInfoJson;               // the "FindActInfo" result
    for (json &set : root["act_func_sets"]) {
        json probe;  strcpy(probeKey, "name");            // line 327 builds {"name": …}
        if (operator==(set["name"], usedActSet)) {        // nlohmann ==, line 391
            matchedActInfoJson = set;                     // capture on match
            break;
        }
    }

    // (3) GATE: no matching set name → hard error. errorcode 1228.
    //     assert matchedActInfoJson.has_value(); else NeuronAssertion<ErrorCode>(…1228…)
    //     cause/resolution strings keyed on "usedActSet"  (lines 276 / 320 / 321)
    if (!matchedActInfoJson.has_value())
        throw_with_nested(NeuronAssertion(1228, /* "Unable to find used act set" */));

    // (4) For each entry whose value is the nlohmann BINARY tag (type 8) — the bkt/ctrl
    //     blobs — read the blob and add it to the NEFF Bill-of-Materials.
    for (auto &[key, val] : matchedActInfoJson->items())
        if (val.type() == json::value_t::binary)          // type 8
            this->addToBom(key, val.get_binary());        // lines 180 / 647

    this->actTablesEmbedded = 1;                          // *(v60+212) = 1, line 699
}

What this confirms, key by key:

• Match key = the set name (string), compared against usedActSet (the set the compiled module actually used). On mismatch the routine throws with error code 1228 — a loud, deterministic failure rather than silent fall-through.
• Payload embedded = entries tagged binary (nlohmann type 8) — the bkt/ctrl blobs. They are added to the NEFF BOM via addToBom so the runtime can DMA-load them on LoadActFuncSet. The NEFF feature flag that gates dynamic embedding of these tables is documented in §12.5.
• Not read: bkt_entry_cnt, ctl_entry_cnt, func_to_*, func_exp_to_*, or any profile_meta_data field. The routine consumes the roster's name + binary tables only.

5c. Runtime addressing — no profile read at op time

Once a set is resident, an Activation op (opcode 0x21) names its function by func_id (the silicon LUT code = profile_meta_data[f].func_id, §3A), packed into the encoded bundle wire byte +0x23 — the same selector slot the LoadActFuncSet uses for its set index (10.6 §1/§2). The engine resolves func_id against the currently-resident set's tables, located at the func_to_*_start_idx offsets baked into the blobs.

NOTE — +0x23 is the bundle wire byte, not an InstActivation IR-struct offset. The func code reaches the engine in encoded-bundle byte +0x23 (the 64-byte compute word's activation-table/function selector slot); on the in-memory InstActivation IR object the ActivationFunctionType lives at +0x90/+0x120 (10.2 §1, 10.6 §1), and the silicon LUT func_id is supplied through the 31-entry func-remap at encode time. Do not read +0x23 as a field offset of the BIR instruction struct.

No per-set profile_json is opened at op time: the manifest's job — binding func_id to blob offsets plus the 30 control fields — was performed once, offline, when the blobs were generated.

6. The tie to the blobs: profile = manifest, blobs = packed tables

The per-set profile_json and the bkt/ctrl blobs (§10.4) are two views of the same data. The profile is the human-readable index; the blobs are the packed tables.

A reimplementer needs both: the per-set profile (this page) gives the function→offset + control metadata and the symmetry/special/saturation semantics; the blobs give the raw 32-byte poly coefficients and the packed octave words. The Activation engine loads the blobs (LoadActFuncSet, opcode 0x23) and programs the per-function control registers from the profile's scalar fields, denormalized at build time into the engine's control microcode.

7. Confidence summary

GOTCHA — the offline table generator is not in the wheel. The build-time tool that consumes the per-function pwp_jsons and emits the per-set profile + bkt/ctrl blobs ships nowhere in the wheel. The denormalization rules (field renames, the 4-way saturation-pointer packing, the per-octave func_exp computation) are inferred from the output, not read from the generator. A reimplementer can reproduce the runtime and NEFF-pack behavior exactly from the shipped artifacts; reproducing the generator requires deriving these rules from the patterns documented in §3–§4.

Sources: per-set schema decode and the libwalrus consumer (D-AG08); per-function PWP numerics spec (D-M05). Cross-references: the polynomial activation model (§10.1); the bkt/ctrl blob layout (§10.4); NEFF feature flags (§12.5).