Lint Messages

This page is the detailed lint message catalog for nkDSL diagnostics. Use it when a compile-time diagnostic points you to a specific code.

Quick navigation

Errors:

NKDSL-E001, NKDSL-E002, NKDSL-E003

Warnings:

NKDSL-W101, NKDSL-W103, NKDSL-W104, NKDSL-W301, NKDSL-W302, NKDSL-W303

Info:

NKDSL-I201, NKDSL-I301, NKDSL-I302

Errors

NKDSL-E001: unresolved free symbols

Meaning:

The operator IR contains free symbolic names (for example symbol("J")) that were not resolved before compilation. Symbols declared with default=... are treated as resolved and do not trigger this lint.

Typical causes:

A numeric value was intended but left symbolic, or a parameter-binding step in the application workflow was skipped.

Example:

op = (
    SymbolicDiscreteJaxOperator(hi, "hop")
    .for_each_site("i")
    .emit(identity(), matrix_element=symbol("J"))
    .build()
)

How to resolve:

Replace free symbols with concrete values before compile, or add an explicit parameter-binding layer in your workflow and ensure it runs before .compile(). For optional parameters, declare a fallback directly with symbol("J", default=...).

NKDSL-E002: static index out of Hilbert bounds

Meaning:

A static source/target index expression (for example source_index(k) or target_index(k)) refers to a site outside [0, hilbert_size).

Typical causes:

Hard-coded indices copied from a different model size, stale formulas after changing Hilbert layout, or incorrect assumptions about flattened indexing.

Example:

.emit(identity(), matrix_element=source_index(42))

How to resolve:

Ensure every static index expression is valid for the current Hilbert size. If the index should depend on iterator labels, use symbolic selector/index expressions instead of fixed constants.

NKDSL-E003: potential zero division on runtime state values

Meaning:

A division denominator is a direct runtime state read that may be zero. This includes iterator selectors (for example site("i").value, emitted("i").value) and flat-index source/target reads (source_index(k), target_index(k)).

Typical causes:

Matrix elements use expressions like 1 / site("i").value or 1 / source_index(0) without a non-zero guard.

Example:

.emit(identity(), matrix_element=1 / target_index(0))

How to resolve:

Add an explicit non-zero guard (for example where(site("i").value != 0)), or rewrite with explicit conditional branching so division executes only on safe branches.

Warnings

NKDSL-W101: predicate is constant false

Meaning:

The term predicate always evaluates to false, so the term can never emit.

Typical causes:

Placeholder predicates left in place, contradictory conditions, or accidental boolean simplification to False.

How to resolve:

Remove dead terms or fix predicate logic so intended visits are reachable.

NKDSL-W103: duplicate emissions

Meaning:

Two or more emissions in the same term are structurally identical (same update program and amplitude expression).

Typical causes:

Copy/paste duplication while building multi-emission terms.

How to resolve:

Remove duplicates, or intentionally differentiate branch behavior and/or matrix element expressions.

NKDSL-W104: max connection hint below static upper bound

Meaning:

max_conn_size_hint is smaller than the term’s static upper bound (n_iterator_rows * n_emissions).

Typical causes:

The hint was set early and not updated after adding rows/emissions.

How to resolve:

Increase the hint to a conservative valid value, or remove the explicit hint and let the compiler infer one.

NKDSL-W301: generated states outside Hilbert support

Meaning:

Sampled emitted states are not members of the Hilbert support set.

Typical causes:

Update programs produce states that are not representable in the chosen Hilbert space.

Example scenario:

A rewrite writes values outside what the Hilbert model can encode, or applies shifts that move occupations beyond support.

How to resolve:

Constrain updates and predicates so emitted states remain in Hilbert support. If the warning is expected in exploratory code, reduce scope or guard branches until model assumptions are finalized.

NKDSL-W302: generated states violate Hilbert constraints

Meaning:

Sampled emitted states fail hilbert.constraint(state).

Typical causes:

Rewrites break particle-number, magnetization, parity, or custom constrained subspace rules.

Example scenario:

A term shifts occupation on one site without complementary update, violating a fixed-particle-number constraint.

How to resolve:

Tighten predicates and/or adjust update programs to preserve the constrained manifold for all emitted branches.

NKDSL-W303: generated states contain illegal local basis values

Meaning:

One or more site values in sampled emitted states are outside hilbert.local_states.

Typical causes:

Unbounded shift operations, writes with invalid values, or assumptions about local basis that do not match the configured Hilbert object.

How to resolve:

Gate shifts with predicates, use bounded rewrites (for example shift_mod where physically appropriate), and validate write targets against local basis.

Info

NKDSL-I201: missing branch tags on multi-emission term

Meaning:

A term with multiple emissions does not assign tag=... for one or more branches, reducing readability of diagnostics and IR output.

How to resolve:

Add explicit tags to each emission so logs and diagnostics stay easy to parse.

NKDSL-I301: skipped exact support-membership checks

Meaning:

Exact support lookup was skipped because Hilbert cardinality exceeded lint_max_exact_hilbert_states.

Typical causes:

Hilbert space is too large for exact support enumeration within configured diagnostics limits.

How to resolve:

Increase lint_max_exact_hilbert_states if memory/time budget allows, or rely on sampled diagnostics for large spaces.

NKDSL-I302: skipped sampled branch evaluation

Meaning:

Some sampled branch evaluations could not run in diagnostics mode (for example unresolved runtime values or branch evaluation failures).

Typical causes:

Missing runtime symbols, non-evaluable branch context during diagnostics, or unexpected evaluation failures in sampled paths.

How to resolve:

Resolve runtime bindings before compile and ensure branch expressions can be evaluated under diagnostics sampling.