Symmetry and Data Augmentation

[Scienfitz]

Implements #621

New: A Symmetry class which is part of baybe Surrogates. Three distinct symmetries are included, for more info check the userguide and for a demonstration of the effect see the new example. The ability to perform data augmentation has been included for all symmetries.

I have left some initial comments on design questions that are still open or where I am kind of indifferent and just had to choose one. Feel free to leave an opinion there first so the large-scale design picture can be finalized independent of small comments.

TODO

• CHANGELOG (after architecture is logged in)
• Remember to compress finalized svg picture

Other Notes
Symmetries and constraints are conceptually so similar that they should probably have the same interface. The design here has been done from scratch completely ignoring the constraint interface because it is already known to be not optimal and needs refactoring.

• There is no overarching shared attribute parameters or similar because some symmetries allow single and some multiple such parameters. Instead the parameters are treated like the objectives treat target(s)
• Contrary to dependency constraint, dependency symmetry can only hold 1 set of dependencies. The constraint should be refactored to look the same.

Unrelated Bugfix
I noticed that the permutation constraint also removed the diagonal in its filtering process. However this seems unreasonable since the diagonal is a set of points that are unique and have no invariant equivalent hence nothing needs removing. Turns out there was an automatic removal of the diagoanl because internally DiscretePermutationInvarianceConstraint also always applied a DiscreteNoLabelDuplicates constraint. I think the rational was that label duplicates dont make sense in these mixture situations so they need removing. However, this as nothing to do with the invariance and is achieved anyway in mixture use cases by adding a no label duplicate explicitly. So it was removed from the DiscretePermutationInvarianceConstraint which now leads to the expected amount of removed points (on of the matrix triangles)

[AVHopp]

@Scienfitz just to make sure - I guess since this is marked as a draft, you do not require a PR review for now, right? Is there anything else that we can assist with?

[Scienfitz]

@AVHopp yes exactly and it will always be like that for PR's that I open in draft: Ignore until requested or asked in any other way

[Copilot]

Pull Request Overview

This PR implements automatic data augmentation for measurements when constraints support symmetry assumptions, particularly for permutation and dependency invariance constraints. This enhancement helps surrogate models better learn from symmetric relationships in the data without requiring users to manually generate augmented points.

• Adds consider_data_augmentation flags to both surrogate models and relevant constraints to control augmentation behavior
• Integrates augmentation logic into the Bayesian recommender workflow, applying it before model fitting when configured
• Provides comprehensive examples and documentation showing the performance benefits of augmentation

Reviewed Changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/test_measurement_augmentation.py	New test file verifying augmentation is applied when configured
examples/Constraints_Discrete/augmentation.py	New example demonstrating augmentation effects on optimization performance
docs/userguide/surrogates.md	Documentation updates explaining data augmentation feature
docs/userguide/constraints.md	Documentation updates for augmentation flags in constraints
docs/scripts/build_examples.py	Build script improvement to ignore __pycache__ folders
baybe/utils/dataframe.py	Added documentation note about constraint considerations
baybe/utils/augmentation.py	Cleaned up duplicate example in docstring
baybe/surrogates/gaussian_process/core.py	Added consider_data_augmentation flag with temporary default
baybe/surrogates/base.py	Added base consider_data_augmentation flag to surrogate interface
baybe/searchspace/core.py	Core augmentation logic and augment_measurements method
baybe/recommenders/pure/bayesian/base.py	Integration of augmentation into Bayesian recommender workflow
baybe/recommenders/pure/base.py	Minor cleanup of validation logic
baybe/constraints/discrete.py	Added consider_data_augmentation flags to constraint classes
baybe/constraints/base.py	Moved augmentation flag to base constraint class
CHANGELOG.md	Documented new features and changes

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Scienfitz]

Important: Validation so far is only part of the recommend call here in the recommenders. Validation has not been included in the Campaign yet. This is due to two factors

• To properly validate the symmetries and searchspace compatibility there needs to be a mechanism that can iterate over all possible recommenders of a metarecommender. Otherwise this upfront validation already fails for the two phase recommender if the second recommender has symmetries
• There would be double validation with campaign and recommend call so the context info of whether validation was already performed needs to be passed somewhere. Likely fixable with settings mechanism not yet available

[Scienfitz]

@AdrianSosic I see now that the 2nd point could be solved with the Settings mechanism but I have no idea how to solve issue 1.

In the absence of that its not realy possible to turn it into an upfront validation, so I would probably not change the validation for this moment unless you have a smarter idea

[AVHopp]

+1 for being pragmatic and not trying to come up with something potentially convoluted right now. Even if we find a better way for the validation later, including it is just a plain improvement without negative consequences to users, so we can add it later without problems.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[AVHopp]

All in all happy, only some comments but I do not see any major thing that needs change. Thank you for this cool new feature!