Nvshmem Configure Nic Pe Mapping

NVIDIAOfficialCreated by NVIDIA NVSHMEM Team

Skill
Workflow
Software development
Apache-2.0
Medium risk
Has scripts

From the author

Recommend NVSHMEM NIC-to-PE mappings and environment exports. Use for HCA selection, multi-NIC configuration, or topology-based mapping diagnostics.

— the description by NVIDIA NVSHMEM Team

From the skill’s files

Taken from the skill’s own files (its description, section headings and stated usage). Not an AutoGineer summary, and not written by the author as one.

Recommend NVSHMEM NIC-to-PE mappings and environment exports. Use for HCA selection, multi-NIC configuration, or topology-based mapping diagnostics. Produce a reproducible recommendation from the target node's actual GPU/NIC topology. Do not promise a performance improvement; present the mapping as a topology-informed starting point that must be validated.

What it does

Purpose
Requirements
Inputs
Scripts
Read the Required References
Instructions

When to use it

Use for HCA selection, multi-NIC configuration, or topology-based mapping diagnostics.

Advantages

The skill’s files do not state this.

Usage examples

“My 4 local PEs are bound to GPUs 0–3. Given this target-node collector output and NVSHMEM 3.8.0 IBRC, recommend the closest balanced InfiniBand port mapping and exact exports.”: The agent follows the skill's steps for this request, as the skill's files describe.
“We have 2 PEs and 5 active Ethernet/RoCE ports. Use this PE-to-GPU binding and initialization log to show the supported subset and multi-NIC alternatives without selecting one silently.”: The agent follows the skill's steps for this request, as the skill's files describe.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/nvidia/nvshmem-configure-nic-pe-mapping/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip nvshmem-configure-nic-pe-mapping.zip -d .agents/skills

Documentation by NVIDIA NVSHMEM Team

Tune NVSHMEM NIC-to-PE Mapping

Purpose

Produce a reproducible recommendation from the target node's actual GPU/NIC topology. Do not promise a performance improvement; present the mapping as a topology-informed starting point that must be validated.

Requirements

Use an allocated target compute node with visible GPUs and RDMA devices; do not use login-node topology as evidence.
Make nvidia-smi and /sys/class/infiniband readable on that node. If /sys is unavailable, make ibv_devinfo available or provide equivalent per-port evidence.
Provide the NVSHMEM installation prefix, make nvshmem-info available on the target node, or supply the installed NVSHMEM version explicitly.
Use the bundled read-only collector when possible. It requires no API keys, credentials, package installation, or writable filesystem access.

Inputs

Resolve every required input before emitting exact exports. If values from different sources conflict, identify the conflict and request clarification rather than selecting a value silently.

Required inputs

NVSHMEM version: Prefer the user-confirmed installed version; otherwise use the collector's [nvshmem-version] output, then nvshmem-info -n on the target node. Retain the complete reported version after normalizing a leading v.
Remote transport: Prefer the explicitly selected transport for the target run; otherwise use the target node's NVSHMEM initialization log. Do not infer a transport from topology; request a log when automatic selection is ambiguous.
Local PE count: Prefer observed per-rank logs, then launcher configuration, then an explicit user-provided count. Confirm that all evidence describes the same node allocation.
Ordered local PE -> GPU index or PCI BDF binding: Prefer observed per-rank binding logs, then launcher binding configuration, then an explicit user mapping. Use CUDA_VISIBLE_DEVICES only when its rank order is explicitly established.
Target-node GPU/NIC and HCA-port topology: Prefer the newest complete output from scripts/collect-nic-topology.sh on the target node. Otherwise use the listed nvidia-smi commands plus per-port /sys/class/infiniband or ibv_devinfo evidence. Include GPU and NIC PCI BDFs, port state, and link layer.

Optional inputs

Requested link layer: Use the user's explicit InfiniBand or Ethernet/RoCE preference. If absent, choose from observed active ports as described in step 5.
Excess-port policy: Use the user's explicit request to select a closest subset or use multiple NICs per PE. If absent, present supported alternatives conditionally and make no selection.
Current official documentation or citations: Obtain only when the user requests them or the version/transport matrix is insufficient. Use $nvshmem-docs for that check.

