[DEV]: add pixi.lock and add pixi to pyproject.toml - #31384

Edit: apologies for the CI churn --- I needed to iterate on the Pixi workflow to get it working end-to-end.

Overview

This PR adds Pixi configuration to pyproject.toml and introduces a committed pixi.lock.

The main goal is to provide a project-committed, pinned dependency snapshot for Matplotlib, addressing #23548. In particular:

• pyproject.toml defines the Pixi environment under [tool.pixi]
• pixi.lock records the fully resolved dependency set
• CI exercises that lockfile to verify that it can be used reproducibly

Why pyproject.toml

Pixi configuration is placed in pyproject.toml rather than a project-level pixi.toml.

The reasoning is:

• pyproject.toml is already the canonical project configuration
• it keeps the shared Pixi definition attached to the project itself
• developers who want local customization can still create an untracked pixi.toml, which Pixi will prefer over pyproject.toml

This gives the project a canonical shared configuration while still allowing personal overrides.

Lockfile policy

A main goal of this PR is to commit a pinned dependency list, and pixi.lock is the mechanism used for that.

pixi.lock should therefore be treated as part of the repository state:

• changes to Pixi dependency inputs should be accompanied by a regenerated pixi.lock
• CI uses the lockfile to verify reproducibility
• old commits retain the dependency snapshot that was current at that point in history

In that sense, pixi.lock is the committed pinned dependency snapshot for the project.

Developer workflow

Basic usage:

pixi install

pixi run python -m pip install \
  --no-build-isolation \
  --config-settings=setup-args="-Db_lto=false" \
  --editable .

After that, for example:

pixi run tests-core
pixi run build-doc

Dependency changes:

If dependencies change, then pixi.lock should be regenerated. It is ignored by default in .gitignore so developers who want to change pixi.lock will need to regenerate it, and force add it to a commit:

mv pixi.toml pixi.backup
pixi lock
git add -f pixi.lock

tools/pixi.example.toml

A template is provided for developers who want to customize their local Pixi setup.

For example:

cp tools/pixi.example.toml pixi.toml

This is intended for local experimentation or system-specific tuning. It is not the project's canonical Pixi configuration.

Key design decisions

Editable install is not managed directly by Pixi

This PR intentionally does not use:

    [pypi-dependencies]
    matplotlib = { path = ".", editable = true }

In testing, that led to lockfile instability (lock-file not up-to-date with the workspace), especially in CI.

Instead, responsibilities are split:

• Pixi manages the environment and pinned dependencies
• pip install -e . installs Matplotlib itself

This keeps pixi.lock stable while still supporting editable development installs.

Single environment

Although Pixi supports separate environments such as test and doc, this PR currently uses a single environment containing the relevant dependencies.

The main reason is developer convenience:

• avoids repeated editable installs in separate environments
• keeps the workflow simple
• still allows the lockfile to capture the relevant dependency sets

This can be revisited later if stricter separation is desirable.

CI

This PR adds a minimal CI job that checks that the Pixi environment can be recreated from the committed lockfile.

At the moment the job is intentionally lightweight: it verifies that the lockfile works and that Matplotlib can be built/imported in that environment. It can be extended later to run tests and/or documentation builds.

Notes / future work

• extend Pixi CI coverage to run more tests and build docs
• decide whether additional environment separation is worthwhile
• refine developer-facing documentation around local pixi.toml
  overrides

AI disclosure

I went back and forth w/ chatGPT quite a bot on how to organize this and the various tradeoffs. It also helped with writing this summary, which is of course long-winded, but hopefully complete.