Skip to content

Reorganize adapter input and preparation documentation - #1159

Draft
termoshtt wants to merge 7 commits into
mainfrom
codex/docs-adapter-preparation
Draft

Reorganize adapter input and preparation documentation#1159
termoshtt wants to merge 7 commits into
mainfrom
codex/docs-adapter-preparation

Conversation

@termoshtt

Copy link
Copy Markdown
Member

Summary

  • reorganize the Adapter documentation around separate user and Adapter-author journeys, with tutorials that progress from a direct PySCIPOpt solve through native special constraints, caller-owned Preparation, OpenJij sampling, and Adapter comparison
  • split the former capability-model material into focused guides for exact INPUT_CLASS membership, PreparationPolicy, and the removed-constraint lifecycle, while routing exact formulas, preconditions, generated artifacts, errors, and atomicity to the API reference
  • replace the implementation tutorial with a concise Developer Guide and document the used-decision-variable encode/decode contract on the Solver and Sampler Adapter APIs
  • convert the introductory solve tutorial to executed notebooks with pandas output, synchronize the Japanese and English documentation, merge the MIPLIB and QPLIB download tutorials, and preserve legacy URLs with relocation stubs

Motivation

The previous documentation mixed an obsolete capability model, user-owned model preparation, special-constraint lowering details, and Adapter implementation guidance. This made it difficult for users to tell whether an Adapter would accept an Instance exactly, who was responsible for applying a recommended policy, and how transformed constraints remained available for evaluation.

The new structure gives each layer one owner: tutorials teach the immediate workflow, user guides explain concepts and responsibility boundaries, the generated API reference defines exact operation contracts, and the Developer Guide points Adapter authors to the shared contracts and reference implementations.

Impact

Users now encounter Preparation only after first solving models that need no transformation, and application-specific choices such as penalty weights remain explicit. Adapter authors get a direct path to INPUT_CLASS, caller-owned Preparation, removed constraints, and the requirement to encode and decode only used decision variables. Existing published tutorial and capability-model URLs continue to lead readers to the new documentation.

@termoshtt termoshtt added the documentation Docs, examples, tutorials, migration guides, or API reference label Aug 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Docs, examples, tutorials, migration guides, or API reference

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant