Optics

class batoid.Optic(name=None, coordSys=CoordSys(array([0., 0., 0.]), array([[1., 0., 0.], [0., 1., 0.], [0., 0., 1.]])), inMedium=ConstMedium(1.0), outMedium=ConstMedium(1.0), skip=False, **kwargs)

The base class for all varieties of batoid optics and optical systems.

An Optic can include anything from a single reflective or refractive surface to an entire telescope including multiple mirrors and/or lenses.

Parameters:

• name (str, optional) – An name for this optic

• inMedium (batoid.Medium, optional) – Medium in which approaching rays reside. Default: vacuum.

• outMedium (batoid.Medium, optional) – Medium in which rays will leave this optic. Default: vacuum.

• coordSys (batoid.CoordSys, optional) – Coordinate system indicating the position and orientation of this optic’s vertex with respect to the global coordinate system. Default: the global coordinate system.

• skip (bool, optional) – Whether or not to skip this optic when tracing. This can be useful if you want to trace only through part of a compound optic. Default: False.

• **kwargs (other) – Other attributes to add as object attributes.

classmethod fromYaml(filename)

Load an Optic (commonly a complete telescope) from the given yaml file. This is the most common way to create an Optic. If the file is not initially found, then look in the batoid.datadir directory and subdirectories for the first matching filename and use that.

Look in batoid.datadir for examples of how to format a batoid optic yaml file.

Parameters:

filename (str) – Name of yaml file to load

Returns:

Optic

class batoid.Interface(surface, obscuration=None, **kwargs)

Bases: Optic

An Optic representing a single surface. Almost always one of the concrete subclasses (Mirror, RefractiveInterface, Baffle, Detector) should be instantiated, depending on whether rays should reflect, refract, vignette/pass-through, or stop at this surface.

Parameters:

• surface (batoid.Surface) – The surface instance for this Interface.

• obscuration (batoid.Obscuration, optional) – batoid.Obscuration instance indicating which x,y coordinates are obscured/unobscured for rays intersecting this optic. Default: None, which means don’t apply any ray obscuration.

• **kwargs – Other parameters to forward to Optic.__init__

draw3d(ax, plotly=False, **kwargs)

Draw this interface on a mplot3d axis.

Parameters:

• ax (mplot3d.Axis or plotly.graph_objs.Figure) – Axis on which to draw this optic.

• plotly (bool) – Set True to use plotly API instead of ipyvolume/matplotlib API

getXZSlice(nslice=0)

Calculate global coordinates for an (x,z) slice through this interface.

The calculation is split into two half slices: xlocal <= 0 and xlocal >= 0. When the inner radius is zero, these half slices are merged into one. Otherwise, the two half slices are returned separately.

If the local coordinate system involves any rotation the resulting slice may not be calculated correctly since we are really slicing in (xlocal, zlocal) then transforming these to (xglobal, zglobal).

Parameters:

nslice (int) – Use the specified number of points on each half slice. When zero, the value will be calculated automatically (and will be 2 for planar surfaces).

Returns:

tuple – Tuple (xz1, xz2) of 1D arrays where xz1=[x1, z1] is the xlocal <= 0 half slice and xz2=[x2, z2] is the xlocal >= 0 half slice.

draw2d(ax, **kwargs)

Draw this interface on a 2d matplotlib axis. May not work if elements are non-circular or not axis-aligned.

Parameters:

ax (matplotlib.axes.Axes) – Axis on which to draw this optic.

trace(rv, reverse=False)

Trace ray through this optical element.

Parameters:

• rv (batoid.RayVector) – Input rays to trace, transforming in place.

• reverse (bool) – Trace through optical element in reverse? Default: False

Returns:

batoid.RayVector – Reference to transformed input rays.

Notes

This operation is performed in place; the return value is a reference to the transformed input RayVector.

The transformed rays will be expressed in the local coordinate system of the Optic. See RayVector.toCoordSys to express rays in a different coordinate system.

Also, you may need to reverse the directions of rays if using this method with reverse=True.

traceFull(rv, reverse=False)

Trace rays through this optical element, returning a full history of all surface intersections.

Parameters:

• rv (batoid.RayVector) – Input rays to trace

• reverse (bool) – Trace through optical element in reverse? Default: False

Returns:

