Factory

The factory module provides DonutFactory and a set of coordinate-transform utilities for mapping between pupil and focal planes.

DonutFactory

danish.factory.DonutFactory module-attribute

DonutFactory = DonutInverseFactory

Coordinate transforms

danish.factory.pupil_to_focal

pupil_to_focal(u, v, *, Z=None, aberrations=None, R_outer=1.0, R_inner=0.0, focal_length=None, x_offset=None, y_offset=None)

Transform pupil coordinates to focal coordinates.

Parameters:

Name	Type	Description	Default
u	array of float	Pupil coordinates in meters.	required
v	array of float	Pupil coordinates in meters.	required
Z	Zernike	Aberrations in meters.	None
aberrations	array of float	Aberrations in meters.	None
R_outer	float	Annulus outer and inner radii in meters.	1.0
R_inner	float	Annulus outer and inner radii in meters.	1.0
focal_length	float	Focal length in meters.	None
x_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None
y_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None

Returns:

Type	Description
x, y : array of float	Focal coordinates in meters.

Source code in danish/factory.py

def pupil_to_focal(
    u, v, *,
    Z=None, aberrations=None, R_outer=1.0, R_inner=0.0,
    focal_length=None,
    x_offset=None, y_offset=None
):
    """Transform pupil coordinates to focal coordinates.

    Parameters
    ----------
    u, v : array of float
        Pupil coordinates in meters.
    Z : galsim.zernike.Zernike, optional
        Aberrations in meters.
    aberrations : array of float, optional
        Aberrations in meters.
    R_outer, R_inner : float, optional
        Annulus outer and inner radii in meters.
    focal_length : float
        Focal length in meters.
    x_offset, y_offset : galsim.zernike.Zernike, optional
        Additional focal plane offsets (in meters) represented as Zernike
        series.

    Returns
    -------
    x, y : array of float
        Focal coordinates in meters.
    """
    if Z is None:
        Z = galsim.zernike.Zernike(
            aberrations, R_outer=R_outer, R_inner=R_inner
        )
    if focal_length is None:
        raise ValueError("Missing focal length")

    return _pupil_to_focal(
        u, v, Z,
        focal_length=focal_length,
        x_offset=x_offset, y_offset=y_offset
    )

danish.factory.focal_to_pupil

focal_to_pupil(x, y, *, Z=None, aberrations=None, R_outer=1.0, R_inner=0.0, focal_length=None, x_offset=None, y_offset=None, prefit_order=F2P_PREFIT_ORDER, maxiter=F2P_MAXITER, tol=F2P_TOL, strict=F2P_STRICT)

Transform focal coordinates to pupil coordinates.

Parameters:

Name	Type	Description	Default
x	array of float	Focal coordinates in meters.	required
y	array of float	Focal coordinates in meters.	required
Z	Zernike	Aberrations in meters.	None
aberrations	array of float	Aberrations in meters.	None
R_outer	float	Annulus outer and inner radii in meters.	1.0
R_inner	float	Annulus outer and inner radii in meters.	1.0
focal_length	float	Focal length in meters.	None
x_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None
y_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None
prefit_order	int	Order of prefit used to get good initial guesses for coordinate transformation.	F2P_PREFIT_ORDER
maxiter	int	Number of Newton iterations to attempt before failing.	F2P_MAXITER
tol	float	Tolerance for successful coordinate transformation.	F2P_TOL
strict		If True, then raise a RuntimeError if any coordinates could not be mapped. If False, then return NaN for unmappable coordinates.	F2P_STRICT

Returns:

Type	Description
u, v : array of float	Pupil coordinates in meters.

Source code in danish/factory.py

def focal_to_pupil(
    x, y, *,
    Z=None, aberrations=None, R_outer=1.0, R_inner=0.0,
    focal_length=None,
    x_offset=None, y_offset=None,
    prefit_order=F2P_PREFIT_ORDER, maxiter=F2P_MAXITER, tol=F2P_TOL, strict=F2P_STRICT
):
    """Transform focal coordinates to pupil coordinates.

    Parameters
    ----------
    x, y : array of float
        Focal coordinates in meters.
    Z : galsim.zernike.Zernike, optional
        Aberrations in meters.
    aberrations : array of float, optional
        Aberrations in meters.
    R_outer, R_inner : float, optional
        Annulus outer and inner radii in meters.
    focal_length : float
        Focal length in meters.
    x_offset, y_offset : galsim.zernike.Zernike, optional
        Additional focal plane offsets (in meters) represented as Zernike
        series.
    prefit_order : int
        Order of prefit used to get good initial guesses for coordinate
        transformation.
    maxiter : int
        Number of Newton iterations to attempt before failing.
    tol : float
        Tolerance for successful coordinate transformation.
    strict: bool
        If True, then raise a RuntimeError if any coordinates could not be
        mapped.
        If False, then return NaN for unmappable coordinates.

    Returns
    -------
    u, v : array of float
        Pupil coordinates in meters.
    """
    if Z is None:
        Z = galsim.zernike.Zernike(
            aberrations, R_outer=R_outer, R_inner=R_inner
        )
    if focal_length is None:
        raise ValueError("Missing focal length")

    return _focal_to_pupil(
        x, y, Z,
        focal_length=focal_length,
        x_offset=x_offset, y_offset=y_offset,
        prefit_order=prefit_order,
        maxiter=maxiter,
        tol=tol, strict=strict
    )

