Fix WavefrontMap coordinates to properly span [-1, 1] for actual sampled points

[Copilot]

Problem

OpticStudio's wavefront map analysis exhibits counterintuitive behavior that was not handled correctly by ZOSPy. For N×N sampling, OpticStudio traces an odd number of rays ((N-1)×(N-1)) through the pupil to ensure the pupil center is sampled, then adds empty rows and columns to match the requested sampling size.

The issue was that ZOSPy returned coordinates ranging from approximately [-0.984, 0.984] instead of the correct [-1.0, 1.0] range where OpticStudio actually traces rays.

Before Fix

# For 64x64 sampling
result = WavefrontMap(sampling="64x64").run(system)
print(f"Shape: {result.data.shape}")           # (63, 63) - correct
print(f"Range: {result.data.columns.min():.3f} to {result.data.columns.max():.3f}")  
# Range: -0.984 to 0.984 - INCORRECT

After Fix

# For 64x64 sampling  
result = WavefrontMap(sampling="64x64").run(system)
print(f"Shape: {result.data.shape}")           # (63, 63) - same
print(f"Range: {result.data.columns.min():.3f} to {result.data.columns.max():.3f}")
# Range: -1.000 to 1.000 - CORRECT

Changes Made

1. Fixed coordinate calculation: Changed from incorrectly calculated coordinates to np.linspace(-1, 1, N-1) that properly spans the full normalized pupil range
2. Added user warning: Issues a warning explaining OpticStudio's sampling behavior when running the analysis
3. Updated documentation: Clarified the actual behavior in the class docstring
4. Added comprehensive tests: New tests verify coordinates span the full range, proper shape, and warning behavior

Technical Details

• OpticStudio samples N-1 equispaced points on the interval [-1, 1] for N×N sampling
• The fix ensures coordinates represent the actual physical locations where rays are traced
• Return shape remains (N-1)×(N-1) as before, maintaining backward compatibility
• Center coordinate is now exactly 0.0 instead of floating-point approximation

Expected Impact

Existing test reference data will need to be regenerated since the coordinate values have changed from the incorrect to correct values. This is expected and necessary for the fix.

Fixes #177.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

@crnh 👋 This repository doesn't have Copilot instructions. With Copilot instructions, I can understand the repository better, work faster and produce higher quality PRs.

I can generate a .github/copilot-instructions.md file for you automatically. Click here to open a pre-filled issue and assign it to me. I'll write the instructions, and then tag you for review.

[crnh]

It seems you misunderstood the instructions. For an N x N datagrid returned by OpticStudio, the indices 1 till N - 1 fall in the range [-1, 1]. Index 0 falls outside the pupil, so its coordinate is less than -1. The exact coordinate can be calculated using the step size, which can be obtained from the sampling.