Rayoptics

=============
Fix numerous issues with :class:`~.elem.profiles.EvenPolynomial` and similar aspherics (issue 164). Remove use of named coefficient attributes in favor of the `coefs` list. Added :meth:`~.elem.profiles.EvenPolynomial.get_by_order` /:meth:`~.elem.profiles.EvenPolynomial.set_by_order` pair to get coefficients by their order number rather than index directly into `coefs`. Updated CODE V import to use `coefs`.

Fixed an issue with wide angle vignetting where a rotation was being applied incorrectly, driving vignetting to zero for 45 deg field angles. Fixed an issue with wide angle systems specified with a real image height that had an x component. This addresses all known problems with issue 157.

:class:`~.parax.firstorder.FirstOrderData` can be printed using :func:`~listobj` now.

=============
Port to PySide6 for Qt app support. This gains support for Mac silicon with conda-forge availability. Move to Numpy 2.1.3 and other dependency tweaks. Partially address removing elements from a model (issue 141).

=============
In response to issue 157, a wide angle raytrace mode was added to the :class:`~.raytr.opticalspec.FieldSpec` model. This can handle lenses over 90 deg half angle, and performs well for fields>45 deg. Chief ray aiming is done by locating the real entrance pupil location in object space rather than aiming at the paraxial entrance pupil, as in the default field specification. Investigation led to the realization that many wide angle models were specified in terms of real image height, which can be vastly different from the paraxial value. The chief ray is traced in reverse from the image point into object space. Both the real entrance pupil and the real image height calculations are in the new :mod:`~.wideangle` module. A different approach towards calculating vignetting based on a binary search to find the limiting aperture was added. This performs better than the default for wide angle systems, where ray failures during the search need to be handled robustly. Finally, the entire ray trace stack from the :mod:`~.analyses` module to :func:`~.raytr.trace.trace_ray` to :func:`~.raytr.raytrace.trace_raw` was refactored to uniformly pass kwargs, and provide ray trace exception handling. The ability to display rays up to the point they were clipped is helpful for model debugging. The code will continue to be streamlined and refactored as needed to accomodate new functionality and get rid of obsolete ideas.

There were improvements to the importers, both to use the wide angle support and real image height capabilities, and routine maintenance.

Thanks to Tohuvavohu for correcting an error in the :mod:`~.zmxread` module.

=============
Revised the call list for :func:`~.raytr.trace.trace_ray` to make it straightforward to use in the simplest cases. The function returns a tuple of the ray_pkg and an ray error instance; the latter is None if are no errors. The :func:`~.raytr.trace.list_ray` function was modified to handle the trace_ray return data in addition to ray and ray_pkg inputs.

Other changes include:

- Updated the doc for the profile module and added an update step during profile creation (issue 152).
- Fixed several subtle transformation issues and shortcomings when rendering cemented elements (issue 153). Reworked the :func:`~.elem.transform.compute_global_coords` function.
- Changed the paraxial NA to be ref index * slope, in keeping with OSLO and the literature (issue 154).
- Introduce :meth:`~.seq.sequential.SequentialModel.apply_scale_factor_over` in seq_model to permit scaling a range of surfaces. Helps with issue 156.
- Remove 'aperture' and 'field' from PupilSpec :attr:`~.PupilSpec.key` and FieldSpec :attr:`~.FieldSpec.key` key definitions; they were redundant information.

Thanks to quentGit for correcting an error in the :mod:`~.waveabr` module.

=============
Fix issue 150, need to constrain the version of numpy to < 2.0.0

=============
A goal of this version is specify optical systems either via the sequential model, the |ybar| diagram, or the element/part tree description. The rayoptics app supports system entry by :meth:`~.seq.sequential.SequentialModel.add_surface` or :meth:`~.optical.opticalmodel.OpticalModel.add_lens` functions in the iPython console, by sketching a |ybar| diagram, and by opening existing optical models. This required a major update to functionality in the :class:`~.parax.paraxialdesign.ParaxialModel`, especially the |ybar| diagram functionality.

To accomodate the different ways models may be built up interactively, a new internal approach of using a simple grammar (:mod:`~.elem.sgz2ele`) to take a sequential model as input and produce an element model/part tree description as output has been implemented. This should eliminate the need to use :meth:`~.optical.opticalmodel.OpticalModel.rebuild_from_seq` to get a correct lens layout. It works well with add_surface, add_lens, add_mirror, etc.

The :mod:`~.qtgui.rayopticsapp` module has been refined to better support use of the iPython console with the graphics windows and menu bar. A button, ``Refresh GUI``, was added to the iPython console to do an update_model() call and reshresh the graphics windows. The ``New`` item on the ``File`` menu opens an iPython console with an empty model and **opm**, **sm**, **osp**, etc. predefined. ``New Diagram`` will open an interactive |ybar| diagram window for sketching a diagram (after clicking the ``Sketch Diagram`` button). Panels for optical specification data are open and docked by default.

Optical systems often can have object or pupil planes at infinity. Even with IEEE floating point arithmetic, **inf** values cause problems in common calculations. Furthermore, it is common in imaging forming software to model an "infinite" object distance as a large number (e.g. 1e10); this convention is embedded in many imported models. The places in the code that dealt with infinite values were identified and guarded against bad outcomes using functions :func:`~.util.misc_math.infinity_guard` and :func:`~.util.misc_math.is_kinda_big`.

Effort was put into covering various corner cases that broke the code. Telecentric and afocal systems, object or image spaces with non-air materials, and models with a single surface (e.g. an eye model) were some of the areas that were addressed.

Other changes include:

- Changed :attr:`raytr.opticalspec.PupilSpec.key` `value_key` literal from ``pupil`` to ``epd`` for clarity.
- Added :meth:`~.optical.opticalmodel.OpticalModel.apply_scale_factor` method to OpticalModel, ParaxialModel, ElementModel, and the OpticalSpecs models.
- Fix the surface normal calculation for :class:`~.elem.profiles.XToroid` (issue 147).
- Look specifically for ``www.photonstophotos.net`` in stringified input (issue 145).
- Added wavefront/opd calculation based on an infinite reference sphere (issue 142).