OrderedDict of dict – There will be one key-value pair for every Interface traced through (which for this class, is just a single Interface). The values will be dicts with key-value pairs:

'name'

name of Interface (str)

'in'

the incoming rays to that Interface (RayVector)

'out'

the outgoing rays from that Interface (RayVector)

Notes

Pay careful attention to the coordinate systems of the returned rays. These will generally differ from the original input coordinate system. To transform to another coordinate system, see RayVector.toCoordSys.

traceSplit(rv, minFlux=0.001, reverse=False, _verbose=False)

Trace rays through this optical element, splitting the return values into rays that continue propagating in the “forward” direction, and those that were reflected into the “reverse” direction. Fluxes of output rays are proportional to reflection/transmission coefficients of the interface (which may depend on wavelength and incidence angle).

Parameters:

• rv (batoid.RayVector) – Input rays to trace

• minFlux (float) – Minimum flux value of rays to continue propagating. Default: 1e-3.

• reverse (bool) – Trace through optic in reverse? Default: False.

Returns:

• forwardRays (list of batoid.RayVector.) – Each item in list comes from one distinct path through the optic exiting in the forward direction. The exact path traversed is accessible from the .path attribute of the item.

• reverseRays (list of batoid.RayVector.) – Each item in list comes from one distinct path through the optic exiting in the reverse direction. The exact path traversed is accessible from the .path attribute of the item.

Notes

Returned rays will be expressed in the local coordinate system of the Optic. See RayVector.toCoordSys to express rays in a different coordinate system.

withGlobalShift(shift)

Return a new Interface with its coordinate system shifted.

Parameters:

shift (array (3,)) – The coordinate shift, relative to the global coordinate system, to apply to self.coordSys

Returns:

Interface – Shifted interface.

withLocalShift(shift)

Return a new Interface with its coordinate system shifted.

Parameters:

shift (array (3,)) – The coordinate shift, relative to the local coordinate system, to apply to self.coordSys

Returns:

Interface – Shifted interface.

withGlobalRotation(rot, rotCenter=None, coordSys=None)

Return a new Interface with its coordinate system rotated.

Parameters:

• rot (array (3,3)) – Rotation matrix wrt to the global coordinate system to apply.

• rotCenter (array (3,)) – Point about which to rotate. Default: None means use [0,0,0]

• coordSys (batoid.CoordSys) – Coordinate system of rotCenter above. Default: None means use the global coordinate system.

Returns:

Interface – Rotated interface.

withLocalRotation(rot, rotCenter=None, coordSys=None)

Return a new Interface with its coordinate system rotated.

Parameters:

• rot (array (3,3)) – Rotation matrix wrt to the local coordinate system to apply.

• rotCenter (array (3,)) – Point about which to rotate. Default: None means use [0,0,0]

• coordSys (batoid.CoordSys) – Coordinate system of rotCenter above. Default: None means use self.coordSys.

Returns:

Interface – Rotated interface.

withSurface(surface)

Return a new Interface with its surface attribute replaced.

Parameters:

surface (batoid.Surface) – New replacement surface.

Returns:

Interface – Interface with new surface.

withPerturbedSurface(perturbation)

Return a new Interface with its surface attribute perturbed by adding the given perturbation to the original surface.

Parameters:

perturbation (batoid.Surface) – Perturbation to apply to the surface.

Returns:

Interface – Interface with perturbed surface.

class batoid.Mirror(*args, **kwargs)

Bases: Interface

Specialization for reflective interfaces.

Rays will interact with this surface by reflecting off of it.

class batoid.RefractiveInterface(*args, **kwargs)

Bases: Interface

Specialization for refractive interfaces.

Rays will interact with this surface by refracting through it.

class batoid.Baffle(*args, **kwargs)

Bases: Interface

Specialization for baffle interfaces.

Rays will interact with this optic by passing straight through. However, the vignetting calculation will still be applied at this Interface.

class batoid.Detector(*args, **kwargs)

Bases: Interface

Specialization for detector interfaces.

Rays will interact with this surface by passing through it. Usually, however, this is the last Optic in a CompoundOptic, so tracing will stop with this Interface.

class batoid.CompoundOptic(items, **kwargs)

Bases: Optic

An Optic containing two or more Optic s as subitems.

Ray traces will be carried out sequentially for the subitems.

Parameters:

