feat(neighborhoods): add groupBy() support#2334
Merged
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds groupBy() capabilities to the Neighborhoods enumerating stream API (preview), including support for collectors, and wires SolutionView into grouping so predicates/mappers/collectors can access working-solution state consistently with other building blocks.
Changes:
- Extends
UniEnumeratingStream/BiEnumeratingStreampreview APIs withgroupBy(...)overloads (keys-only, collector-only, keys+collector) and implements them in the enumerating stream internals. - Introduces a preview collector API (
*NeighborhoodsCollector*) plusNeighborhoodsCollectors.toList(...), and adapts these collectors to Bavet’s constraint collector machinery at node-build time (whenSolutionViewis available). - Adds/updates tests and docs, and exports the new preview collector package from the Java module.
Reviewed changes
Copilot reviewed 27 out of 29 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| model/test-model/src/main/java/ai/timefold/solver/model/testmodel/EmployeeScheduleOutputMetrics.java | Minor formatting-only change. |
| model/test-model/src/main/java/ai/timefold/solver/model/testmodel/EmployeeScheduleInputMetrics.java | Minor formatting-only change. |
| docs/src/modules/ROOT/pages/optimization-algorithms/neighborhoods.adoc | Mentions groupBy as another building block supporting solutionView-aware functions. |
| core/src/test/java/ai/timefold/solver/core/preview/api/neighborhood/stream/enumerating/UniEnumeratingStreamTest.java | Refactors helpers/names and adds groupBy(...)/collector test coverage. |
| core/src/test/java/ai/timefold/solver/core/preview/api/neighborhood/stream/enumerating/BiEnumeratingStreamTest.java | New tests for groupBy(...) on bi-stream sources. |
| core/src/main/java/module-info.java | Exports the new preview collector package. |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/enumerating/UniEnumeratingStream.java | Adds groupBy(...) overloads to the preview uni-stream API. |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/enumerating/BiEnumeratingStream.java | Adds groupBy(...) overloads to the preview bi-stream API. |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/UniNeighborhoodsCollectorValueHandle.java | New preview API for incremental per-value handles (uni). |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/UniNeighborhoodsCollectorAccumulator.java | New preview API for creating per-value handles using SolutionView (uni). |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/UniNeighborhoodsCollector.java | New preview API collector contract (uni). |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/NeighborhoodsCollectors.java | New factory for common neighborhoods collectors (toList). |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/BiNeighborhoodsCollectorValueHandle.java | New preview API for incremental per-value handles (bi). |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/BiNeighborhoodsCollectorAccumulator.java | New preview API for creating per-value handles using SolutionView (bi). |
| core/src/main/java/ai/timefold/solver/core/preview/api/neighborhood/stream/collector/BiNeighborhoodsCollector.java | New preview API collector contract (bi). |
| core/src/main/java/ai/timefold/solver/core/impl/util/ConstantLambdaUtils.java | Adds constant Neighborhoods*Mapper pickers for node sharing; removes unused constants. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/uni/UniGroupUniEnumeratingStream.java | Switches grouping node construction to a SolutionView-aware constructor and marks distinctness. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/uni/UniGroupBiEnumeratingStream.java | New uni-parent-to-bi-output grouping stream implementation. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/uni/AbstractUniEnumeratingStream.java | Implements the new groupBy(...) API and routes distinct() through neighborhoods constant mappers. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/common/NeighborhoodsGroupNodeConstructorWithoutAccumulate.java | New internal wrapper for non-accumulating group node constructors keyed for sharing. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/common/NeighborhoodsGroupNodeConstructorWithAccumulate.java | New internal wrapper for accumulating group node constructors keyed for sharing. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/common/NeighborhoodsGroupNodeConstructor.java | New internal factory tying mappers/collectors to Bavet group node constructors using SolutionView. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/common/AbstractNeighborhoodsGroupNodeConstructor.java | New equality-keyed base implementation supporting node sharing. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/bi/BiGroupUniEnumeratingStream.java | New bi-parent-to-uni-output grouping stream implementation. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/bi/BiGroupBiEnumeratingStream.java | Updates grouping node construction to be SolutionView-aware and marks distinctness. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/enumerating/bi/AbstractBiEnumeratingStream.java | Implements the new groupBy(...) API and routes distinct() through neighborhoods constant mappers. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/collector/ToListUniNeighborhoodsCollector.java | Internal implementation of uni toList() collector. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/collector/ToListBiNeighborhoodsCollector.java | Internal implementation of bi toList(mapper) collector with SolutionView support. |
| core/src/main/java/ai/timefold/solver/core/impl/neighborhood/stream/collector/NeighborhoodsCollectorUtils.java | Adapts neighborhoods collectors to Bavet constraint collectors at build time (with SolutionView). |
Christopher-Chianelli
approved these changes
Jun 3, 2026
…ods.adoc Co-authored-by: Christopher Chianelli <christopher@timefold.ai>
Collaborator
Author
|
Since I made significant changes (mostly adding new collectors), I'm re-requesting a review, @Christopher-Chianelli. |
|
Christopher-Chianelli
approved these changes
Jun 4, 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.
No description provided.