Constraint docs

[g-braeunlich]

Description

Add docs about constraints.

Fixes #223

Type of change

Please delete options that are not relevant.

• Documentation only change (no code changed)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

• I have run the pre-commit checks with pre-commit run --all-files
• I have run ruff check . and ruff format
• I have run mypy .
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

Reviewer Checklist:

• The content of this PR brings value to the community. It is not too specific to a particular use case.
• The tests and checks pass (linting, formatting, type checking). For a new problem, double check the github actions workflow to ensure the problem is being tested.
• The documentation is updated.
• The code is understandable and commented. No large code blocks are left unexplained, no huge file. Can I read and understand the code easily?
• There is no merge conflict.
• The changes are not breaking the existing results (datasets, training curves, etc.). If they do, is there a good reason for it? And is the associated problem version bumped?
• For a new problem, has the dataset been generated with our slurm script so we can re-generate it if needed? (This also ensures that the problem is running on the HPC.)
• For bugfixes, it is a robust fix and not a hacky workaround.

[markfuge]

In general, this is good @g-braeunlich

I think one improvement could be to have a concrete example at the end where we mention why and under what conditions someone would use certain constraints over another. I think this information is already clear in the documentation you made, but sometimes readers appreciate having a concrete use case and example where they can understand it in context.

This is something that I think @arthurdrake1 could provide or help you with. @arthurdrake1 do you think we could use the Beams2D example to show how and why we would use the difference constraint classes, maybe added as a section at the bottom labeld "Example" or something like this?

[arthurdrake1]

@markfuge, thanks for the heads up. I will look at the commits @g-braeunlich made and work on the Beams2D example today.

[arthurdrake1]

@markfuge let me know if this is the type of thing you were thinking of. If so we can have @g-braeunlich include it where it's most appropriate.

Beams2D Example

Here, we provide a concrete example for the Beams2D problem that illustrates when to use certain constraints over others.

1. The case for a THEORY/Error constraint:

• We know that for a topology optimization problem like Beams2D, the volume fraction volfrac must be defined between 0 and 1 because the design space must be somewhere between empty void (0) and completely filled with solid material (1). Therefore, this must be our theoretical bound and we declare bounded(lower=0.0, upper=1.0).category(THEORY) as an argument when defining volfrac. Violating this constraint will throw an error, because it is physically impossible to have a volume fraction outside of this range.

2. The case for a IMPL/Warning constraint:

• Through experimentation, we have found that values of volfrac below 0.1 lead to solver instability and high compliance values, as there is not enough material available for the optimizer to provide adequate support against the applied force. We have also found that values above 0.9 do not provide any structurally meaningful solutions, since the design space can be almost completely filled with solid material. Therefore, we recommend users to stay within these practical implementation bounds, declaring bounded(lower=0.1, upper=0.9).warning().category(IMPL) as another argument of volfrac. Violating this constraint will produce a warning summarizing the above explanation, but allow the user to continue.

[arthurdrake1]

Per request I have also reviewed the changes and approve these additions to the documentation.

[arthurdrake1]

@g-braeunlich @markfuge and I discussed the above changes that I suggested and think they're good to go for incorporating into this PR. You can go ahead and include my example and close when you're ready.