v3.2.0

This release outlines the beam on any surface of a sequential system, and keys the cache on everything that can change a cached result. It requires named-arrays 2.15.

The outline of the beam on a surface (#258)

AbstractSequentialSystem.beam_footprint(index, wavelength=None, samples_field_stop=401, samples_pupil_stop=401) returns the outline of the beam on one surface of a system. That is the convex hull of the points where the light reaching the end of the system crosses that surface. The outline is a PolygonalAperture in the surface's local coordinates. An aperture with a transformation of its own gives its vertices before that transformation, so on a stop the outline matches aperture.transformation(aperture.vertices).

• The rays: the outline is the hull of the rays which graze the edges of both stops, together with the rays of the default grid. Only the rays that reach the end of the system count.
  • The rays along the edges are solved for as rayfunction_stops solves them, at as many samples along each edge as asked for, and traced through the whole system. Both stops are left open for this trace, since rounding would block about half of the rays on their edges.
  • Where another aperture cuts the beam, the corners where its edge crosses the outline of the beam are found from the rays along the edges, to within the spacing of the samples.
  • The grid fills in what the edges miss, to within its spacing: a corner of another aperture inside the beam, or a beam which an aperture smaller than it bounds instead of the stops. So the outline holds every ray of the grid which reaches the end.
• Accuracy: a grid over the field and the pupil finds the corners of the hull only to within its spacing, which shrinks as the fourth root of the number of rays. Here are the footprints of ESIS on its primary mirror, compared with the hull of a grid of a billion rays:
  • A grid of 1.2 million rays falls 2 mm short of that hull.
  • 401 × 401 samples along the edges of the stops, about a million rays in 4 s, contain it to within 3 µm.
  • Doubling the samples along the edges moves the outline by less than 0.08 mm.

Limitations:

• Where the stops don't bound the beam, the outline is only as close to it as the default grid is fine.
• Curved cuts: where an aperture other than the stops cuts the outside of the beam along a curve, the outline cuts straight across from one corner to the next. Apertures with straight edges are outlined exactly.
• Uncertain systems aren't supported yet, since na.geometry.convex_hull doesn't support uncertain components.

A cache keyed on the code, the data and the dependencies (#254)

optika.memory used to key each cache entry on the source of the decorated function alone. So a change to the code that function calls, or to the data it reads, left the old result in place. That is what kept the refitted CCD diffusion models of #244 and #251 from appearing until their cache directories were deleted by hand.

optika.memory now lives in ~/.optika/cache/<fingerprint>, where the fingerprint is a hash of three things:

• The code of optika: the contents of each module, except the tests.
• The data of optika: the size and modification time of each data file.
• The dependencies: the versions of named-arrays, numpy, scipy and astropy.

Identical code shares a cache, so a reinstall, a new environment, or switching to another branch and back reuses the old results. Hidden files, bytecode caches, other kinds of files and files that can't be read are skipped. It adds about 33 ms to import optika.

Behavior changes:

• Every cached result is computed again once, in a new directory.
• An edit to an editable install of named-arrays, numpy, scipy or astropy doesn't change its version. So the cache must be cleared with optika.memory.clear() after one.
• Old cache directories are never removed, since two environments in use at once would delete each other's caches. They are small and can be deleted at any time, as can the old entries directly under ~/.optika/cache/optika.

Full Changelog: v3.1.0...v3.2.0