Skip to content

docs: rename the "set" concept to "stream" and document jm.set deprecation - #185

Open
konn wants to merge 13 commits into
developfrom
konn/jijmodeling-set-stream-deprecation-2efaf2
Open

docs: rename the "set" concept to "stream" and document jm.set deprecation#185
konn wants to merge 13 commits into
developfrom
konn/jijmodeling-set-stream-deprecation-2efaf2

Conversation

@konn

@konn konn commented Aug 10, 2026

Copy link
Copy Markdown
Collaborator

Description

Renames the "set" concept to stream throughout the tutorials, and documents the deprecation of jm.set in favour of jm.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.unique for deduplication).

Changes, in both en and ja:

  • 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 the jm.unique pointer are folded into the surrounding prose); the array-iteration and dictionary-iteration admonitions are reworded away from "behaves like a set"; explicit conversion is now jm.stream. A new note records the 2.8.0 rename and that jm.set survives as a deprecated alias.
  • basics/modeling — stream-vs-scalar comparisons; "streams of indices" instead of "index sets".
  • references/migration_guide_to_jijmodeling2Element is replaced by first-class streams rather than Sets; 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, showing jm.stream, and demonstrating that the deprecated jm.set still works, including its Decorator API comprehension form.

Historical release notes (releases/jijmodeling-2.5.0, 2.5.1) still mention jm.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 of set(..), types as Stream[..] instead of Set[..] — 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, using task sync_paired_notebooks plus the two releases/unreleased notebooks (excluded from the book build by _config.yml, so 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, kernel patch version) are deliberately left untouched, so the diff shows only output that genuinely changed.

task check_paired_notebooks and textlint both pass for the two languages.

⚠️ The RTD preview still shows the OLD printer output — this is expected

Do not read the ReadTheDocs preview as the result of this PR. Pages such as basics/placeholders still render

Placeholders: {'A': Placeholder(name="A", dict, dict_keys=set((N, L)): ...

even 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.yaml installs the tutorials package with pip install .[dev], so jijmodeling>=2.0.0,<3 resolves to the latest released version (2.7.1) — a clean install that knows nothing about this branch's jm.stream.
  • docs/{en,ja}/_config.yml sets execute_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.yml excludes from execution — releases/jijmodeling-* and releases/unreleased*. That is why releases/unreleased does preview correctly, showing jm.stream(N) and the deprecated-jm.set example.

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, and check_paired_notebooks does not execute at all.

🤖 Generated with Claude Code

konn and others added 10 commits August 10, 2026 13:02
…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
konn marked this pull request as ready for review August 10, 2026 06:51
@NY57
NY57 self-requested a review August 12, 2026 06:47
NY57
NY57 previously approved these changes Aug 12, 2026

@NY57 NY57 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Comment thread markdowns/ja/basics/expressions.md Outdated

@NY57 NY57 left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants