Optics — batoid 0.4.2 documentation

# 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.