Scripts

Script	Use	Invocation
`scripts/collect-nic-topology.sh`	Collect read-only NVSHMEM version, GPU PCI, GPU/NIC topology, and RDMA-port evidence. It emits all evidence to stdout and may exit nonzero after producing useful partial output.	Resolve the script from this skill directory and invoke `run_script("scripts/collect-nic-topology.sh", "--prefix", "/absolute/nvshmem/prefix")` when the prefix is known, or omit `--prefix` to use environment/PATH discovery.

Read the Required References

Read references/version-transport-matrix.md before interpreting or emitting any mapping variable.
Read references/topology-and-output.md before ranking NICs or formatting a recommendation.
Treat the bundled NVSHMEM 3.8 or later BLOCK contract as authoritative within its recorded transport scope. Do not invoke $nvshmem-docs merely to revalidate behavior that this contract resolves, including for releases later than 3.8.

Instructions

1. Resolve the NVSHMEM Version and Transport

Obtain the version from the user first. Otherwise use the collector's [nvshmem-version] evidence or run nvshmem-info -n when it is already available on the target node. Normalize a leading v and retain the complete reported version.

Classify the release as:

3.7 or earlier;
3.8 or later.

Do not assume latest or silently treat an unknown version as 3.8. If the version remains unknown, request the installed version before continuing.

Determine the selected remote transport: IBRC, IBDevX, IBGDA, GPUNetIO, UCX, or libfabric. If automatic selection makes the transport ambiguous, ask for the relevant initialization log or the intended transport.

2. Resolve Documentation Uncertainty

Use references/version-transport-matrix.md as the default authority for mapping behavior. Do not invoke $nvshmem-docs when the matrix or the bundled NVSHMEM 3.8 or later BLOCK contract resolves the version, transport, feature gate, and required mapping controls, including for a release later than 3.8.

Invoke the sibling $nvshmem-docs skill at ../nvshmem-docs/SKILL.md only when the matrix and bundled contract are insufficient or conflicting, exact feature-version applicability remains unclear, or the user explicitly requests live official documentation or citations. Follow that skill's version and citation workflow.

If a documentation check is needed but the sibling skill, an HTTPS retrieval tool, or the live official pages are unavailable:

continue from the matrix only when it resolves the needed behavior;
otherwise withhold final exports and identify the unresolved behavior;
label Documentation freshness: unverified only when a documentation check was attempted;
state which official routes could not be checked; and
never invent a behavior that the matrix does not establish.

When a documentation check is performed, report the exact documentation edition consulted and any remaining uncertainty. Otherwise identify the applicable matrix section as the basis for the recommendation.

3. Collect Topology Evidence

When already running on the target compute node, tell the user that the skill is running a read-only collector. Before its first invocation in the current checkout, inspect the complete bundled collector script. Run only that inspected file; if it is unavailable or incomplete, do not execute it. Then run:

run_script("scripts/collect-nic-topology.sh")

When the NVSHMEM installation prefix is known, pass its absolute path explicitly:

run_script("scripts/collect-nic-topology.sh", "--prefix", "/opt/nvshmem")

Replace the example path with the absolute prefix. Without --prefix, discovery uses NVSHMEM_PREFIX, then nvshmem-info on PATH. Prefix libraries are scoped to that query. Exit 2 indicates incomplete evidence.

When not on the target node, ask the user for the collector's complete output from the target node. If the script is unavailable remotely, request all of:

nvshmem-info -n
nvidia-smi --query-gpu=index,pci.bus_id,name --format=csv,noheader
nvidia-smi topo -m

Also request, for every candidate HCA port, its HCA name, port number, PCI BDF, state, and link layer from /sys/class/infiniband or ibv_devinfo.

Do not run a collector from a login node and treat that topology as compute-node evidence.

4. Establish PE Placement

Obtain the number of local PEs per node. Assume nodes are homogeneous only after stating that assumption.

Obtain the ordered local PE -> GPU index or PCI BDF binding from explicit user input, launcher configuration, CUDA_VISIBLE_DEVICES, or per-rank logs. Do not infer a local PE's GPU solely from PE count or the order displayed by nvidia-smi topo -m.