• items (list of Optic) – Subitems making up this compound optic.

• **kwargs – Other parameters to forward to Optic.__init__

__getitem__(key)

Dictionary access to the entire hierarchy of subitems of this CompoundOptic.

Either access through the fully-qualified name (optic['LSST.LSSTCamera.L1']) or by partially-qualified name (optic['LSSTCamera.L1'] or even optic['L1']). Note that partially-qualified name access is only available for unique partially-qualified names.

trace(rv, reverse=False, path=None)

Recursively trace through all subitems of this CompoundOptic.

Parameters:

• rv (batoid.RayVector) – Input rays to trace, transforming in place.

• reverse (bool) – Trace through optical element in reverse? Default: False

• path (list of names of Interfaces.) – Trace through the optical system in this order, as opposed to the natural order. Useful for investigating particular ghost images. Note that items included in path will not be skipped, even if their skip attribute is true.

Returns:

batoid.RayVector – Reference to transformed input rays.

Notes

This operation is performed in place; the return value is a reference to the transformed input RayVector.

Returned rays will be expressed in the local coordinate system of the last element of the CompoundOptic. See RayVector.toCoordSys to express rays in a different coordinate system.

Also, you may need to reverse the directions of rays if using this method with reverse=True.

traceFull(rv, reverse=False, path=None)

Recursively trace rays through this CompoundOptic, returning a full history of all surface intersections.

Parameters:

• rv (batoid.RayVector) – Input rays to trace

• reverse (bool) – Trace through optical element in reverse? Default: False

• path (list of names of Interfaces.) – Trace through the optical system in this order, as opposed to the natural order. Useful for investigating particular ghost images. Note that items included in path will not be skipped, even if their skip attribute is true.

Returns:

OrderedDict of dict – There will be one key-value pair for every Interface traced through. The values will be dicts with key-value pairs:

'name'

name of Interface (str)

'in'

the incoming rays to that Interface (RayVector)

'out'

the outgoing rays from that Interface (RayVector)

Notes

Pay careful attention to the coordinate systems of the returned rays. These will generally differ from the original input coordinate system. To transform to another coordinate system, see RayVector.toCoordSys.

traceSplit(rv, minFlux=0.001, reverse=False, _verbose=False)

Recursively trace rays through this CompoundOptic, splitting at each surface.

The return values are rays that continuing in the “forward” direction, and those reflected into the “reverse” direction. Fluxes of output rays are proportional to reflection/transmission coefficients of the interface (which may depend on wavelength and incidence angle). Note that traceSplit is applied recursively, so a single call on a CompoundOptic may result in many combinations of reflections/refractions being applied internally before rays are either deleted by falling below the minFlux or reach the entrace/exit of the CompoundOptic.

Parameters:

• rv (batoid.RayVector) – Input rays to trace

• minFlux (float) – Minimum flux value of rays to continue propagating. Default: 1e-3.

• reverse (bool) – Trace through optic in reverse? Default: False.

Returns:

• forwardRays (list of batoid.RayVector.) – Each item in list comes from one distinct path through the optic exiting in the forward direction. The exact path traversed is accessible from the .path attribute of the item.

• reverseRays (list of batoid.RayVector.) – Each item in list comes from one distinct path through the optic exiting in the reverse direction. The exact path traversed is accessible from the .path attribute of the item.

Notes

Returned forward (reverse) rays will be expressed in the local coordinate system of the last (first) element of the CompoundOptic. See RayVector.toCoordSys to express rays in a different coordinate system.

draw3d(ax, **kwargs)

Recursively draw this CompoundOptic on a mplot3d axis by drawing all subitems.

Parameters:

• ax (mplot3d.Axis or plotly.graph_objs.Figure) – Axis on which to draw this optic.

• plotly (bool) – Set True to use plotly API instead of ipyvolume/matplotlib API

draw2d(ax, **kwargs)

Draw a 2D slice of this CompoundOptic in the (x,z) plane.

Calls draw2d recursively on each of our items, with the actual drawing taking place in Interface and (optionally) Lens instances.

The kwargs are passed to the drawing commands, except for the optional keyword ‘only’ which restricts drawing to only instances that are subclasses of a specified type or types.

Parameters:

• ax (matplotlib.axes.Axes) – Axis on which to draw this optic.

