ENH: Allow contour levels to be decreasing - #32206

PR summary

Closes #31227

Problem

contour and contourf raise ValueError: Contour levels must be increasing whenever the contour levels are given in monotonically decreasing order. This prevents the use case described in #31227: plotting a fixed set of negative contours (e.g. -base * 2**arange(...) grids) that extends beyond the data range, where the value closest to zero is known ahead of time but the depth of the data is not.

Reproduction

import matplotlib.pyplot as plt
z = [[0, 1], [1, 2]]
plt.contourf(z, levels=[2, 1, 0])  # ValueError: Contour levels must be increasing

What changed

• When the supplied levels are monotonically decreasing they are reversed internally, so the rest of the code can keep assuming increasing levels. This works for contour, contourf, and their tricontour counterparts, whether the levels are passed as a list, array, or positionally.
• Per-level styling (colors, linewidths, linestyles, hatches) is reversed together with the levels so that each style stays associated with the level it was given for. When extend is combined with an explicit color list that includes under/over colors, the extended colors are preserved at the ends.
• Genuinely non-monotonic levels still raise the existing error, so ambiguous orderings are not silently reordered.

Why this approach

This follows the direction discussed in the issue: the maintainers rejected sorting arbitrary user level lists (ambiguous for per-level colors), but a monotonic decreasing list can be unambiguously reversed, and the per-level attributes flipped with it. ContourSet.levels, layers, and the colorbar therefore stay consistent with the rest of the code.

How it was tested

• New test_decreasing_levels (contour and contourf, list/array/positional forms).
• New test_decreasing_levels_styling (colors/linewidths/linestyles stay with their levels).
• Updated test_contourf_decreasing_levels to cover the still-rejected non-monotonic case.
• python -m pytest lib/matplotlib/tests/test_contour.py -v -> 92 passed, 2 skipped.

Related work

PR #31237 addresses the same issue with a different approach: it removes the monotonicity requirement for line contours entirely (accepting arbitrary, including non-monotonic, orders without reordering) while keeping the error for contourf. This PR instead handles the strictly decreasing case for both contour and contourf by reversing the levels.

AI Disclosure

N/A

PR quality check

• Use an expressive title, e.g. "Fix title font property precedence"
• New and changed code is tested
• Plotting related features are demonstrated in an example (N/A - behavior covered by unit tests)
• New features and API changes have release notes
• Documentation complies with general and docstring guidelines