If the binding is ambiguous, request it before producing an exact closest-NIC mapping. A conditional table is acceptable, but final exports are not. Do not bypass the missing binding by duplicating every usable NIC for every PE; that adds non-closest paths and is a different multi-port policy. Consider such an all-ports assignment only after the user explicitly requests it and accepts the distance tradeoff.

5. Filter and Rank Candidate Ports

Treat an HCA port, not merely an HCA device, as the selectable NIC unit.

Exclude inactive or physically down ports and record why each was excluded.
Partition active ports by link layer. Do not mix InfiniBand with Ethernet/RoCE by default.
Honor an explicitly requested link layer. Otherwise choose the larger active partition; prefer InfiniBand on an exact tie. Ask the user if that default conflicts with their fabric or provider intent.
Rank each bound GPU-to-port pair by PIX < PXB < PHB < NODE < SYS from nvidia-smi topo -m.
Break equal-distance choices by lower assigned-port load, then canonical hca:port order.
Share a port when fewer usable ports than PEs makes sharing necessary, while preserving distance first and balance second.

6. Resolve Excess NICs Explicitly

When usable NIC ports outnumber local PEs, stop before final exports and ask whether to:

select the closest balanced subset; or
use multiple NICs per PE.

Offer option 2 only when the resolved version and transport support it according to the matrix. Explain whether multi-NIC requires automatic distance assignment or supports an explicit BLOCK mapping. If the user does not answer, show both supported alternatives as conditional recommendations and do not choose silently.

If the user asked to use all NICs but the resolved version/transport does not support multi-NIC, explain the restriction and request approval to use the closest subset. Do not treat the unsupported request as implicit approval for a subset, and do not emit final exports until the user confirms it. When only the subset is supported, present that single supported choice for confirmation instead of offering a disabled multi-NIC option.

7. Synthesize Exactly One Selection Mechanism

Prefer NVSHMEM_HCA_PE_MAPPING for exact assignments. Use NVSHMEM_HCA_LIST only when selecting an eligible set and accepting transport-canonical ordering. Never set both variables.

Apply the version/transport rules in the matrix exactly:

For 3.7 and earlier, preserve one expanded mapping slot per PE for explicit IB mappings. Use automatic distance assignment for supported multi-NIC paths.
For 3.8 or later, apply the bundled BLOCK contract: set NVSHMEM_ENABLE_NIC_PE_MAPPING=1 for explicit assignments and NVSHMEM_ENABLE_MULTI_PORT=1 whenever recommending more than one NIC per PE.
For UCX and libfabric, explain the provider-controlled boundary and do not fabricate common-HCA exact mappings.

Build NVSHMEM_HCA_PE_MAPPING with explicit hca:port:count entries. Expand every count before explaining which slots each PE receives. Preserve duplicates when intentional sharing is required.

Keep a mapping-only export block limited to NIC-assignment controls. Do not add NVSHMEM_REMOTE_TRANSPORT or provider/launcher settings merely because the transport is known; include them only when the user separately asks to select the transport and the matrix, or documentation when needed, verifies the value.

8. Return the Recommendation

Execute the Output Contract in order; that reference is the single authority for output fields, formatting, withholding messages, and validation guidance.

Treat its Mapping and Exact Exports sections as mandatory gates. Do not return until each gate is either completed or explicitly withheld for the reason allowed by the contract. Do not duplicate or paraphrase the contract in this file.

Examples

“My 4 local PEs are bound to GPUs 0–3. Given this target-node collector output and NVSHMEM 3.8.0 IBRC, recommend the closest balanced InfiniBand port mapping and exact exports.”
“Interpret this nvidia-smi topo -m and per-port state/link-layer output. NVSHMEM is 3.7 with IBGDA; identify whether multiple NICs per PE are supported and what extra evidence is needed before emitting exports.”
“We have 2 PEs and 5 active Ethernet/RoCE ports. Use this PE-to-GPU binding and initialization log to show the supported subset and multi-NIC alternatives without selecting one silently.”

Troubleshooting