danish.factory.pupil_focal_jacobian

pupil_focal_jacobian(u, v, *, Z=None, aberrations=None, R_outer=1.0, R_inner=0.0, focal_length=None, x_offset=None, y_offset=None)

Compute Jacobian of the pupil-to-focal coordinate transform.

Parameters:

Name	Type	Description	Default
u	array of float	Pupil coordinates in meters.	required
v	array of float	Pupil coordinates in meters.	required
Z	Zernike	Aberrations in meters.	None
aberrations	array of float	Aberrations in meters.	None
R_outer	float	Annulus outer and inner radii in meters.	1.0
R_inner	float	Annulus outer and inner radii in meters.	1.0
focal_length	float	Focal length in meters.	None
x_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None
y_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None

Returns:

Type	Description
dxdu, dxdv, dydu, dydv : array of float	Jacobian of focal coordinates with respect to pupil coordinates.

Source code in danish/factory.py

def pupil_focal_jacobian(
    u, v, *,
    Z=None, aberrations=None, R_outer=1.0, R_inner=0.0,
    focal_length=None,
    x_offset=None, y_offset=None
):
    """Compute Jacobian of the pupil-to-focal coordinate transform.

    Parameters
    ----------
    u, v : array of float
        Pupil coordinates in meters.
    Z : galsim.zernike.Zernike, optional
        Aberrations in meters.
    aberrations : array of float, optional
        Aberrations in meters.
    R_outer, R_inner : float, optional
        Annulus outer and inner radii in meters.
    focal_length : float
        Focal length in meters.
    x_offset, y_offset : galsim.zernike.Zernike, optional
        Additional focal plane offsets (in meters) represented as Zernike
        series.

    Returns
    -------
    dxdu, dxdv, dydu, dydv : array of float
        Jacobian of focal coordinates with respect to pupil coordinates.
    """
    if Z is None:
        Z = galsim.zernike.Zernike(
            aberrations, R_outer=R_outer, R_inner=R_inner
        )
    if focal_length is None:
        raise ValueError("Missing focal length")

    return _pupil_focal_jacobian(
        u, v, Z,
        focal_length=focal_length,
        x_offset=x_offset, y_offset=y_offset
    )

Pupil sampling

danish.factory.enclosed_fraction

enclosed_fraction(x, y, u, v, u0, v0, radius, *, Z=None, aberrations=None, R_outer=1.0, R_inner=0.0, focal_length=None, x_offset=None, y_offset=None, pixel_scale=None)

Compute fraction of pixels enclosed by circles defined on the pupil.

Parameters:

Name	Type	Description	Default
x	array of float	Pixel coordinates.	required
y	array of float	Pixel coordinates.	required
u	array of float	Pupil coordinates in meters.	required
v	array of float	Pupil coordinates in meters.	required
u0	float	Pupil coordinates of circle center in meters.	required
v0	float	Pupil coordinates of circle center in meters.	required
radius	float	Circle radius in meters.	required
Z	Zernike	Aberrations in meters.	None
aberrations	array of float	Aberrations in meters.	None
R_outer	float	Annulus outer and inner radii in meters.	1.0
R_inner	float	Annulus outer and inner radii in meters.	1.0
focal_length	float	Focal length in meters.	None
x_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None
y_offset	Zernike	Additional focal plane offsets (in meters) represented as Zernike series.	None
pixel_scale	float	Pixel scale in meters.	None

Returns:

Name	Type	Description
enclosed	array of float, congruent to x or y	Each pixel's enclosed fraction between 0, 1.

Source code in danish/factory.py

def enclosed_fraction(
    x, y,
    u, v,
    u0, v0, radius, *,
    Z=None, aberrations=None, R_outer=1.0, R_inner=0.0,
    focal_length=None,
    x_offset=None, y_offset=None,
    pixel_scale=None,
):
    """Compute fraction of pixels enclosed by circles defined on the pupil.

    Parameters
    ----------
    x, y : array of float
        Pixel coordinates.
    u, v : array of float
        Pupil coordinates in meters.
    u0, v0 : float
        Pupil coordinates of circle center in meters.
    radius : float
        Circle radius in meters.
    Z : galsim.zernike.Zernike, optional
        Aberrations in meters.
    aberrations : array of float, optional
        Aberrations in meters.
    R_outer, R_inner : float, optional
        Annulus outer and inner radii in meters.
    focal_length : float
        Focal length in meters.
    x_offset, y_offset : galsim.zernike.Zernike, optional
        Additional focal plane offsets (in meters) represented as Zernike
        series.
    pixel_scale : float
        Pixel scale in meters.

    Returns
    -------
    enclosed : array of float, congruent to x or y
        Each pixel's enclosed fraction between 0, 1.
    """

    if Z is None:
        Z = galsim.zernike.Zernike(
            aberrations, R_outer=R_outer, R_inner=R_inner
        )
    if focal_length is None:
        raise ValueError("Missing focal length")
    if pixel_scale is None:
        raise ValueError("Missing pixel scale")

    Z1 = Z * focal_length if focal_length else Z

    dudx, dudy, dvdx, dvdy = _pixel_pupil_jacobian(
        u, v, Z1,
        pixel_scale=pixel_scale,
        x_offset=x_offset, y_offset=y_offset
    )

    return _enclosed_fraction(
        x, y, u, v, u0, v0, radius,
        dudx=dudx, dudy=dudy, dvdx=dvdx, dvdy=dvdy
    )