docs: rename the "set" concept to "stream" and document jm.set deprecation - #185
Open
konn wants to merge 13 commits into
Open
docs: rename the "set" concept to "stream" and document jm.set deprecation#185konn wants to merge 13 commits into
konn wants to merge 13 commits into
Conversation
…ation JijModeling's "set" has always been an ordered, lazily evaluated sequence that may contain duplicates. The tutorials used to paper over this with an admonition saying "sets in JijModeling are streams"; that explanation is dropped and the concept is simply called a stream throughout. - basics/expressions: the section is now "Streams and comprehensions for sum/product"; the "sets are streams" admonition is replaced by one that states plainly that a stream is not a mathematical set, plus a note recording the 2.8.0 rename and the deprecated `jm.set` alias. - basics/modeling: stream-vs-scalar comparisons, streams of indices. - references/migration_guide_to_jijmodeling2: `Element` is replaced by first-class streams, `jm.set(expr)` becomes `jm.stream(expr)`. - releases/unreleased: a new "Feature Enhancements" entry that spells out why the rename happened, shows `jm.stream`, and demonstrates that the deprecated `jm.set` — including its comprehension form — still works. Both language variants updated; paired notebooks re-synced with jupytext. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Rendered model output changed with the rename: expressions now print as `stream(..)` instead of `set(..)`, and types as `Stream[..]` instead of `Set[..]`. Every notebook that displays a model was therefore showing stale output. Executed against a local build of the branch that introduces `jm.stream`, via `task sync_paired_notebooks` plus the two `releases/unreleased` notebooks (which `_config.yml` excludes from the book build, so they are executed explicitly). The unreleased notes now carry real output for both the `jm.stream` example and the deprecated-`jm.set` example. Notebooks whose only diff was execution metadata (iopub timestamps and the kernel patch version) are left untouched, so the diff is limited to output that genuinely changed. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
That admonition existed to disambiguate the old "set" naming from what the type actually is. Now that the concept is simply called a stream, there is nothing left to disambiguate, and the callout only restates the definition that opens the section. The two facts worth keeping — that a stream may contain duplicates, and that `jijmodeling.unique` removes them — are folded into the surrounding prose. The release notes keep the set-vs-stream contrast, since there it justifies the rename rather than disambiguating terminology. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The rename applies to the JijModeling type, not to every mathematical set in the prose. An index set or a key set really is a set in the rigorous sense — its elements are unique — so renaming those to "indices" or "streams of indices" lost accuracy rather than gaining it. Restores the original wording in both languages: "index set" / "key set" and 「添え字の集合」/「キー集合」, including the section heading and the `indices` / `keys` description. Only the JijModeling type itself, and the values that carry it, are still called streams. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
"Set-algebra operations" is not established terminology. The original wording was "logical operations", which is what these `|` / `&` operators are called elsewhere in the section heading, so restore it — along with "set difference" / 「差集合」, the standard name for what `jm.diff` computes. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
konn
marked this pull request as ready for review
August 10, 2026 06:51
NY57
self-requested a review
August 12, 2026 06:47
NY57
reviewed
Aug 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Renames the "set" concept to stream throughout the tutorials, and documents the deprecation of
jm.setin favour ofjm.stream.The tutorials used to introduce the concept as a "set" and then walk it back with an admonition explaining that JijModeling "sets" are really streams — ordered, lazily evaluated, and allowing duplicates. That two-step explanation is dropped: the concept is simply called a stream from the start, and a shorter note now states plainly that a stream is not a mathematical set (pointing at
jm.uniquefor deduplication).Changes, in both
enandja:basics/expressions— the section becomes "Streams and comprehensions for sum/product"; the "sets are streams" admonition is dropped entirely (with the concept simply called a stream there is nothing left to disambiguate — the duplicates-allowed fact and thejm.uniquepointer are folded into the surrounding prose); the array-iteration and dictionary-iteration admonitions are reworded away from "behaves like a set"; explicit conversion is nowjm.stream. A new note records the 2.8.0 rename and thatjm.setsurvives as a deprecated alias.basics/modeling— stream-vs-scalar comparisons; "streams of indices" instead of "index sets".references/migration_guide_to_jijmodeling2—Elementis replaced by first-class streams rather thanSets;jm.set(expr)→jm.stream(expr), with a note about the deprecated alias.releases/unreleased— a new Feature Enhancements entry explaining why the rename happened, showingjm.stream, and demonstrating that the deprecatedjm.setstill works, including its Decorator API comprehension form.Historical release notes (
releases/jijmodeling-2.5.0,2.5.1) still mentionjm.set; they describe what shipped at those versions and are left as-is. Wording that means a mathematical set — "key set", "edge set", "set of labels" — is untouched.Re-executed notebooks
The rename changes rendered model output — expressions print as
stream(..)instead ofset(..), types asStream[..]instead ofSet[..]— so every notebook that displays a model was showing stale output, including ones whose prose I did not touch (introduction,quickstart/*,advanced/*,references/cheat_sheet, …).They are re-executed here against a local build of the JijModeling branch that introduces
jm.stream, usingtask sync_paired_notebooksplus the tworeleases/unreleasednotebooks (excluded from the book build by_config.yml, so executed explicitly). The unreleased notes now carry real output for both thejm.streamexample and the deprecated-jm.setexample.Notebooks whose only diff was execution metadata (iopub timestamps, kernel patch version) are deliberately left untouched, so the diff shows only output that genuinely changed.
task check_paired_notebooksandtextlintboth pass for the two languages.Do not read the ReadTheDocs preview as the result of this PR. Pages such as
basics/placeholdersstill rendereven though the committed notebook says
dict_keys=stream((N, L)).The reason is that the preview does not use the committed outputs at all:
docs/{en,ja}/.readthedocs.yamlinstalls the tutorials package withpip install .[dev], sojijmodeling>=2.0.0,<3resolves to the latest released version (2.7.1) — a clean install that knows nothing about this branch'sjm.stream.docs/{en,ja}/_config.ymlsetsexecute_notebooks: force, so the build discards every committed output and re-runs the notebooks against that released library.The only pages that render committed outputs are the ones
_config.ymlexcludes from execution —releases/jijmodeling-*andreleases/unreleased*. That is whyreleases/unreleaseddoes preview correctly, showingjm.stream(N)and the deprecated-jm.setexample.Nothing is pinned or worked around for this: no pre-release of JijModeling is published just to make the preview green. The preview corrects itself as soon as 2.8.0 reaches PyPI, since the existing dependency range already admits it.
Suggested order: merge the JijModeling PR → release 2.8.0 → rebuild this preview → merge to
develop.CI is likewise unaffected:
check_book_*re-executes from scratch rather than diffing against the committed outputs, andcheck_paired_notebooksdoes not execute at all.🤖 Generated with Claude Code