Symptom	Response
The collector reports `status=partial`, an unknown NVSHMEM version, missing GPUs, or no HCA ports.	Re-run it on an allocated target compute node with the intended NVSHMEM installation and NVIDIA/RDMA device visibility. Paste the complete labeled output; a nonzero exit may still contain usable evidence.
No exact mapping can be produced.	Obtain the NVSHMEM version, resolved remote transport, local PE-to-GPU binding, and active-port evidence. Give only conditional guidance until all are available.
Ports have mixed link layers or a requested port is inactive.	Exclude inactive ports and select one link-layer partition unless the user explicitly requests another supported fabric.
NVSHMEM behavior is unclear for the selected version or transport.	Check the version/transport matrix first, then invoke `$nvshmem-docs` only if it remains insufficient or the user requires current official citations.
Logs select unexpected ports after applying the mapping.	Verify the export block, PE binding, selected transport, and provider constraints; compare against the unforced automatic configuration before changing other settings.

Limitations

Limit recommendations to the observed target-node topology and port state; repeat evidence collection after hardware, fabric, launcher, or binding changes.
Treat topology proximity as a selection heuristic, not a performance guarantee; validate with a representative workload.
Do not produce an exact mapping until the NVSHMEM version, transport, local PE-to-GPU binding, and usable-port evidence are resolved.
For UCX and libfabric, remain within the provider-controlled boundary and do not fabricate common-HCA mapping settings.

Guardrails

Do not select inactive ports or silently mix link layers.
Do not assume that a numerically matching GPU and NIC index implies proximity.
Do not turn an unknown PE-to-GPU binding into an all-ports-per-PE mapping.
Do not emit 3.8-or-later BLOCK behavior for 3.7 or earlier.
Do not emit legacy IBGDA multi-port controls as the primary 3.8-or-later control.
Do not generate provider-native UCX or libfabric settings; explain them without inventing values.
Do not overwrite user files or change the system while collecting evidence.

Files

ATTRIBUTION.mdAdded by AutoGineer967 B
BENCHMARK.md10.7 KiB
LICENSELicence file added by AutoGineer11.2 KiB
SKILL.md14.7 KiB
evals/evals.json15.9 KiB
evals/files/ambiguous-two-gpu-two-ib.txt448 B
evals/files/four-gpu-four-ib.txt1.1 KiB
evals/files/four-gpu-two-ib.txt618 B
evals/files/mixed-link-inactive.txt829 B
evals/files/two-gpu-five-ib.txt817 B
evals/files/two-gpu-four-ib.txt840 B
references/topology-and-output.md11.0 KiB
references/version-transport-matrix.md11.1 KiB
scripts/collect-nic-topology.shScript8.2 KiB
skill-card.md3.9 KiB
skill.oms.sig6.7 KiB

evals/evals.json

{
  "skill_name": "nvshmem-configure-nic-pe-mapping",
  "evals": [
    {
      "id": "nvshmem-configure-nic-pe-mapping-001",
      "prompt": "Use the attached topology to tune NVSHMEM 3.7.0 IBRC. There are four local PEs bound in order to GPU0, GPU1, GPU2, and GPU3. I want one closest InfiniBand port per PE.",
      "files": ["evals/files/four-gpu-four-ib.txt"],
      "expected_output": "The agent recommends one explicit expanded slot per PE in local-PE order and explains the 3.7 modulo interpretation.",
      "assertions": [
        "The agent invokes nvshmem-docs or explicitly reports why live documentation could not be verified",
        "The mapping pairs PE0..PE3 with their PIX mlx5_0..mlx5_3 ports and emits NVSHMEM_ENABLE_NIC_PE_MAPPING=1 plus NVSHMEM_HCA_PE_MAPPING",
        "The agent does not emit NVSHMEM_ENABLE_MULTI_PORT or assign multiple NICs to a 3.7 IBRC PE"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-002",
      "prompt": "For NVSHMEM 3.7.0 IBDevX, use this topology with two PEs bound PE0->GPU0 and PE1->GPU1. Four InfiniBand ports are active; use all of them if supported.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent explains that 3.7 IBDevX does not support multi-NIC per PE and asks the user to confirm the closest-subset choice before finalizing.",
      "assertions": [
        "The agent does not apply the 3.8 BLOCK contract to NVSHMEM 3.7",
        "The agent offers only a supported one-port-per-PE closest subset and does not fabricate an IBDevX multi-port control",
        "The two unselected active ports are reported rather than silently ignored"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-003",
      "prompt": "Tune NVSHMEM 3.7.0 IBGDA for the attached two-GPU/four-IB-port node. PE0 uses GPU0 and PE1 uses GPU1. I explicitly want multiple closest ports per PE.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent enables 3.7 IBGDA automatic multi-port selection and distinguishes predicted ports from runtime-selected ports.",
      "assertions": [
        "The exports set NVSHMEM_ENABLE_NIC_PE_MAPPING=0 and NVSHMEM_IBGDA_ENABLE_MULTI_PORT=1",
        "The agent does not set NVSHMEM_HCA_PE_MAPPING, NVSHMEM_HCA_LIST, or the 3.8 common multi-port variable",
        "The agent explains that exact explicit multi-NIC assignment is unavailable for 3.7 IBGDA"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-004",
      "prompt": "Use the attached topology for NVSHMEM 3.7.0 GPUNetIO with PE0 on GPU0 and PE1 on GPU1. Enable the transport to consume multiple topology-selected NICs.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent recommends automatic NIC assignment for 3.7 GPUNetIO and avoids an exact multi-slot mapping.",
      "assertions": [
        "The exports set NVSHMEM_ENABLE_NIC_PE_MAPPING=0 and do not include either HCA selection variable",
        "The agent does not invent a GPUNetIO-specific or 3.8 common multi-port variable",
        "The answer says runtime transport logs must confirm the automatically consumed NICs"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-005",
      "prompt": "On NVSHMEM 3.7.0 libfabric, two local PEs are bound PE0->GPU0 and PE1->GPU1 on this four-NIC node. Limit each PE to two provider-selected NICs.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent preserves libfabric provider/automatic selection and emits only its documented per-PE maximum when verified.",
      "assertions": [
        "The answer uses NVSHMEM_LIBFABRIC_MAX_NIC_PER_PE=2 only if documentation verifies it",
        "The agent does not generate NVSHMEM_HCA_PE_MAPPING or NVSHMEM_HCA_LIST for libfabric",
        "The answer distinguishes a topology prediction from provider-controlled selection"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-006",
      "prompt": "Can you create an exact NVSHMEM 3.7.0 UCX HCA-to-PE mapping from this topology? PE0 is GPU0 and PE1 is GPU1.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent explains that UCX controls NIC selection internally and declines to fabricate a common-HCA exact mapping.",
      "assertions": [
        "The agent does not emit NVSHMEM_HCA_PE_MAPPING, NVSHMEM_HCA_LIST, or invented UCX environment values",
        "The answer may show the topology prediction but clearly labels it non-enforcing",
        "The answer invokes the documentation workflow for the 3.7 UCX applicability claim"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-007",
      "prompt": "For published NVSHMEM 3.8.0 IBRC, use all four active InfiniBand ports on this two-PE node. PE0 is GPU0 and PE1 is GPU1. I explicitly choose multiple NICs per PE.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent creates two contiguous expanded slots per PE using the 3.8 BLOCK contract and emits the common multi-port controls.",
      "assertions": [
        "The answer emits the mandatory mapping table with PE, GPU PCI BDF, HCA port, NIC PCI BDF, topology distance, and sharing/load notes",
        "The mapping gives PE0 mlx5_0 and mlx5_1 and PE1 mlx5_2 and mlx5_3 with the complete four-slot expansion",
        "One exact fenced shell export block includes NVSHMEM_ENABLE_NIC_PE_MAPPING=1, NVSHMEM_ENABLE_MULTI_PORT=1, and only NVSHMEM_HCA_PE_MAPPING",
        "The answer shows base=2, rem=0 and the slot range for each PE"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-008",
      "prompt": "Tune published NVSHMEM 3.8.0 IBDevX with this five-port topology. PE0 is GPU0, PE1 is GPU1, and I choose exact multi-NIC mapping using every active InfiniBand port.",
      "files": ["evals/files/two-gpu-five-ib.txt"],
      "expected_output": "The agent applies 3.8 uneven BLOCK remainder distribution, assigning three slots to PE0 and two to PE1.",
      "assertions": [
        "The answer emits the mandatory mapping table with one row per PE-port assignment and all required BDF, distance, and sharing/load columns",
        "The answer expands all five slots and shows base=2, rem=1, PE0 count=3, and PE1 count=2",
        "The slots are grouped contiguously by local PE and minimize the supplied GPU-to-NIC distances subject to the quotas",
        "One exact fenced shell export block enables both explicit mapping and common multi-port without HCA_LIST"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-009",
      "prompt": "For published NVSHMEM 3.8.0 IBGDA, use NVSHMEM_HCA_LIST as a set-based filter for these five canonical active ports on two local PEs, PE0->GPU0 and PE1->GPU1. Explain exactly what happens.",
      "files": ["evals/files/two-gpu-five-ib.txt"],
      "expected_output": "The agent explains HCA_LIST canonical ordering, removes the fifth trailing slot, and gives two BLOCK slots per PE.",
      "assertions": [
        "The answer computes usable=4, warns that the fifth canonical port is removed, and shows the two-port blocks",
        "The exports include explicit mapping and common multi-port plus HCA_LIST, but not HCA_PE_MAPPING",
        "The answer explains why HCA_LIST is set-based rather than an exact arbitrary PE order"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-010",
      "prompt": "Use published NVSHMEM 3.8.0 GPUNetIO on this four-GPU/two-port node. Local PEs map in GPU order. Give each PE its closest port even though ports must be shared.",
      "files": ["evals/files/four-gpu-two-ib.txt"],
      "expected_output": "The agent creates four expanded slots with intentional duplicate ports so each PE has an exact one-slot assignment.",
      "assertions": [
        "The mapping contains E=4 expanded slots for N=4 PEs even though only two physical ports exist and explains the intentional duplicates",
        "The answer applies the preserved E<=N one-slot case rather than a multi-port BLOCK assignment",
        "The exports contain only explicit mapping controls and do not require NVSHMEM_ENABLE_MULTI_PORT=1 for one port per PE"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-011",
      "prompt": "I use NVSHMEM 3.8.0 UCX with two PEs, PE0->GPU0 and PE1->GPU1. Generate the exact HCA mapping from this topology.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent keeps UCX outside the 3.8 common BLOCK contract and does not generate unsupported HCA controls.",
      "assertions": [
        "The agent explicitly says the attached 3.8 contract excludes provider-native UCX selection",
        "No exact HCA or invented provider-native exports are emitted",
        "The answer provides validation/log guidance or a non-enforcing proximity table"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-012",
      "prompt": "For NVSHMEM 3.8.0 libfabric on this two-PE/four-NIC node, create a BLOCK HCA_PE_MAPPING with two NICs per PE.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent rejects the requested common BLOCK mapping because libfabric remains provider controlled.",
      "assertions": [
        "The agent does not apply the common 3.8 HCA BLOCK contract to libfabric",
        "The answer explains that only documented provider/automatic controls such as a verified maximum can be recommended",
        "The agent does not invent provider-native values"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-013",
      "prompt": "Tune published NVSHMEM 3.8.0 IBRC from this mixed-link topology. Two local PEs are PE0->GPU0 and PE1->GPU1. I did not select a link layer.",
      "files": ["evals/files/mixed-link-inactive.txt"],
      "expected_output": "The agent excludes the down port, separates Ethernet from InfiniBand, and uses InfiniBand as the default on an active-port-count tie.",
      "assertions": [
        "mlx5_2 is excluded as inactive and mlx5_3/mlx5_4 are excluded from the default assignment as Ethernet",
        "The answer does not mix InfiniBand and Ethernet and states that Ethernet alone does not prove RoCE readiness",
        "The mandatory mapping table uses the active closest InfiniBand ports, includes every required column, and the answer lists all exclusions"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-014",
      "prompt": "NVSHMEM 3.8.0 IBRC uses two PEs on the attached node, but my launcher may swap GPU0 and GPU1 between local ranks. Please give me the exact closest-NIC exports now.",
      "files": ["evals/files/ambiguous-two-gpu-two-ib.txt"],
      "expected_output": "The agent requests the ordered local PE-to-GPU binding and withholds final exact exports because either ordering changes the mapping.",
      "assertions": [
        "The agent does not infer PE order from nvidia-smi output or numeric indices",
        "The answer asks for launcher, CUDA_VISIBLE_DEVICES, or per-rank binding evidence",
        "Any mapping shown is explicitly conditional and not presented as final exports",
        "The agent does not bypass the ambiguity by assigning both NICs to both PEs or by adding NVSHMEM_REMOTE_TRANSPORT"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-015",
      "prompt": "I have this topology and two local PEs bound PE0->GPU0 and PE1->GPU1, but nvshmem-info is unavailable and I do not know the installed NVSHMEM version. Tune IBRC for me.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent requests the installed version and gives only version-conditional guidance without final exports.",
      "assertions": [
        "The agent does not assume latest or silently use the 3.8 contract",
        "The answer explains the material 3.7-versus-3.8 difference",
        "The agent withholds final environment exports until the version is resolved"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-016",
      "prompt": "This isolated cluster has NVSHMEM 3.9.0 IBRC, no internet access, and no nvshmem-docs installation. PE0 is GPU0 and PE1 is GPU1 in the attached topology. Recommend a mapping without guessing changes made after 3.8.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent applies the bundled NVSHMEM 3.8 or later BLOCK contract to 3.9 without invoking nvshmem-docs, then resolves or requests the excess-port policy before final exports.",
      "assertions": [
        "The agent does not invoke nvshmem-docs merely because the installed version is 3.9.0 and identifies the bundled contract as covering NVSHMEM 3.8 or later",
        "The agent does not invent variables, defaults, or semantics outside the bundled contract",
        "Because four usable ports outnumber two PEs, the answer requests or resolves closest-subset versus multi-port intent before emitting final exports"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-017",
      "prompt": "Using the current/latest official NVSHMEM docs, verify the variables and tune my installed published NVSHMEM 3.8.0 IBRC. Use the closest subset for PE0->GPU0 and PE1->GPU1 from this topology.",
      "files": ["evals/files/two-gpu-four-ib.txt"],
      "expected_output": "The agent invokes nvshmem-docs because the user explicitly requested current official documentation, reports the displayed edition, and recommends the closest one-port subset under the NVSHMEM 3.8 or later BLOCK contract.",
      "assertions": [
        "The agent invokes the sibling nvshmem-docs workflow and fetches live official environment-variable and release evidence",
        "The answer reports the exact documentation edition consulted and distinguishes it from installed 3.8.0",
        "The mandatory mapping table contains all required columns and the exact fenced export block uses HCA_PE_MAPPING, never both HCA selection variables"
      ],
      "expected_skill": "nvshmem-configure-nic-pe-mapping",
      "expected_script": "None"
    },
    {
      "id": "nvshmem-configure-nic-pe-mapping-018",
      "prompt": "How should I configure active-backup bonding for two ordinary Ethernet interfaces on a storage server that does not use NVSHMEM or GPUs?",
      "expected_output": "The agent recognizes that this is unrelated to NVSHMEM NIC-to-PE tuning and does not invoke the skill.",
      "assertions": [
        "The agent does not invoke nvshmem-configure-nic-pe-mapping or nvshmem-docs",
        "The answer addresses ordinary Linux Ethernet bonding without NVSHMEM HCA variables",
        "The agent does not run the topology collector"
      ],
      "expected_skill": null,
      "expected_script": null
    }
  ]
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an API key, Needs Node.js

Security

What our scanner noticed· Medium risk

Large base64-encoded blobs
Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

NVIDIA NVSHMEM Team

Publisher

NVIDIA (Official)

Source

NVIDIA/skills · skills/nvshmem-configure-nic-pe-mapping · commit fce3cca

Licence

Apache License 2.0 (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE-APACHE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by NVIDIA NVSHMEM Team or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download nvshmem-configure-nic-pe-mapping.zip