rayoptics.raytr.analyses module

Aberration calculations for (fld, wvl, foc), including focus and image shift

This module refactors some existing ray trace and aberration calculations in other modules to be expressed for a single field point and wavelength. The ability to apply focus and image shifts to an already acquired data set is provided for use interactively and in other performance critical areas.

The following classes are implemented in this module:

• Ray: trace a single ray

• RayFan: trace a fan of rays in either the x or y meridian

• RayList: trace a list of rays from an object point

• RayGrid: trace a rectilinear grid of rays

All but the Ray class are supported by a group of functions to trace the rays, accumulate the data (trace_*), and refocus (focus_*) the data. A all-in-one function (eval_*) to trace and apply focus is supplied also. These are used in the update_data methods of the classes to generate the ray data.

This module also has functions to calculate chief ray and reference sphere information as well as functions for calculating the monochromatic PSF of the model.

class Ray(opt_model, p, f=0, wl=None, foc=None, image_pt_2d=None, image_delta=None, srf_indx=-1, srf_save='single', output_filter=None, rayerr_filter=None, color=None)

Bases: object

A ray at the given field and wavelength.

opt_model

OpticalModel instance

p

relative 2d pupil coordinates

f

index into FieldSpec or a Field instance

wl

wavelength (nm) to trace the ray, or central wavelength if None

foc

focus shift to apply to the results

image_pt_2d

base image point. if None, the chief ray is used

image_delta

image offset to apply to image_pt_2d

srf_save

‘single’: save the ray data for surface srf_indx ‘all’: save all of the surface by surface ray data

srf_indx

for single surface retention, the surface index to save

update_data(**kwargs)

Trace the ray and calculate transverse aberrations.

class RayFan(opt_model, f=0, wl=None, foc=None, image_pt_2d=None, image_delta=None, num_rays=21, xyfan='y', output_filter=None, rayerr_filter=None, color=None, **kwargs)

Bases: object

A fan of rays across the pupil at the given field and wavelength.

opt_model

OpticalModel instance

f

index into FieldSpec or a Field instance

wl

wavelength (nm) to trace the fan, or central wavelength if None

foc

focus shift to apply to the results

image_pt_2d

base image point. if None, the chief ray is used

image_delta

image offset to apply to image_pt_2d

num_rays

number of samples along the fan

xyfan

‘x’ or ‘y’, specifies the axis the fan is sampled on

update_data(**kwargs)

Set the fan attribute to a list of (pupil coords), dx, dy, opd.

select_plot_data(fan, xyfan, data_type)

Given a fan of data, select the sample points and the resulting data.

smooth_plot_data(f_x, f_y, num_points=100)

Interpolate fan data points and return a smoothed version.

trace_ray_fan(opt_model, fan_rng, fld, wvl, foc, output_filter=None, rayerr_filter=None, **kwargs)

Trace a fan of rays, according to fan_rng.

eval_fan(opt_model, fld, wvl, foc, xy, image_pt_2d=None, image_delta=None, num_rays=21, output_filter=None, rayerr_filter=None, **kwargs)

Trace a fan of rays and evaluate dx, dy, & OPD across the fan.

trace_fan(opt_model, fld, wvl, foc, xy, image_pt_2d=None, image_delta=None, num_rays=21, output_filter=None, rayerr_filter=None, **kwargs)

Trace a fan of rays and precalculate data for rapid refocus later.

focus_fan(opt_model, fan_pkg, fld, wvl, foc, image_pt_2d=None, image_delta=None, **kwargs)

Refocus the fan of rays and return the tranverse abr. and OPD.

class RayList(opt_model, pupil_gen=None, pupil_coords=None, num_rays=21, f=0, wl=None, foc=None, image_pt_2d=None, image_delta=None, apply_vignetting=True)

Bases: object

Container class for a list of rays produced from a list or generator

opt_model

OpticalModel instance

pupil_gen

(fct, args, kwargs), where:

• fct: a function returning a generator returning a 2d coordinate

• args: passed to fct

• kwargs: passed to fct

pupil_coords

list of 2d coordinates. If None, filled in by calling pupil_gen.

num_rays

number of samples side of grid. Used only if pupil_coords and pupil_gen are None.

f

index into FieldSpec or a Field instance

wl

wavelength (nm) to trace the fan, or central wavelength if None

foc