• only (list) – A list of types to draw, e.g., Mirror, or Lens. Default: None means to draw all types.

withGlobalShift(shift)

Return a new CompoundOptic with its coordinate system shifted (and the coordinate systems of all subitems)

Parameters:

shift (array (3,)) – The coordinate shift, relative to the global coordinate system, to apply to self.coordSys

Returns:

CompoundOptic – Shifted optic.

withLocalShift(shift)

Return a new CompoundOptic with its coordinate system shifted.

Parameters:

shift (array (3,)) – The coordinate shift, relative to the local coordinate system, to apply to self.coordSys

Returns:

CompoundOptic – Shifted interface.

withGloballyShiftedOptic(name, shift)

Return a new CompoundOptic with the coordinate system of one of its subitems shifted.

Parameters:

• name (str) – The subitem to shift.

• shift (array (3,)) – The coordinate shift, relative to the global coordinate system, to apply to the subitem’s coordSys.

Returns:

CompoundOptic – Optic with shifted subitem.

withLocallyShiftedOptic(name, shift)

Return a new CompoundOptic with the coordinate system of one of its subitems shifted.

Parameters:

• name (str) – The subitem to shift.

• shift (array (3,)) – The coordinate shift, relative to the local coordinate system of that subitem, to apply to the subitem’s coordSys.

Returns:

CompoundOptic – Optic with shifted subitem.

withGlobalRotation(rot, rotCenter=None, coordSys=None)

Return a new CompoundOptic with its coordinate system rotated.

Parameters:

• rot (array (3,3)) – Rotation matrix wrt to the global coordinate system to apply.

• rotCenter (array (3,)) – Point about which to rotate. Default: None means use [0,0,0]

• coordSys (batoid.CoordSys) – Coordinate system of rotCenter above. Default: None means use the global coordinate system.

Returns:

CompoundOptic – Rotated optic.

withLocalRotation(rot, rotCenter=None, coordSys=None)

Return a new CompoundOptic with its coordinate system rotated.

Parameters:

• rot (array (3,3)) – Rotation matrix wrt to the local coordinate system to apply.

• rotCenter (array (3,)) – Point about which to rotate. Default: None means use [0,0,0]

• coordSys (batoid.CoordSys) – Coordinate system of rotCenter above. Default: None means use self.coordSys.

Returns:

CompoundOptic – Rotated optic.

withLocallyRotatedOptic(name, rot, rotCenter=None, coordSys=None)

Return a new CompoundOptic with the coordinate system of one of its subitems rotated.

Parameters:

• name (str) – The subitem to rotate.

• rot (array (3,3)) – Rotation matrix wrt to the subitem’s local coordinate system to apply.

• rotCenter (array (3,)) – Point about which to rotate. Default: None means use [0,0,0]

• coordSys (batoid.CoordSys) – Coordinate system of rotCenter above. Default: None means use the coordinate system of the subitem being rotated.

Returns:

CompoundOptic – Optic with rotated subitem.

withSurface(name, surface)

Return a new CompoundOptic with one of its subitem’s surfaces attribute replaced.

Parameters:

• name (str) – Which subitem’s surface to replace.

• surface (batoid.Surface) – New replacement surface.

Returns:

CompoundOptic – Optic with new surface.

withPerturbedSurface(name, perturbation)

Return a new CompoundOptic with one of its subitem’s surfaces attribute perturbed by adding the given perturbation to the original surface.

Parameters:

• name (str) – Which subitem’s surface to replace.

• perturbation (batoid.Surface) – Surface to add to the original surface.

Returns:

CompoundOptic – Optic with perturbed surface.

class batoid.Lens(items, **kwargs)

Bases: CompoundOptic

An lens with two Interface s as front and back surfaces.

Parameters:

• items (list of batoid.Optic, len (2,)) – Subitems making up this compound optic.

• **kwargs – Other parameters to forward to CompoundOptic.__init__

draw2d(ax, **kwargs)

Specialized draw2d for Lens instances.

If the optional keyword ‘only’ equals Lens, then fill the area between the lens refractive interfaces using the remaining specified kwargs (fc, ec, alpha, …)

Otherwise, call draw2d on each of our refractive interfaces.

The optional labelpos and fontdict kwargs are used to draw a label at the specified x position (in global coords), using the specified font properties.