feat(skills): formulation-display — canonical optimization-problem presentation per package (papers' notation) + QILC/Piccolissimo display sets

[aarontrowbridge]

---

type: issue-draft
repo: harmoniqs/amicode
tier: standard
date: 2026-10-03

Important

Problem — When a solve or loop uses one of the packages, the technical detail of what optimization problem was actually solved is invisible: reports and demo write-ups state results without stating the problem in classic optimization form (as in the Direct Collocation for QOC paper, arXiv:2305.03261, and Universal Dynamics with Globally Controlled Analog Quantum Simulators, arXiv:2508.19075), and package-specific display requirements are folklore — e.g. QILC work must show measurement models, pulse/correction plots, and convergence, but nothing encodes that.
Approach — A new public skill formulation-display owning the canonical presentation: the continuous trajectory-optimization core, the direct-collocation DIRCOL form (dynamics as equality constraints, isomorphic real representation, control bounds), the indirect/GRAPE contrast, the free-time/min-time form, and the robustness-ensemble form — each in the papers' own notation — plus where these render (PI-report findings, demos, papers, spec cards). The entitled packages get display sections in their own cards: Piccolissimo (spline-parameterized NLP with the spline-faithful integrator as the dynamics constraint, Gauss–Newton) and Intonatissimo/QILC (the measurement-matching subproblem in classic form, trust region, Armijo, and the required display set: measurement models, per-iteration pulse + correction plots, convergence traces).
Approaches considered — folding everything into the PI-report issue (rejected: the formulation presentation serves papers, demos, and specs too, not just reports); one monolithic entitled skill (rejected: the Piccolo/paper backbone is public and should stage for every session).
Scope — in: the formulation-display skill; display sections in piccolissimo and intonatissimo; lint green · out: new plotting code (the plot skill's per-tier sets stay canonical), the PI-report generator itself (#1700).
Assumptions — the two papers' forms are the house style; measurement-model operators and ILC structures as in the Intonatissimo usage card.

Acceptance Criteria

• formulation-display skill lands in the repo library, lint green, with the five canonical forms in the papers' notation
• Every form carries its provenance (equation/paper pointer) and states when to show which (direct vs indirect, fixed vs free time)
• intonatissimo gains the QILC classic-form statement + the required display set (measurement models, pulses + corrections, convergence)
• piccolissimo gains the spline-NLP classic form + its display set
• The cards cross-reference display-conventions honesty bars and the plot skill's per-tier sets instead of duplicating them

Testing Decisions

Skill lint (lint-skills.mjs) on the repo library; no runtime surface.

Key Decisions

• Public/entitled split per the placement doctrine: paper-backed canonical forms are public; package-internal parameterizations stay in their entitled cards.
• The classic forms are written in the papers' notation, not package API terms — the skill maps API to math (the report shows math; the run dir shows code).

Constraints & Invariants

• Honesty bars inherit from display-conventions: legs named, provenance on every number, no invented capability claims — every API name verified against the skills' existing verified references.
• No proprietary secret leaks into the public card (Piccolissimo/Intonatissimo specifics stay entitled).

Source

Companion slice to #1700 (the PI report) — its findings will cite this skill for problem statements.

Notes

Driven by the round-3 review: findings explain hypotheses in prose; the missing piece is the formal problem statement, which these skills will make standard.