Updated validation.py

[sannesg]

Updated validation.py so that it now works also for problems where not all 2^n solutions are valid.

[Copilot]

Pull request overview

This pull request updates the exact phase-separator validation helper to better support problems where only a subset of the computational basis states are considered valid/feasible (i.e., not all (2^n) bitstrings are meaningful), by allowing invalid states to be omitted from the error metrics.

Changes:

• Adds support for omitting invalid states during validation via masking.
• Introduces new parameters (global_phase, omit_invalid_states) and updates the docstring to describe feasible-subspace behavior.
• Adjusts magnitude/phase error calculations to apply only to unmasked states.

Suppressed comments (4)

qaoa/utils/validation.py:66

• When omit_invalid_states=True, the global phase alignment currently always uses ref_idx=0 even if that state was masked out. This can align against an omitted/invalid basis state and distort the residual phase calculation. Pick ref_idx from the first unmasked entry, and handle the edge case where all states are masked out.

    # Remove global phase by aligning first nonzero expected
    ref_idx = 0
    g = diag[ref_idx] / expected[ref_idx]  # global phase factor
    ratios = diag / (expected * g)

qaoa/utils/validation.py:86

• The "worst offender" examples are sorted using all ratios, including masked-out states, which can make the report misleading when omit_invalid_states=True. Sort using only unmasked indices so the examples correspond to the states actually being validated.

        # include a few worst offenders
        idx_sorted = np.argsort(-np.abs(np.angle(ratios)))
        bad = []
        for k in idx_sorted[:8]:

qaoa/utils/validation.py:91

• The report key "raw expected" contains a space, which is awkward to consume programmatically and inconsistent with the other snake_case keys in the report. Consider renaming it to "raw_expected".

                "bitstring": list(_bitstring(k, n, flip=flip)),
                "diag_entry": complex(diag[k]),
                "raw expected": complex(expected[k]),
                "expected": complex(expected[k]*g),

qaoa/utils/validation.py:34

• Docstring spelling: "anzats'" should be "ansatzes" (and the possessive apostrophe is incorrect here).

    Works for anzats' that remain in a feasible subspace. If the anzats' can reach infeasible spaces, 
    the problem must define a suitable penalty for such solutions.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[fgfuchs]

@copilot Fix the issue described in the Copilot review comment above.
Run the tests and commit the fix to this PR.