focus shift to apply to the results

image_pt_2d

base image point. if None, the chief ray is used

image_delta

image offset to apply to image_pt_2d

apply_vignetting

whether to apply vignetting factors to pupil coords

update_data(**kwargs)

trace_ray_list(opt_model, pupil_coords, fld, wvl, foc, append_if_none=False, output_filter=None, rayerr_filter=None, **kwargs)

Trace a list of rays at fld and wvl and return ray_pkgs in a list.

trace_list_of_rays(opt_model, rays, output_filter=None, rayerr_filter=None, **kwargs)

Trace a list of rays (pt, dir, wvl) and return ray_pkgs in a list.

Parameters:

• opt_model – OpticalModel instance

• rays –

  list of (pt0, dir0, wvl)

  • pt0: starting point in coords of first interface

  • dir0: starting direction cosines in coords of first interface

  • wvl: wavelength in nm

• output_filter – None, “last”, or a callable. See below

• **kwargs – kwyword args passed to the trace function

The output_filter keyword argument controls what ray data is returned to the caller.

• if None, returns the entire traced ray

• if “last”, returns the ray data from the last interface

• if a callable, it must take a ray_pkg as an argument and return the desired data or None

Returns:

A list with an entry for each ray in rays

eval_pupil_coords(opt_model, fld, wvl, foc, image_pt_2d=None, image_delta=None, num_rays=21, **kwargs)

Trace a list of rays and return the transverse abr.

trace_pupil_coords(opt_model, pupil_coords, fld, wvl, foc, image_pt_2d=None, image_delta=None, **kwargs)

Trace a list of rays and return data needed for rapid refocus.

focus_pupil_coords(opt_model, ray_list, fld, wvl, foc, image_pt_2d=None, image_delta=None)

Given pre-traced rays and a ref. sphere, return the transverse abr.

class RayGrid(opt_model, f=0, wl=None, foc=None, image_pt_2d=None, image_delta=None, num_rays=21, value_if_none=nan)

Bases: object

Container for a square grid of rays.

opt_model

OpticalModel instance

f

index into FieldSpec or a Field instance

wl

wavelength (nm) to trace the fan, or central wavelength if None

foc

focus shift to apply to the results

image_pt_2d

base image point. if None, the chief ray is used

image_delta

image offset to apply to image_pt_2d

num_rays

number of samples along the side of the grid

update_data(**kwargs)

trace_ray_grid(opt_model, grid_rng, fld, wvl, foc, append_if_none=True, output_filter=None, rayerr_filter=None, **kwargs)

Trace a grid of rays at fld and wvl and return ray_pkgs in 2d list.

eval_wavefront(opt_model, fld, wvl, foc, image_pt_2d=None, image_delta=None, num_rays=21, value_if_none=nan)

Trace a grid of rays and evaluate the OPD across the wavefront.

trace_wavefront(opt_model, fld, wvl, foc, image_pt_2d=None, image_delta=None, num_rays=21)

Trace a grid of rays and pre-calculate data needed for rapid refocus.

focus_wavefront(opt_model, grid_pkg, fld, wvl, foc, image_pt_2d=None, image_delta=None, value_if_none=nan)

Given pre-traced rays and a ref. sphere, return the ray’s OPD.

psf_sampling(n=None, n_pupil=None, n_airy=None)

Given 2 of 3 parameters, calculate the third.

Parameters:

• n – The total width of the sampling grid

• n_pupil – The sampling across the pupil

• n_airy – The sampling across the central peak of the Airy disk

Returns: (n, n_pupil, n_airy)

calc_psf_scaling(pupil_grid, ndim, maxdim)

Calculate the input and output grid spacings.

Parameters:

• pupil_grid – A RayGrid instance

• ndim – The sampling across the wavefront

• maxdim – The total width of the sampling grid

Returns:

The linear grid spacing on the entrance pupil delta_xp: The linear grid spacing on the image plane

Return type:

delta_x

calc_psf(wavefront, ndim, maxdim)

Calculate the point spread function of wavefront W.

Parameters:

• wavefront – ndim x ndim Numpy array of wavefront errors. No data condition is indicated by nan

• ndim – The sampling across the wavefront

• maxdim – The total width of the sampling grid

Returns: AP, the PSF of the input wavefront

update_psf_data(pupil_grid, build='rebuild')