Change wavefront map indices to range [-1, 1] for actual sampled pupil

[crnh]

Proposed change

For an N x N sampling, the Wavefront Map analysis returns an (N - 1) x (N - 1) DataFrame with incorrect row and column labels. This was caused by an incorrect interpretation of the ZOS-API output (cell coordinates were interpreted as corner coordinates but are in fact center coordinates) and a confusing step size returned by the ZOS-API (the API returns 2 / (N - 1), but this should be 2 / (N - 2) because OpticStudio uses an odd sampling).
Fixes in this PR:

• The Wavefront Map analysis now returns an N x N DataFrame.
• Row and column labels now span the range [-1, 1] for the (N - 1) x (N - 1) cells inside the pupil, with step size 2 / (N - 2); labels for the empty row and column are one step outside this range.

Type of change

• Example (a notebook demonstrating how to use ZOSPy for a specific application)
• Bugfix (non-breaking change which fixes an issue)
• New analysis (a wrapper around an OpticStudio analysis)
• New feature (other than an analysis)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests
• Documentation (improvement of either the docstrings or the documentation website)

Additional information

• OpticStudio version: 2025R1

Related issues

Closes #177.

Checklist

• I have followed the contribution guidelines
• The code has been linted, formatted and tested (see the contribution guidelines).
• Local tests pass. Please fix any problems before opening a PR. If this is not possible, specify what doesn't work and why you can't fix it.
• I tested ZOSPy for all supported Python versions (hatch test -a).
• I added new tests for any features contributed, or updated existing tests.
• I updated CHANGELOG.md with my changes (except for refactorings and changes in the documentation).

If you updated an example:

• I executed all examples and verified that they run without errors (hatch run all-examples).

If you contributed an example:

• I contributed my example as a Jupyter notebook.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR fixes Wavefront Map datagrid coordinate labeling and sizing so returned results align with OpticStudio’s actual sampled pupil points and span the intended [-1, 1] coordinate range.

Changes:

• Update Wavefront Map to return an N×N DataFrame (including the empty row/column as NaN) with corrected coordinate indices.
• Extend unpack_datagrid to allow overriding grid spacing (dx, dy) when generating labels.
• Update tests and reference data to reflect the corrected Wavefront Map grid and indices.

Reviewed changes

Copilot reviewed 18 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
zospy/utils/zputils.py	Adds dx/dy overrides for datagrid label generation.
zospy/analyses/wavefront/wavefront_map.py	Returns full N×N grid and constructs corrected pupil coordinates via unpack_datagrid.
tests/utils/test_zputils.py	Refactors/expands tests for unpack_datagrid, including custom spacing.
tests/analyses/test_wavefront.py	Adds assertions for Wavefront Map index/step sizing and reference matching.
tests/data/reference/*.json	Updates stored reference outputs for new grid size/indices.
pyproject.toml	Adds ipykernel to dev dependency group.
CHANGELOG.md	Documents the Wavefront Map DataFrame size/index fix.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.