Full API

Core

Fields

class hcipy.field.Grid(coords, weights=None)

Bases: object

A set of points on some coordinate system.

Parameters
coordsCoordsBase

The actual definition of the coordinate values.

weightsarray_like or None

The interval size, area, volume or hypervolume of each point, depending on the number of dimensions. If this is None (default), the weights will be attempted to be calculated on the fly when needed.

Attributes
coords

The coordinate values for each dimension.

as_(self, system)

Convert the grid to the new coordinate system system.

If the grid is already in the right coordinate system, this function doesn’t do anything.

Parameters
systemstr

The name of the coordinate system to check for.

Returns
Grid

A new Grid in the required coordinate system.

Raises
ValueError

If the conversion to the coordinate system system isn’t known.

closest_to(self, p)

Get the index of the point closest to point p.

Point p is assumed to have the same coordinate system as the grid itself.

Parameters
parray_like

The point at which to search for.

Returns
int

The index of the closest point.

copy(self)

Create a copy.

property delta

The spacing between points in regularly-spaced grid.

Raises
ValueError

If the grid is not regular.

property dims

The number of elements in each dimension for a separated grid.

Raises
ValueError

If the grid is not separated.

empty(self, tensor_shape=None, dtype=None)

Create an empty Field from this Grid.

Parameters
tensor_shapearray_like or None

The shape of the tensors in the to be created field. If this is None, a scalar field will be created.

dtypedata-type

The numpy data-type with which to create the field.

Returns
Field

A empty field.

is_(self, system)

Check if the coordinate system is system.

Parameters
systemstr

The name of the coordinate system to check for.

Returns
bool

If the coordinate system of the grid is equal to system.

property is_regular

True if the grid is regularly-spaced, False otherwise.

property is_separated

True if the grid is separated, False otherwise.

property is_unstructured

True if the grid is unstructured, False otherwise.

property ndim

The number of dimensions.

ones(self, tensor_shape=None, dtype=None)

Create a field of ones from this Grid.

Parameters
tensor_shapearray_like or None

The shape of the tensors in the to be created field. If this is None, a scalar field will be created.

dtypedata-type

The numpy data-type with which to create the field.

Returns
Field

A ones field.

property points

A list of points of this grid.

This can be used for easier iteration:

for p in grid.points:
        print(p)
property regular_coords

The tuple (delta, dims, zero) for a regularly-spaced grid.

Raises
ValueError

If the grid is not regular.

reverse(self)

Reverse the order of the points in-place.

Returns
Grid

Itself to allow for chaining these transformations.

reversed(self)

Make a copy of the grid with the order of the points reversed.

Returns
Grid

The reversed grid.

rotate(self, angle, axis=None)

Rotate the grid in-place.

Parameters
anglescalar

The angle in radians.

axisndarray or None

The axis of rotation. For two-dimensional grids, it is ignored. For three-dimensional grids it is required.

Returns
Grid

Itself to allow for chaining these transformations.

rotated(self, angle, axis=None)

A rotated copy of this grid.

Parameters
anglescalar

The angle in radians.

axisndarray or None

The axis of rotation. For two-dimensional grids, it is ignored. For three-dimensional grids it is required.

Returns
Grid

The rotated grid.

scale(self, scale)

Scale the grid in-place.

Parameters
scalearray_like

The factor with which to scale the grid.

Returns
Grid

Itself to allow for chaining these transformations.

scaled(self, scale)

A scaled copy of this grid.

Parameters
scalearray_like

The factor with which to scale the grid.

Returns
Grid

The scaled grid.

property separated_coords

A list of coordinates for each dimension in a separated grid.

Raises
ValueError

If the grid is not separated.

property shape

The shape of a reshaped numpy.ndarray using this grid.

Raises
ValueError

If the grid is not separated.

shift(self, shift)

Shift the grid in-place.

Parameters
shiftarray_like

The amount with which to shift the grid.

Returns
Grid

Itself to allow for chaining these transformations.

shifted(self, shift)

A shifted copy of this grid.

Parameters
shiftarray_like

The amount with which to shift the grid.

Returns
Grid

The scaled grid.

property size

The number of points in this grid.

subset(self, criterium)

Construct a subset of the current sampling, based on criterium.

Parameters
criteriumfunction or array_like

The criterium used to select points. A function will be evaluated for every point. Otherwise, this must be a boolean array of integer array, used for slicing the points.

Returns
Grid

A new grid with UnstructuredCoords that includes only the points for which the criterium was true.

property weights

The interval size, area, volume or hypervolume of each point, depending on the number of dimensions.

The weights are attempted to be calculated on the fly if not set. If this fails, a warning is emitted and all points will be given an equal weight of one.

property zero

The zero point of a regularly-spaced grid.

Raises
ValueError

If the grid is not regular.

zeros(self, tensor_shape=None, dtype=None)

Create a field of zeros from this Grid.

Parameters
tensor_shapearray_like or None

The shape of the tensors in the to be created field. If this is None, a scalar field will be created.

dtypedata-type

The numpy data-type with which to create the field.

Returns
Field

A zeros field.

class hcipy.field.UnstructuredCoords(coords)

Bases: hcipy.field.coordinates.CoordsBase

An unstructured list of points.

Parameters
coordslist or tuple

A tuple of a list of positions for each dimension.

reverse(self)

Reverse the ordering of points in-place.

property size

The number of points.

class hcipy.field.SeparatedCoords(separated_coords)

Bases: hcipy.field.coordinates.CoordsBase

A list of points that are separable along each dimension.

The actual points are given by the iterated tensor product of the separated_coords.

Parameters
separated_coordslist or tuple

A tuple of a list of coordinates along each dimension.

Attributes
separated_coords

A tuple of a list of coordinates along each dimension.

property dims

The number of points along each dimension.

reverse(self)

Reverse the ordering of points in-place.

property shape

The shape of an numpy.ndarray with the right dimensions.

property size

The number of points.

class hcipy.field.RegularCoords(delta, dims, zero=None)

Bases: hcipy.field.coordinates.CoordsBase

A list of points that have a regular spacing in all dimensions.

Parameters
deltaarray_like

The spacing between the points.

dimsarray_like

The number of points along each dimension.

zeroarray_like

The coordinates for the first point.

Attributes
delta

The spacing between the points.

dims

The number of points along each dimension.

zero

The coordinates for the first point.

property regular_coords

The tuple (delta, dims, zero) of the regularly-spaced coordinates.

reverse(self)

Reverse the ordering of points in-place.

property separated_coords

A tuple of a list of the values for each dimension.

The actual points are the iterated tensor product of this tuple.

property shape

The shape of an numpy.ndarray with the right dimensions.

property size

The number of points.

class hcipy.field.CartesianGrid(coords, weights=None)

Bases: hcipy.field.grid.Grid

A grid representing a N-dimensional Cartesian coordinate system.

rotate(self, angle, axis=None)

Rotate the grid in-place.

Caution

All structure in the coordinates will be destroyed.

Parameters
anglescalar

The angle in radians.

axisndarray or None

The axis of rotation. For two-dimensional grids, it is ignored. For three-dimensional grids it is required.

Returns
Grid

Itself to allow for chaining these transformations.

rotated(self, angle, axis=None)

A rotated copy of this grid.

Parameters
anglescalar

The angle in radians.

axisndarray or None

The axis of rotation. For two-dimensional grids, it is ignored. For three-dimensional grids it is required.

Returns
Grid

The rotated grid.

scale(self, scale)

Scale the grid in-place.

Parameters
scalearray_like or scalar

The factor with which to scale the grid.

Returns
Grid

Itself to allow for chaining these transformations.

shift(self, shift)

Shift the grid in-place.

Parameters
shiftarray_like

The amount with which to shift the grid.

Returns
Grid

Itself to allow for chaining these transformations.

property w

The w-coordinate (dimension 3).

property x

The x-coordinate (dimension 0).

property y

The y-coordinate (dimension 1).

property z

The z-coordinate (dimension 2).

hcipy.field.field_inverse_tikhonov(f, rcond=1e-15)

Invert a tensor field of order 2 using Tikhonov regularization.

Parameters
fField

The tensor field for which to calculate the inverses. The tensor order of this Field has to be 2.

rcondscalar

The relative regularization parameter to use for the inversions.

Returns
Field

The resulting Field with tensor order 2.

Raises
ValueError

If the tensor order of field f is not 2.

hcipy.field.field_svd(f, full_matrices=True, compute_uv=True)

Calculate the singular value decomposition for a tensor field of order 2.

Parameters
fField

The tensor field for which to calculate the singular value decompositions.

full_matricesboolean

If True, matrices in U and Vh will have shapes (M,M) and (N,N) respectively. Otherwise their shapes are (M,K), (K,N) respectively, where K=min(M,N).

compute_uvboolean

Whether to compute matrices U and Vh in addition to the singular values.

Returns
UField

The unitary matrices. Only returned if compute_uv is True.

SField

The singular values, sorted in descending order.

VhField

The unitary matrices. Only returned if compute_uv is True.

hcipy.field.make_field_operation(op)
hcipy.field.field_conjugate_transpose(a)

Performs the conjugate transpose of a rank 2 tensor field.

Parameters
aField

The field to conjugate transpose

Returns
Field

The conjugate transposed field

hcipy.field.field_transpose(a)

Performs the transpose of a rank 2 tensor field.

Parameters
aField

The field to transpose

Returns
Field

The transposed field

hcipy.field.field_determinant(a)

Calculates the determinant of a tensor field.

Parameters
aField

The field for which the determinant needs to be calculated

Returns
Field

The field that contains the determinant on every spatial position

hcipy.field.field_adjoint(a)

Calculates the adjoint of a tensor field.

Parameters
aField

The field for which the adjoint needs to be calculated

Returns
Field

The adjointed field

hcipy.field.field_cross(a, b)

Calculates the cross product of two vector fields.

Parameters
aField

The first field of the cross product

bField

The second field of the cross product

Returns
Field

The cross product field

class hcipy.field.PolarGrid(coords, weights=None)

Bases: hcipy.field.grid.Grid

A grid representing a two-dimensional Polar coordinate system.

property r

The radial coordinate (dimension 0).

rotate(self, angle, axis=None)

Rotate the grid in-place.

Parameters
anglescalar

The angle in radians.

axisndarray or None

The axis of rotation. For this (polar) grid, it is ignored.

Returns
Grid

Itself to allow for chaining these transformations.

scale(self, scale)

Scale the grid in-place.

Parameters
scalearray_like

The factor with which to scale the grid.

Returns
Grid

Itself to allow for chaining these transformations.

shift(self, shift)

Shift the grid in-place.

Caution

All structure in the coordinates will be destroyed.

Parameters
shiftarray_like

The amount with which to shift the grid.

Returns
Grid

Itself to allow for chaining these transformations.

shifted(self, shift)

A shifted copy of this grid.

Caution

The returned grid is a Cartesian grid.

Parameters
shiftarray_like

The amount with which to shift the grid.

Returns
Grid

The scaled grid.

property theta

The angular coordinate (dimension 1).

class hcipy.field.Field

Bases: numpy.ndarray

The value of some physical quantity for each point in some coordinate system.

Parameters
arrarray_like

An array of values or tensors for each point in the Grid.

gridGrid

The corresponding Grid on which the values are set.

Attributes
gridGrid

The grid on which the values are defined.

at(self, p)

The value of this field closest to point p.

Parameters
parray_like

The point at which the closest value should be returned.

Returns
array_like

The value, potentially tensor, closest to point p.

property is_scalar_field

True if this field is a scalar field (ie. a tensor order of 0), False otherwise.

property is_valid_field

True if the field corresponds with its grid.

property is_vector_field

True if this field is a vector field (ie. a tensor order of 1), False otherwise.

property shaped

The reshaped version of this field.

Raises
ValueError

If this field isn’t separated, no reshaped version can be made.

property tensor_order

The order of the tensor of the field.

property tensor_shape

The shape of the tensor of the field.

hcipy.field.field_einsum(subscripts, *operands, **kwargs)

Evaluates the Einstein summation convention on the operand fields.

This function uses the same conventions as numpy.einsum(). The input subscript is multiplexed over each position in the grid. The grids of each of the input field operands don’t have to match, but must have the same lengths.

The subscripts must be written as you would for a single position in the grid. The function alters these subscripts to multiplex over the entire grid.

Caution

Some subscripts may yield no exception, even though they would fail for a single point in the grid. The output in these cases can not be trusted.

Parameters
subscriptsstr

Specifies the subscripts for summation.

operandslist of array_like or Field

These are the arrays or fields for the operation.

out{ndarray, None}, optional

If provided, the calculation is done into this array.

dtype{data-type, None}, optional

If provided, forces the calculation to use the data type specified. Note that you may have to also give a more liberal casting parameter to allow the conversions. Default is None.

order{‘C’, ‘F’, ‘A’, ‘K’}, optional

Controls the memory layout of the output. ‘C’ means it should be C contiguous. ‘F’ means it should be Fortran contiguous, ‘A’ means it should be ‘F’ if the inputs are all ‘F’, ‘C’ otherwise. ‘K’ means it should be as close to the layout as the inputs as is possible, including arbitrarily permuted axes. Default is ‘K’.

casting{‘no’, ‘equiv’, ‘safe’, ‘same_kind’, ‘unsafe’}, optional

Controls what kind of data casting may occur. Setting this to ‘unsafe’ is not recommended, as it can adversely affect accumulations.

  • ‘no’ means the data types should not be cast at all.

  • ‘equiv’ means only byte-order changes are allowed.

  • ‘safe’ means only casts which can preserve values are allowed.

  • ‘same_kind’ means only safe casts or casts within a kind,

    like float64 to float32, are allowed.

  • ‘unsafe’ means any data conversions may be done.

Default is ‘safe’.

optimize{False, True, ‘greedy’, ‘optimal’}, optional

Controls if intermediate optimization should occur. No optimization will occur if False and True will default to the ‘greedy’ algorithm. Also accepts an explicit contraction list from the np.einsum_path function. See np.einsum_path for more details. Default is False.

Returns
Field

The calculated Field based on the Einstein summation convention.

Raises
ValueError

If all of the fields don’t have the same grid size. If the number of operands is not equal to the number of subscripts specified.

hcipy.field.field_dot(a, b, out=None)

Perform a dot product of a and b multiplexed over the field dimension.

Parameters
aField or array_like

Left argument of the dot product.

bField or array_like

Right argument of the dot product.

outField or array_like

If provided, the calculation is done into this array.

Returns
Field

The result of the dot product.

hcipy.field.field_trace(a, out=None)
hcipy.field.field_inv(a)
hcipy.field.make_uniform_grid(dims, extent, center=0, has_center=False)

Create a uniformly-spaced Grid of a certain shape and size.

Parameters
dimsscalar or ndarray

The number of points in each dimension. If this is a scalar, it will be multiplexed over all dimensions.

extentscalar or ndarray

The total extent of the grid in each dimension.

centerscalar or ndarray

The center point. The grid will by symmetric around this point.

has_centerboolean

Does the grid has to have the center as one of its points. If this is False, this does not mean that the grid will not have the center.

Returns
Grid

A Grid with RegularCoords.

hcipy.field.make_pupil_grid(dims, diameter=1)

Makes a new Grid, meant for descretisation of a pupil-plane wavefront.

This grid is symmetric around the origin, and therefore has no point exactly on the origin for an even number of pixels.

Parameters
dimsndarray or integer

The number of pixels per dimension. If this is an integer, this number of pixels is used for all dimensions.

diameterndarray or scalar

The diameter of the grid in each dimension. If this is a scalar, this diameter is used for all dimensions.

Returns
Grid

A CartesianGrid with RegularCoords.

hcipy.field.make_focal_grid_from_pupil_grid(pupil_grid, q=1, num_airy=None, focal_length=1, wavelength=1)

Make a grid for a focal plane from a pupil grid.

Calculate the focal grid corresponding to the pupil grid, using an FFT grid as a guide. The resulting grid focal will always contain the origin (0, 0) point. The extent of the pupil grid will be used as the diameter of the pupil. If the pupil is undersized on the pupil grid, the resulting focal grid needs to be rescaled manually.

Note

In almost all cases, it is preferable to use make_focal_grid_replacement(). This function allows you to directly set the diameter, and doesn’t require the user to pass the pupil grid as an argument. make_focal_grid_from_pupil_grid() retains old functionality and serves as a backwards compatibility function, due to its ubiquitous usage in HCIPy code. make_focal_grid_from_pupil_grid() will be deprecated in future versions, and new code should aim to use its replacement.

Parameters
pupil_gridGrid

The pupil grid for which the focal grid needs to be calculated. The extent of this Grid is used as the diameter of the pupil.

qscalar or array_like

The number of pixels per resolution element (= lambda f / D).

num_airyscalar or array_like

The spatial extent of the grid in radius in resolution elements (= lambda f / D).

focal_lengthscalar

The focal length used for calculating the spatial resolution at the focal plane.

wavelengthscalar

The reference wavelength used for calculating the spatial resolution at the focal plane.

Returns
Grid

A Grid describing the sampling for a focal plane.

hcipy.field.make_focal_grid_replacement(q, num_airy, spatial_resolution=None, pupil_diameter=None, focal_length=None, reference_wavelength=None)

Make a grid for a focal plane.

This grid will be a CartesianGrid with RegularCoords, and supports different resolutions, samplings, or extent in x and y. If spatial_resolution is 1, then the grid will be returned in normalized (ie. homogenized) coordinates. Otherwise, it will be in physical units. The spatial resolution is defined by:

\[\Delta x = \lambda f / D = \lambda F\]

where \(\lambda\) is the wavelength, \(f\) is the effective focal length before the focal plane, \(D\) is the diameter of the pupil, and \(F\) is the F-number of the incoming light beam. You can supply either the spatial resolution or a set of focal length, reference wavelength and pupil diameter. If none are supplied, a spatial resolution of 1 will be assumed, meaning normalized units.

The grid will always contain the origin (0, 0) point.

This function will be renamed to make_focal_grid after the next update.

Parameters
qscalar or array_like

The number of pixels per resolution element (= lambda f / D).

num_airyscalar or array_like

The spatial extent of the grid in radius in resolution elements (= lambda f / D).

spatial_resolutionscalar or array_like

The physical size of a resolution element (= lambda f / D). It this is not given, the spatial resolution will be calculated from the given focal_length, reference_wavelength and pupil_diameter.

pupil_diameterscalar or array_like

The diameter of the pupil. If it is an array, this indicates the diameter in x and y.

focal_lengthscalar

The focal length used for calculating the spatial resolution at the focal plane.

reference_wavelengthscalar

The reference wavelength used for calculating the spatial resolution at the focal plane.

Returns
Grid

A Grid describing the sampling for a focal plane.

Raises
ValueError

If both no spatial resolution and no complete set of (focal length, reference wavelength and pupil diameter) was supplied.

hcipy.field.make_focal_grid(*args, **kwargs)
hcipy.field.make_hexagonal_grid(circum_diameter, n_rings, pointy_top=False, center=None)

Make a regular hexagonal grid.

Parameters
circum_diameterscalar

The circum diameter of the hexagons in the grid.

n_ringsinteger

The number of rings in the grid.

pointy_topboolean

If the hexagons contained in the grid.

centerndarray

The center of the grid in cartesian coordinates.

Returns
Grid

A CartesianGrid with UnstructuredCoords, indicating the center of the hexagons.

hcipy.field.make_chebyshev_grid(dims, minimum=None, maximum=None)
hcipy.field.make_supersampled_grid(grid, oversampling)

Make a new grid that oversamples by a factor oversampling.

Note

The Grid grid must be a grid with separable coordinates.

Parameters
gridGrid

The grid that we want to oversample.

oversamplinginteger or scalar or ndarray

The factor by which to oversample. If this is a scalar, it will be rounded to the nearest integer. If this is an array, a different oversampling factor will be used for each dimension.

Returns
Grid

The oversampled grid.

hcipy.field.make_subsampled_grid(grid, undersampling)

Make a new grid that undersamples by a factor undersampling.

Note

The dimensions of the grid must be divisible by undersampling.

Parameters
gridGrid

The grid that we want to oversample.

undersamplinginteger or scalar or ndarray

The factor by which to undersample. If this is a scalar, it will be rounded to the nearest integer. If this is an array, a different undersampling factor will be used for each dimension.

Returns
Grid

The undersampled grid.

hcipy.field.subsample_field(field, subsampling, new_grid=None, statistic='mean')

Average the field over subsampling pixels in each dimension.

Note

The dimensions of the grid of field must be divisible by subsampling.

Parameters
fieldField

The field to subsample. The grid of this field must have the right dimensions to be able to be subsampled.

subsamplinginteger or scalar or ndarray

The subsampling factor. If this is a scalar, it will be rounded to the nearest integer. If this is an array, the subsampling factor will be different for each dimension.

new_gridGrid

If this grid is given, no new grid will be calculated and this grid will be used instead. This saves on calculation time if your new grid is already known beforehand.

statisticstring or callable

The statistic to compute (default is ‘mean’). The following statistics are available:

  • ‘mean’ : compute the mean of values for points within each superpixel.

  • ‘median’ : compute the median of values for points within each superpixel.

  • ‘sum’ : compute the sum of values for points within each superpixel. This is identical to a weighted histogram.

  • ‘min’ : compute the minimum of values for points within each superpixel.

  • ‘max’ : compute the maximum of values for point within each superpixel.

Returns
Field

The subsampled field.

hcipy.field.evaluate_supersampled(field_generator, grid, oversampling, statistic='mean', make_sparse=True)

Evaluate a Field generator on grid, with an oversampling.

Parameters
field_generatorField generator or list of Field generators

The field generator to evaluate. If this is a list of Field generators, each Field generator will be evaluated and stored in a ModeBasis.

gridGrid

The grid on which to evaluate field_generator.

oversamplinginteger or scalar or ndarray

The factor by which to oversample. If this is a scalar, it will be rounded to the nearest integer. If this is an array, a different oversampling factor will be used for each dimension.

statisticstring or callable

The statistic to compute (default is ‘mean’). The following statistics are available:

  • ‘mean’ : compute the mean of values for points within each superpixel.

  • ‘median’ : compute the median of values for points within each superpixel.

  • ‘sum’ : compute the sum of values for points within each superpixel. This is identical to a weighted histogram.

  • ‘min’ : compute the minimum of values for points within each superpixel.

  • ‘max’ : compute the maximum of values for point within each superpixel.

make_sparseboolean

If the resulting ModeBasis needs to be sparsified. This is ignored if only a single Field generator is provided.

Returns
Field or ModeBasis

The evaluated field or mode basis.

hcipy.field.make_uniform_vector_field(field, jones_vector)

Make an uniform vector field from a scalar field and a jones vector.

Parameters
fieldField

An input scalar field that is expanded to a vector field

jones_vectorarray_like

The output vector at every pixel

Returns
Field

The expanded vector field

hcipy.field.make_uniform_vector_field_generator(field_generator, jones_vector)

Make an uniform vector field generator from a scalar field generator and a jones vector.

Parameters
field_generatorField generator

The field generator to evaluate.

jones_vectorarray_like

The output vector at every grid coordinate

Returns
Field generator

This function can be evaluated on a grid to get a Field.

Mode bases

class hcipy.mode_basis.ModeBasis(transformation_matrix, grid=None)

Bases: object

A list of modes.

Parameters
transformation_matrixarray_like or list of array_like

The transformation matrix of the mode basis or a list of modes.

gridGrid or None

The grid on which the modes are defined.

append(self, mode)

Append mode to this mode basis.

Parameters
modearray_like or Field

The mode to add to the ModeBasis

coefficients_for(self, b, dampening_factor=0)

Calculate the coefficients on this mode basis in a least squares fashion.

The vector b is projection onto the mode basis in a least squares fashion. This means that the const function

\[J(c) = |b - A x|^2_2 + |\lambda x|^2_2\]

is minimized, where \(x\) are the coefficients, and \(\lambda\) is the dampening factor.

If this projection needs to be done repeatedly, you may be better off calculating the inverse of the transformation matrix directly and left-multiplying that with your vector, rather than using a least squares estimation every time.

Parameters
barray_like or Field

The vector for which to calculate the coefficients.

dampening_factorscalar

The Tikhonov dampening factor used for the least squares procedure.

Returns
array_like

The coefficients that correspond to the vector b.

extend(self, modes)

Extend the mode basis with modes.

Parameters
modeslist or array_like or ModeBasis

The modes to add to the ModeBasis.

property is_dense

If the mode basis is dense.

property is_sparse

If the mode basis is sparse.

linear_combination(self, coefficients)

Calculate a linear combination using this mode basis.

Parameters
coefficientsarray_like or list

The coefficients of the linear combinations.

Returns
array_like or Field

The calculated linear combination.

property orthogonalized

Get an orthogonalized version of this ModeBasis.

The resulting ModeBasis spans the same vector space, but each mode is orthogonal to all others. In general the resulting ModeBasis is dense, so no distinction is made between sparse and dense mode bases in this function. This function will always return a dense mode basis.

Returns
ModeBasis

A mode basis with orthogonalized modes.

Raises
NotImplementedError

If the mode basis is a mode basis containing non-scalar fields.

to_dense(self, copy=False)

Convert the mode basis to a dense mode basis.

Parameters
copyboolean

Whether to force a copy or not. A copy is always made if the current ModeBasis is not dense.

Returns
ModeBasis

The densified ModeBasis.

to_sparse(self, copy=False)

Convert the mode basis to a sparse mode basis.

Parameters
copyboolean

Whether to force a copy or not. A copy is always made if the current ModeBasis is not sparse.

Returns
ModeBasis

The sparsified ModeBasis.

Raises
TypeError

If this ModeBasis cannot be sparsified.

property transformation_matrix

The transformation matrix of this mode basis.

hcipy.mode_basis.make_gaussian_hermite_basis(grid, num_modes, mode_field_diameter, starting_mode=0)

Creates a Gaussian-Hermite mode basis.

This function evaluates the starting_mode to num_modes + starting_modes Gaussian-Hermite modes. And returns a ModeBasis made out of these Gaussian-Hermite modes.

Parameters
gridGrid

The grid on which to evaluate the Gaussian-Hermite mode.

num_modesint

The number of modes to create.

mode_field_diameterscalar

The mode field diameter of the Gaussian-Hermite mode.

starting_modeint

The starting point of the mode indices.

Returns
ModeBasis

The evaluated Gaussian-Hermite modes.

hcipy.mode_basis.gaussian_hermite_index(i, mode_field_diameter=1, grid=None)

Creates a Gaussian-Hermite mode.

This function evaluates the i-th order Gaussian-Hermite mode on a grid.

Parameters
iint

The one-dimensional mode index.

mode_field_diameterscalar

The mode field diameter of the Gaussian-Hermite mode.

gridGrid

The grid on which to evaluate the Gaussian-Hermite mode.

Returns
Field

The evaluated Gaussian-Hermite mode.

hcipy.mode_basis.gaussian_hermite(n, m, mode_field_diameter=1, grid=None)

Creates a Gaussian-Hermite mode.

This function evaluates a (n, m) order Gaussian-Hermite mode on a grid. The definition of the modes are the following,

\[\exp{\left(-\frac{r^2}{w_0^2}\right)} H_n\left(\sqrt{2}\frac{x}{w_0}\right) H_m\left(\sqrt{2}\frac{y}{w_0}\right).\]

Here \(w_0\) is the mode_field_radius, which is \(\mathrm{MFD}/2\). This defintion follows the Physicists definition of the Hermite polynomials. The modes are numerical normalized to have a total power of 1.

More details on the Hermite Polynomials can be found on: http://mathworld.wolfram.com/HermitePolynomial.html

Parameters
nint

The x order.

mint

The y order.

mode_field_diameterscalar

The mode field diameter of the Gaussian-Laguerre mode.

gridGrid

The grid on which to evaluate the mode.

Returns
Field

The evaluated mode.

hcipy.mode_basis.index_to_hermite(i)

Converts a one-dimensional mode index to the two-dimensional mode index.

The one-dimensional mode index is converted to a two-dimensional index. The two-dimensional index determines the order in the x and y directions.

Parameters
iint

The one-dimensional index.

Returns
nint

The x order.

mint

The y order.

hcipy.mode_basis.gaussian_laguerre(p, l, mode_field_diameter=1, grid=None)

Creates a Gaussian-Hermite mode.

This function evaluates a (p,l) order Gaussian-Laguerre mode on a grid. The definition of the modes are the following,

\[\exp{\left(-\frac{r^2}{w_0^2}\right)} L_p^{|l|}\left(\frac{2r^2}{w_0^2} \right) \left(\sqrt{2}\frac{r}{w_0}\right)\]

Here \(w_0\) is the mode_field_radius, which is \(\mathrm{MFD}/2\). And \(L_p^{|l|}\) are the generalized Laguerre Polynomials. All modes are numerical normalized to have a total power of 1.

More details on generalized Laguerre Polynomials can be found on: http://mathworld.wolfram.com/AssociatedLaguerrePolynomial.html

Parameters
pint

The radial order.

lint

The azimuthal order.

mode_field_diameterscalar

The mode field diameter of the mode.

gridGrid

The grid on which to evaluate the mode.

Returns
Field

The evaluated mode.

hcipy.mode_basis.make_gaussian_laguerre_basis(grid, pmax, lmax, mode_field_diameter, pmin=0)

Creates a Gaussian-Laguerre mode basis.

This function evaluates Gaussian-Laguerre modes. For each radial order within [pmin, pmax] it will calculate the azimuthal order [-lmax, lmax] inclusive. This function returns a ModeBasis made out of these Gaussian-Laguerre modes.

Parameters
gridGrid

The grid on which to evaluate the Gaussian-Laguerre mode.

pmaxint

The maximum radial order of the modes.

lmaxint

The maximum azimuthal order.

mode_field_diameterscalar

The mode field diameter of the Gaussian-Laguerre mode.

pminint

The minimal radial order.

Returns
ModeBasis

The Gaussian-Laguerre modes.

hcipy.mode_basis.make_gaussian_pokes(grid, mu, sigma, cutoff=5)

Make a basis of Gaussians.

Parameters
gridGrid

The grid on which to calculate the mode basis.

muGrid

The centers for each of the Gaussians.

sigmandarray or scalar

The standard deviation of each of the Gaussians. If this is a scalar, this value will be used for all Gaussians.

cutoffscalar or None

The factor of sigma beyond which the Gaussian will be set to zero. The ModeBasis will be sparse to reduce memory usage. If the cutoff is None, there will be no cutoff, and the returned ModeBasis will be dense.

Returns
ModeBasis

The sparse mode basis. If cutoff is None, a dense mode basis will be returned.

hcipy.mode_basis.make_sine_basis(grid, fourier_grid, sort_by_energy=True)

Make a sine basis.

Repeated frequencies will not be repeated in this mode basis. This means that opposite points in the fourier_grid will be silently ignored.

Parameters
gridGrid

The Grid on which to calculate the modes.

fourier_gridGrid

The grid defining all frequencies.

sort_by_energybool

Whether to sort by increasing energy or not.

Returns
ModeBasis

The mode basis containing all sine modes.

hcipy.mode_basis.make_cosine_basis(grid, fourier_grid, sort_by_energy=True)

Make a cosine basis.

Repeated frequencies will not be repeated in this mode basis. This means that opposite points in the fourier_grid will be silently ignored.

Parameters
gridGrid

The Grid on which to calculate the modes.

fourier_gridGrid

The grid defining all frequencies.

sort_by_energybool

Whether to sort by increasing energy or not.

Returns
ModeBasis

The mode basis containing all cosine modes.

hcipy.mode_basis.make_fourier_basis(grid, fourier_grid, sort_by_energy=True)

Make a Fourier basis.

Fourier modes this function are defined to be real. This means that for each point, both a sine and cosine mode is returned.

Repeated frequencies will not be repeated in this mode basis. This means that opposite points in the fourier_grid will be silently ignored.

Parameters
gridGrid

The Grid on which to calculate the modes.

fourier_gridGrid

The grid defining all frequencies.

sort_by_energybool

Whether to sort by increasing energy or not.

Returns
ModeBasis

The mode basis containing all Fourier modes.

hcipy.mode_basis.make_complex_fourier_basis(grid, fourier_grid, sort_by_energy=True)

Make a complex Fourier basis.

Fourier modes this function are defined to be complex. For each point in fourier_grid the complex Fourier mode is contained in the output.

Parameters
gridGrid

The Grid on which to calculate the modes.

fourier_gridGrid

The grid defining all frequencies.

sort_by_energybool

Whether to sort by increasing energy or not.

Returns
ModeBasis

The mode basis containing all Fourier modes.

hcipy.mode_basis.make_zernike_basis(num_modes, D, grid, starting_mode=1, ansi=False, radial_cutoff=True, use_cache=True)

Make a ModeBasis of Zernike polynomials.

Parameters
num_modesint

The number of Zernike polynomials to generate.

Dscalar

The diameter of the Zernike polynomial.

gridGrid or None

The grid on which to evaluate the Zernike polynomials. If this is None, a list of Field generators will be returned.

starting_modeint

The first mode to evaluate.

ansiboolean

If this is True, the modes will be indexed using ANSI indices. Otherwise, a Noll indexing scheme is used.

radial_cutoffboolean

Whether to apply a circular aperture to cutoff the modes.

use_cacheboolean

Whether to use a cache while calculating the modes. A cache uses memory, so turn it off when you are limited on memory.

Returns
ModeBasis or list of Field generators

The evaluated mode basis of Zernike polynomials, or a list of Field generators for each of the Zernike polynomials.

hcipy.mode_basis.zernike(n, m, D=1, grid=None, radial_cutoff=True, cache=None)

Evaluate the Zernike polynomial on a grid.

Parameters
nint

The radial Zernike order.

mint

The azimuthal Zernike order.

Dscalar

The diameter of the Zernike polynomial.

gridGrid

The grid on which to evaluate the Zernike polynomial. If this is None, a Field generator will be returned.

radial_cutoffboolean

Whether to apply a circular aperture to cutoff the modes.

cachedictionary or None

A dictionary containing previously calculated Zernike modes on the same grid. This function is for speedup only, and therefore the cache is expected to be valid. You can reuse the cache for future calculations on the same exact grid. The given dictionary is updated with the current calculation.

Returns
Field or Field generator

The evaluated Zernike polynomial. If grid is None, a Field generator is returned, which evaluates the Zernike polynomial on the supplied grid.

hcipy.mode_basis.noll_to_zernike(i)

Get the Zernike index from a Noll index.

Parameters
iint

The Noll index.

Returns
nint

The radial Zernike order.

mint

The azimuthal Zernike order.

hcipy.mode_basis.zernike_to_noll(n, m)

Get the Noll index for a pair of Zernike indices.

Parameters
nint

The radial Zernike order.

mint

The azimuthal Zernike order.

Returns
int

The Noll index.

hcipy.mode_basis.ansi_to_zernike(i)

Get the Zernike index from an ANSI index.

Parameters
iint

The ANSI index.

Returns
nint

The radial Zernike order.

mint

The azimuthal Zernike order.

hcipy.mode_basis.zernike_to_ansi(n, m)

Get the ANSI index for a pair of Zernike indices.

Parameters
nint

The radial Zernike order.

mint

The azimuthal Zernike order.

Returns
int

The ANSI index.

hcipy.mode_basis.disk_harmonic(n, m, D=1, bc='dirichlet', grid=None)

Create a disk harmonic.

Parameters
nint

Radial order

mint

Azimuthal order

Dscalar

The diameter of the pupil.

bcstring

The boundary conditions to use. This can be either ‘dirichlet’, or ‘neumann’ for a Dirichlet or Neumann boundary condition respectively.

gridGrid

The grid on which to evaluate the function.

Returns
Field

The disk harmonic function evaluated on grid.

hcipy.mode_basis.disk_harmonic_energy(n, m, bc='dirichlet')

Get the energy of a disk harmonic function.

This allows for functions to sort a disk harmonic mode basis on energy.

Parameters
nint

Radial order

mint

Azimuthal order

bcstring

The boundary conditions to use. This can be either ‘dirichlet’, or ‘neumann’ for a Dirichlet or Neumann boundary condition respectively.

Returns
scalar

The energy corresponding to the mode.

hcipy.mode_basis.make_disk_harmonic_basis(grid, num_modes, D=1, bc='dirichlet')

Create a disk harmonic mode basis.

Parameters
gridGrid

The grid on which to evaluate the disk harmonic modes.

num_modesint

The number of modes to create.

Dscalar

The diameter of the disk.

bcstring

The boundary conditions to use. This can be either ‘dirichlet’, or ‘neumann’ for a Dirichlet or Neumann boundary condition respectively.

Returns
ModeBasis

The evaluated disk harmonic modes.

Fourier transforms

hcipy.fourier.make_fourier_transform(input_grid, output_grid=None, q=1, fov=1, planner='estimate')

Construct a FourierTransform object.

The most time-efficient Fourier transform method will be chosen according to actual or estimated performance.

Parameters
input_gridGrid

The grid that will be used for the Field passed to the Fourier transform.

output_gridNone or Grid

The grid of the resulting field. If it is None, a optimal grid will be chosen, according to q and fov.

qscalar

Describes how many samples to take in the Fourier domain. A value of 1 means critcally sampled in the Fourier domain.

fovscalar

Describes how far out the Fourier domain extends. A value of 1 means the same amount of samples as the spatial domain.

plannerstring

If it is ‘estimate’, performance of the different methods will be estimated from theoretical complexity estimates. If it is ‘measure’, actual Fourier transforms will be performed to get the actual performance. The latter takes longer, but is more accurate.

Returns
FourierTransform

The Fourier transform that was requested.

class hcipy.fourier.FourierTransform

Bases: object

The base class for all Fourier transform implementations.

Attributes
input_gridGrid

The grid that is expected for the input field.

output_gridGrid

The grid that is produced by the Fourier transform.

backward(self, field)

Returns the inverse Fourier transform of the Field field.

Parameters
fieldField

The field to inverse Fourier transform.

Returns
Field

The inverse Fourier transform of the field.

forward(self, field)

Returns the forward Fourier transform of the Field field.

Parameters
fieldField

The field to Fourier transform.

Returns
Field

The Fourier transform of the field.

get_transformation_matrix_backward(self)

Returns the transformation matrix corresonding to the Fourier transform.

Returns
ndarray

A matrix representing the Fourier transform.

get_transformation_matrix_forward(self)

Returns the transformation matrix corresonding to the Fourier transform.

Returns
ndarray

A matrix representing the Fourier transform.

hcipy.fourier.make_fft_grid(input_grid, q=1, fov=1)
class hcipy.fourier.FastFourierTransform(input_grid, q=1, fov=1, shift=0)

Bases: hcipy.fourier.fourier_transform.FourierTransform

backward(self, field)
forward(self, field)
class hcipy.fourier.ConvolveFFT(input_grid, kernel)

Bases: object

forward(self, field)
class hcipy.fourier.ShearFFT

Bases: object

class hcipy.fourier.RotateFFT

Bases: object

class hcipy.fourier.FilterFFT

Bases: object

class hcipy.fourier.MatrixFourierTransform(input_grid, output_grid)

Bases: hcipy.fourier.fourier_transform.FourierTransform

backward(self, field)
forward(self, field)
class hcipy.fourier.NaiveFourierTransform(input_grid, output_grid, cache_matrices=True)

Bases: hcipy.fourier.fourier_transform.FourierTransform

property T_backward
property T_forward
backward(self, field)
forward(self, field)

Optical systems

hcipy.optics.make_power_law_error(pupil_grid, ptv, diameter, exponent=-2.5, aperture=None, remove_modes=None)

Create an error surface from a power-law power spectral density.

Parameters
pupil_gridGrid

The grid on which to calculate the error.

ptvscalar

The peak-to-valley of the wavefront aberration in meters.

diameterscalar

The diameter over which the ptv is calculated.

exponentscalar

The exponent of the power law.

apertureField

The mask over which to calculate the ptv. A circular aperture with diameter diameter is used if this is not given.

remove_modesModeBasis

The modes which to remove from the surface aberration. The peak-to-valley is enforced before these modes are removed. This allows for correctting surface errors with optic alignment.

Returns
Field

The surface error calculated on pupil_grid.

class hcipy.optics.SurfaceAberration(pupil_grid, ptv, diameter, exponent=-2.5, refractive_index=-1, aperture=None, remove_modes=None)

Bases: hcipy.optics.optical_element.AgnosticOpticalElement

A surface aberration with a specific power law.

Parameters
pupil_gridGrid

The grid on which the incoming wavefront is defined.

ptvscalar

The peak-to-valley of the wavefront aberration in meters.

diameterscalar

The diameter over which the ptv is calculated.

exponentscalar

The exponent of the power law.

refractive_indexscalar

The refractive index of the surface for which this is the surface error. The default is a mirror surface.

apertureField

The mask over which to calculate the ptv. A circular aperture with diameter diameter is used if this is not given.

remove_modesModeBasis

The modes which to remove from the surface aberration. The peak-to-valley is enforced before these modes are removed. This allows for correctting surface errors with optic alignment.

class hcipy.optics.SurfaceAberrationAtDistance(surface_aberration, distance)

Bases: hcipy.optics.optical_element.OpticalElement

A surface at a certain distance from the current plane.

Light is propagated to this surface, then the surface errors are applied, and afterwards the light is propagated back towards the original plane. This allows for easy addition of surface errors on lenses, while still retaining the Fraunhofer propagations in between focal and pupil planes.

Parameters
surface_aberrationOpticalElement

The optical element describing the surface aberration.

distancescalar

The distance from the current plane.

backward(self, wavefront)

Propagate a wavefront backwards through the surface aberration.

Parameters
wavefrontWavefront

The incoming wavefront.

Returns
Wavefront

The wavefront before the surface aberration. This wavefront is given at the same plane as wavefront.

forward(self, wavefront)

Propagate a wavefront forwards through the surface aberration.

Parameters
wavefrontWavefront

The incoming wavefront.

Returns
Wavefront

The wavefront after the surface aberration. This wavefront is given at the same plane as wavefront.

hcipy.optics.Apodizer

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

hcipy.optics.PhaseApodizer

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

class hcipy.optics.ThinLens(focal_length)

Bases: hcipy.optics.optical_element.OpticalElement

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

hcipy.optics.SurfaceApodizer

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

class hcipy.optics.ComplexSurfaceApodizer(amplitude, surface, refractive_index)

Bases: hcipy.optics.optical_element.OpticalElement

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

class hcipy.optics.MultiplexedComplexSurfaceApodizer(amplitude, surface, refractive_index)

Bases: hcipy.optics.optical_element.OpticalElement

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

class hcipy.optics.DynamicOpticalSystem

Bases: object

A dynamically varying optical system.

This can be used as a starting point for an implementation of an adaptive optics system. The optics are changed as specific moments in time, which can be scheduled by submitting a callback. The time points are bridged using the integrate function, which is written by the derived class. This function should integrate on each detector without reading out the detector. Detector readouts or DM changes should be implemented as callbacks.

add_callback(self, t, callback)

Add a callback to the list of callbacks.

This function can even be called during handling of a callback. This is especially useful when implementing periodic callbacks: a callback can reinsert itself at a later time at the end of handling of the callback.

Parameters
tscalar

The time at which to call the callback.

callbackfunction

The function to call at time t. This function should have no arguments.

evolve_until(self, t)

Evolve the optical system until time t.

Parameters
tscalar

The point in time to which to simulate this optical system. Callbacks and integrations are handled along the way.

integrate(self, integration_time)

Integrate the current optical system for a certain integration time.

This function should be implemented by a user in a derived class.

Parameters
integration_timescalar

The integration time with which to integrate the optical system.

hcipy.optics.make_gaussian_influence_functions(pupil_grid, num_actuators_across_pupil, actuator_spacing, crosstalk=0.15, cutoff=3, x_tilt=0, y_tilt=0, z_tilt=0)

Create influence functions with a Gaussian profile.

The default value for the crosstalk is representative for Boston Micromachines DMs.

Parameters
pupil_gridGrid

The grid on which to calculate the influence functions.

num_actuators_across_pupilinteger

The number of actuators across the pupil. The total number of actuators will be this number squared.

actuator_spacingscalar

The spacing between actuators before tilting the deformable mirror.

crosstalkscalar

The amount of crosstalk between the actuators. This is defined as the value of the influence function at a nearest-neighbour actuator.

cutoffscalar

The distance from the center of the actuator, as a fraction of the actuator spacing, where the influence function is truncated to zero.

x_tiltscalar

The tilt of the deformable mirror around the x-axis in radians.

y_tiltscalar

The tilt of the deformable mirror around the y-axis in radians.

z_tiltscalar

The tilt of the deformable mirror around the z-axis in radians.

Returns
ModeBasis

The influence functions for each of the actuators.

hcipy.optics.make_xinetics_influence_functions(pupil_grid, num_actuators_across_pupil, actuator_spacing, x_tilt=0, y_tilt=0, z_tilt=0)

Create influence functions for a Xinetics deformable mirror.

This function uses a The rotation of the deformable mirror will be done in the order X-Y-Z.

Parameters
pupil_gridGrid

The grid on which to calculate the influence functions.

num_actuators_across_pupilinteger

The number of actuators across the pupil. The total number of actuators will be this number squared.

actuator_spacingscalar

The spacing between actuators before tilting the deformable mirror.

x_tiltscalar

The tilt of the deformable mirror around the x-axis in radians.

y_tiltscalar

The tilt of the deformable mirror around the y-axis in radians.

z_tiltscalar

The tilt of the deformable mirror around the z-axis in radians.

Returns
ModeBasis

The influence functions for each of the actuators.

class hcipy.optics.DeformableMirror(influence_functions)

Bases: hcipy.optics.optical_element.OpticalElement

A deformable mirror using influence functions.

This class does not contain any temporal simulation (ie. settling time), and assumes that there is no crosstalk between actuators.

Parameters
influence_functionsModeBasis

The influence function for each of the actuators.

property actuators
backward(self, wavefront)

Propagate a wavefront backwards through the deformable mirror.

Parameters
wavefrontWavefront

The incoming wavefront.

Returns
Wavefront

The reflected wavefront.

flatten(self)

Flatten the DM by setting all actuators to zero.

forward(self, wavefront)

Propagate a wavefront through the deformable mirror.

Parameters
wavefrontWavefront

The incoming wavefront.

Returns
Wavefront

The reflected wavefront.

property influence_functions

The influence function for each of the actuators of this deformable mirror.

property opd

The optical path difference in meters that this deformable mirror induces.

phase_for(self, wavelength)

Get the phase that is added to a wavefront with a specified wavelength.

Parameters
wavelengthscalar

The wavelength at which to calculate the phase deformation.

Returns
Field

The calculated phase deformation.

random(self, rms)

Set the dm actuators with random white noise of a certain rms.

Parameters
rmsscalar

The dm surface rms.

property surface

The surface of the deformable mirror in meters.

hcipy.optics.label_actuator_centroid_positions(influence_functions, label_format='{:d}', **text_kwargs)

Display centroid positions for a set of influence functions.

The location of each of the actuators is calculated using a weighted centroid, and at that location a label is written to the open Matplotlib Figure. The text can be modified with label_format, which is formatted with new-style Python formatting: label_format.format(i) where i is the actuator index.

Parameters
influence_functionsModeBasis

The influence function for each actuator.

label_formatstring

The text that will be displayed at the actuator centroid. This must be a new-style formattable string.

Raises
ValueError

If the influence functions mode basis does not contain a grid.

class hcipy.optics.Detector

Bases: object

integrate(self, wavefront, dt, weight=1)

Integrates the detector.

Parameters
wavefrontWavefront or array_like

The wavefront sets the amount of power generated per unit time.

dtscalar

The integration time in units of time.

weightscalar

Weight of every unit of integration time.

read_out(self)

Reads out the detector.

No noise will be added to the image.

Returns
output_fieldarray_like

The final detector image.

class hcipy.optics.NoiselessDetector

Bases: hcipy.optics.detector.Detector

A detector without noise.

This detector includes no noise effects at all. This can be used as a theoretically perfect detector.

integrate(self, wavefront, dt, weight=1)

Integrates the detector.

Parameters
wavefrontWavefront or array_like

The wavefront sets the amount of power generated per unit time.

dtscalar

The integration time in units of time.

weightscalar

Weight of every unit of integration time.

read_out(self)

Reads out the detector.

No noise will be added to the image.

Returns
output_fieldarray_like

The final detector image.

class hcipy.optics.NoisyDetector(input_grid, dark_current_rate=0, read_noise=0, flat_field=0, include_photon_noise=True)

Bases: hcipy.optics.detector.Detector

A detector class that has some basic noise properties.

A detector that includes the following noise sources: photon shot noise, dark current shot noise, flat field errors and read noise. These noise sources (except for photon shot noise) can be either a scalar (same for entire grid) or an array. For the flat field error specifically: if a scalar is given, a normal distributed flat field map (given scalar is standard deviation about 1) is generated that will be used - if an array is given, that array will be used, so it will NOT be a normal distributed flat field where every point in array gives the standard deviation. This allows the user to load a specific flat field map.

Parameters
input_gridGrid

The grid on which the detector samples.

dark_current_ratescalar or array_like

An array or scalar that gives dark current rate in counts per unit time for each point in the grid.

read_noisescalar or array_like

An array or scalar that gives the rms read noise counts for each point in the grid.

flat_fieldscalar or array_like

An array or scalar that gives the flat field error for each point in the grid. If a scalar is given, a random normal distributed flat field map (given scalar is standard deviation about 1) is generated that will be used.

include_photon_noiseboolean

Turns the photon noise on or off.

property flat_field
integrate(self, wavefront, dt, weight=1)

Integrates the detector.

The amount of power and dark current that the detector generates are calculated for a given integration time and weight.

Parameters
wavefrontWavefront or array_like

The wavefront sets the amount of power generated per unit time.

dtscalar

The integration time in units of time.

weightscalar

Weight of every unit of integration time.

read_out(self)

Reads out the detector.

The read out operation of the detector. This means that, if applicable, first photon noise will be included to the power. Then, in this order, the flat field error and read-out noise are applied. After the read out the power is reset.

Returns
output_fieldarray_like

The final detector image.

class hcipy.optics.SingleModeFiber(input_grid, mode_field_diameter, mode=None)

Bases: hcipy.optics.detector.Detector

integrate(self, wavefront, dt, weight=1)

Integrates the detector.

Parameters
wavefrontWavefront or array_like

The wavefront sets the amount of power generated per unit time.

dtscalar

The integration time in units of time.

weightscalar

Weight of every unit of integration time.

read_out(self)

Reads out the detector.

No noise will be added to the image.

Returns
output_fieldarray_like

The final detector image.

hcipy.optics.fiber_mode_gaussian(grid, mode_field_diameter)
class hcipy.optics.SingleModeFiberArray(input_grid, fiber_grid, mode, *args, **kwargs)

Bases: hcipy.optics.optical_element.OpticalElement

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

get_transformation_matrix_backward(self, wavelength=1)

Calculate the linear transformation matrix that corresponds to a backward propagation.

The matrix is defined such that E_in = M.dot(E_out), where E_out and E_in are the electric fields of the output and input plane respectively, and M is the transformation matrix returned by this function.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

:: warning::

Depending on the chosen resolution, this matrix can be extremely large and use extremely large amounts of memory. For example, a Fresnel propagation on a 128x128 grid will already create a matrix of 2.1GB. Use with caution.

This function will be implemented by the derived class.

Parameters
wavelengthscalar

The wavelength for which the transformation matrix will be calculated.

Returns
ndarray

The full propagation matrix.

get_transformation_matrix_forward(self, wavelength=1)

Calculate the linear transformation matrix that corresponds to a forward propagation.

The matrix is defined such that E_out = M.dot(E_in), where E_out and E_in are the electric fields of the output and input respectively, and M is the transformation matrix returned by this function.

:: warning::

Depending on the chosen resolution, this matrix can be extremely large and use extremely large amounts of memory. For example, a Fresnel propagation on a 128x128 grid will already create a matrix of 2.1GB. Use with caution.

This function will be implemented by the derived class.

Parameters
wavelengthscalar

The wavelength for which the transformation matrix will be calculated.

Returns
ndarray

The full propagation matrix.

class hcipy.optics.GaussianBeam(w0, z, wavelength)

Bases: object

An analytical description of a light beam with a Gaussian profile.

Parameters
w0scalar

The beam waist.

zscalar

The current distance from the beam waist.

wavelengthscalar

The wavelength of the light.

property FWHM

The current FWHM of the Gaussian beam.

property R

The current radius of curvature of the Gaussian beam.

property beam_divergence

The beam divergence of the Gaussian beam.

property beam_radius

The current beam radius of the Gaussian beam.

property beam_waist

The beam waist of the Gaussian beam.

property complex_beam_parameter

The complex beam parameter of the Gaussian beam.

evaluate(self, grid)

Evaluate the wavefront of the Gaussian beam at the current position on the given grid.

Parameters
gridGrid

The grid on which to calculate the wavefront for the Gaussian beam.

Returns
Wavefront

The evaluated wavefront of the Gaussian beam.

property full_width_half_maximum

The current FWHM of the Gaussian beam.

property gouy_phase

The current Gouy phase of the Gaussian beam.

property k

The wavenumber of the Gaussian beam.

property psi

The current Gouy phase of the Gaussian beam.

property q

The complex beam parameter of the Gaussian beam.

property radius_of_curvature

The current radius of curvature of the Gaussian beam.

property rayleigh_distance

The Rayleight distance of the Gaussian beam.

property theta

The beam divergence of the Gaussian beam.

property w

The current beam radius of the Gaussian beam.

property wavenumber

The wavenumber of the Gaussian beam.

property zR

The Rayleight distance of the Gaussian beam.

hcipy.optics.Magnifier

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

class hcipy.optics.MicroLensArray(input_grid, lenslet_grid, focal_length, lenslet_shape=None)

Bases: hcipy.optics.optical_element.OpticalElement

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

hcipy.optics.closest_points(point_grid, evaluated_grid)
class hcipy.optics.OpticalElement

Bases: object

Base class for all optical elements.

This class can propagate a Wavefront through an optical element (or free space), therefore modifying it. Any OpticalElement should be agnostic of the grid and wavelength of the wavefront. If it’s not, you can use the make_agnostic_optical_element() decorator to create an agnostic optical element out of a gnostic one.

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

get_instance(self, input_grid=None, output_grid=None, wavelength=None)

Return an OpticalElement that can handle wavefronts with input_grid and wavelength.

While any OpticalElement should in theory be able to handle all grids and wavelengths, this function is added to simplify the interface for those who don’t. It allows the user to always access properties of an OpticalElement, evaluated for a specific input_grid and wavelength.

The user needs to supply at least an input grid or an output grid, and a wavelength. If this is not done, a ValueError will be raised.

Parameters
input_gridGrid

The grid on which the input wavefront is defined.

output_gridGrid or None

The grid on which the output wavefront is defined.

wavelengthscalar

The wavelength on which the wavefront is defined.

Returns
OpticalElement

An optical element that can handle wavefront with the specified input grid and wavelength.

get_transformation_matrix_backward(self, wavelength=1)

Calculate the linear transformation matrix that corresponds to a backward propagation.

The matrix is defined such that E_in = M.dot(E_out), where E_out and E_in are the electric fields of the output and input plane respectively, and M is the transformation matrix returned by this function.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

:: warning::

Depending on the chosen resolution, this matrix can be extremely large and use extremely large amounts of memory. For example, a Fresnel propagation on a 128x128 grid will already create a matrix of 2.1GB. Use with caution.

This function will be implemented by the derived class.

Parameters
wavelengthscalar

The wavelength for which the transformation matrix will be calculated.

Returns
ndarray

The full propagation matrix.

get_transformation_matrix_forward(self, wavelength=1)

Calculate the linear transformation matrix that corresponds to a forward propagation.

The matrix is defined such that E_out = M.dot(E_in), where E_out and E_in are the electric fields of the output and input respectively, and M is the transformation matrix returned by this function.

:: warning::

Depending on the chosen resolution, this matrix can be extremely large and use extremely large amounts of memory. For example, a Fresnel propagation on a 128x128 grid will already create a matrix of 2.1GB. Use with caution.

This function will be implemented by the derived class.

Parameters
wavelengthscalar

The wavelength for which the transformation matrix will be calculated.

Returns
ndarray

The full propagation matrix.

hcipy.optics.make_agnostic_optical_element(grid_dependent_arguments=None, wavelength_dependent_arguments=None, num_in_cache=50)

Create an optical element that is agnostic to input_grid or wavelength from one that is not.

This decorator is meant to simplify the creation of agnostic optical elements. When you have an optical element that explicitly needs an input grid and/or wavelength on initialization, you can use this decorator to modify it to make it accept all input grids and/or wavelengths.

All parameters pass to the __init__() of the returned class will be attempted to be evaluated on an input grid or wavelength (depending on if the parameter name appears in grid_dependent_arguments or wavelength_dependent_arguments). This evaluation is done by calling the argument with either the input_grid or wavelength, before passing it to the initializer of the optical element provided by the user. When an argument can be both dependent on input grid and wavelength, you can pass a function with double arguments. This will be evaluated as arg(input_grid, wavelength). If the argument only has a single parameter, this function will make a guess on whether it is input_grid or wavelength dependent and try both possibilities.

Parameters
grid_dependent_argumentslist of strings or None

A list of all names of parameters that could vary with input_grid. These parameters will be evaluated on the grid if they are callable. If this is None, this indicates that no parameters can depend on input_grid, and that the optical element was already input_grid agnostic.

wavelength_dependent_argumentslist of strings or None

A list of all names of parameters that could vary with wavelength. These parameters will be evaluated at the wavelength if they are callable. If this is None, this indicates that no parameters can depend on wavelength, and that the optical element was already wavelength agnostic.

num_in_cacheint

The maximum size of the internal cache for optical elements. Reduce this if the cache is using too much memory, increase if there are a lot of cache misses.

Returns
class

The new optical element class that is now agnostic to input grid and wavelength.

Raises
RuntimeError

If one of the argument gave an error during evaluation.

class hcipy.optics.OpticalSystem(optical_elements)

Bases: hcipy.optics.optical_element.OpticalElement

An linear path of optical elements.

Parameters
optical_elementslist of OpticalElement

The optical elements in the order that the wavefront propagates.

backward(self, wavefront)

Propagate a wavefront backward through the optical system.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical system.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

get_transformation_matrix_backward(self, wavelength=1)

Calculate the forward linear transformation matrix.

Parameters
wavelengthscalar

The wavelength for which the transformation matrix will be calculated.

Returns
ndarray

The full propagation matrix.

get_transformation_matrix_forward(self, wavelength=1)

Calculate the forward linear transformation matrix.

Parameters
wavelengthscalar

The wavelength for which the transformation matrix will be calculated.

Returns
ndarray

The full propagation matrix.

property optical_elements

The list of optical elements contained in this optical system.

hcipy.optics.make_polychromatic(evaluated_arguments=None, num_in_cache=50)

Make a polychromatic optical element from a monochromatic one.

This decorator is deprecated and will be removed in a future version. New code should use its successor make_agnostic_optical_element(), which can also handle input_grid dependencies.

Parameters
evaluated_argumentslist of strings or None

A list of parameters that can be a function of wavelength. If this is None, the original optical element can already handle all wavelengths.

num_in_cacheint

The maximum size of the internal cache.

Returns
class

An optical element class that can handle all wavelengths.

hcipy.optics.PhaseRetarder

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

class hcipy.optics.LinearRetarder(phase_retardation, fast_axis_orientation, wavelength=1)

Bases: hcipy.optics.optical_element.AgnosticOpticalElement

A general linear retarder.

Parameters
phase_retardationscalar or Field

The relative phase retardation induced between the fast and slow axis.

fast_axis_orientationscalar or Field

The angle of the fast axis with respect to the x-axis in radians.

class hcipy.optics.CircularRetarder(phase_retardation, wavelength=1)

Bases: hcipy.optics.optical_element.AgnosticOpticalElement

A general circular retarder.

Parameters
phase_retardationscalar or Field

The relative phase retardation induced between the fast and slow axis.

fast_axis_orientationscalar or Field

The angle of the fast axis with respect to the x-axis in radians.

class hcipy.optics.QuarterWavePlate(fast_axis_orientation, wavelength=1)

Bases: hcipy.optics.polarization.LinearRetarder

A quarter-wave plate.

Parameters
fast_axis_orientationscalar or Field

The angle of the fast axis with respect to the x-axis in radians.

class hcipy.optics.HalfWavePlate(fast_axis_orientation, wavelength=1)

Bases: hcipy.optics.polarization.LinearRetarder

A half-wave plate.

Parameters
fast_axis_orientationscalar or Field

The angle of the fast axis with respect to the x-axis in radians.

class hcipy.optics.LinearPolarizer(polarization_angle)

Bases: hcipy.optics.optical_element.OpticalElement

A linear polarizer.

Parameters
polarization_anglescalar or Field

The polarization angle of the polarizer. Light with this angle is transmitted.

backward(self, wavefront)

Propagate a wavefront backwards through the linear polarizer.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forwards through the linear polarizer.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

property polarization_angle

The angle of polarization of the linear polarizer.

class hcipy.optics.SegmentedDeformableMirror(segments)

Bases: hcipy.optics.deformable_mirror.DeformableMirror

A segmented deformable mirror.

This deformable mirror class can simulate devices such as those made by IrisAO and BMC. All segments are controlled in piston, tip and tilt.

Parameters
segmentsModeBasis

A mode basis with all segments.

get_segment_actuators(self, segment_id)

Get the actuators for an individual segment of the DM.

Parameters
segment_idint

The index of the segment for which to get the actuators.

Returns
pistonscalar

The piston of the segment in meters.

tipscalar

The tip of the segment in radians.

tiltscalar

The tilt of the segment in radians.

property segments

The segments of this deformable mirror in a ModeBasis.

set_segment_actuators(self, segment_id, piston, tip, tilt)

Set the actuators for an individual segment of the DM.

Parameters
segment_idint

The index of the segment for which to get the actuators.

pistonscalar

The piston of the segment in meters.

tipscalar

The tip of the segment in radians.

tiltscalar

The tilt of the segment in radians.

class hcipy.optics.TipTiltMirror(input_grid)

Bases: hcipy.optics.deformable_mirror.DeformableMirror

A tip-tilt mirror.

This deformable mirror class provides a tip-tilt mirror, where the actuators are controlled in OPD.

Parameters
input_gridGrid

The grid that corresponds to the input wavefront

class hcipy.optics.SimpleVibration(mode, amplitude, frequency, phase_0=0)

Bases: hcipy.optics.optical_element.OpticalElement

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

property frequency
property phase
class hcipy.optics.Wavefront(electric_field, wavelength=1)

Bases: object

property amplitude
copy(self)
property electric_field
property grid
property imag
property intensity
property phase
property power
property real
property total_power
property wavenumber
class hcipy.propagation.Propagator

Bases: hcipy.optics.optical_element.OpticalElement

hcipy.propagation.FresnelPropagator

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

hcipy.propagation.FraunhoferPropagator

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

hcipy.propagation.AngularSpectrumPropagator

alias of hcipy.optics.optical_element.make_agnostic_optical_element.<locals>.decorator.<locals>.AgnosticOpticalElement

hcipy.aperture.circular_aperture(diameter, center=None)

Makes a Field generator for a circular aperture.

Parameters
diameterscalar

The diameter of the aperture.

centerarray_like

The center of the aperture

Returns
Field generator

This function can be evaluated on a grid to get a Field.

hcipy.aperture.rectangular_aperture(size, center=None)

Makes a Field generator for a rectangular aperture.

Parameters
sizescalar or array_like

The length of the sides. If this is scalar, a square aperture is assumed.

centerarray_like

The center of the aperture

Returns
Field generator

This function can be evaluated on a grid to get a Field.

hcipy.aperture.regular_polygon_aperture(num_sides, circum_diameter, angle=0)

Makes a Field generator for a regular-polygon-shaped aperture.

Parameters
num_sidesinteger

The number of sides for the polygon.

circum_diameterscalar

The circumdiameter of the polygon.

anglescalar

The angle by which to turn the polygon.

Returns
Field generator

This function can be evaluated on a grid to get a Field.

hcipy.aperture.hexagonal_aperture(circum_diameter, angle=0)

Makes a Field generator for a hexagon aperture.

Parameters
circum_diameterscalar

The circumdiameter of the polygon.

anglescalar

The angle by which to turn the hexagon.

Returns
Field generator

This function can be evaluated on a grid to get a Field.

hcipy.aperture.make_spider(p1, p2, spider_width)

Make a rectangular obstruction from p1 to p2.

Parameters
p1list or ndarray

The starting coordinates of the spider.

p2list or ndarray

The end coordinates of the spider.

spider_widthscalar

The full width of the spider.

Returns
Field generator

The spider obstruction.

hcipy.aperture.make_spider_infinite(p, angle, spider_width)

Make an infinite spider starting at p and extending at an angle angle.

Parameters
plist or ndarray

The starting coordinate of the spider.

anglescalar

The angle to which the spider is pointing in degrees.

spider_widthscalar

The full width of the spider.

Returns
Field generator

The spider obstruction.

hcipy.aperture.make_obstructed_circular_aperture(pupil_diameter, central_obscuration_ratio, num_spiders=0, spider_width=0.01)

Make a simple circular aperture with central obscuration and support structure.

Parameters
pupil_diameterscalar

The diameter of the circular aperture.

central_obscuration_ratioscalar

The ratio of the diameter of the central obscuration compared to the pupil diameter.

num_spidersint

The number of spiders holding up the central obscuration.

spider_widthscalar

The full width of the spiders.

Returns
Field generator

The circularly obstructed aperture.

hcipy.aperture.make_segmented_aperture(segment_shape, segment_positions, segment_transmissions=1, return_segments=False)

Create a segmented aperture.

Parameters
segment_shapeField generator

The shape for each of the segments.

segment_positionsGrid

The center position for each of the segments.

segment_transmissionsscalar or ndarray

The transmission for each of the segments. If this is a scalar, the same transmission is used for all segments.

return_segmentsboolean

Whether to return a ModeBasis of all segments as well.

Returns
Field generator

The segmented aperture.

list of Field generators

The segments. Only returned if return_segments is True.

hcipy.aperture.make_magellan_aperture(normalized=False, with_spiders=True)

Make the Magellan aperture.

Parameters
normalizedboolean

If this is True, the outer diameter will be scaled to 1. Otherwise, the diameter of the pupil will be 6.5 meters.

with_spiders: boolean

If this is False, the spiders will be left out.

Returns
Field generator

The Magellan aperture.

hcipy.aperture.make_luvoir_a_aperture(normalized=False, with_spiders=True, with_segment_gaps=True, gap_padding=1, segment_transmissions=1, return_header=False, return_segments=False)

This aperture changes frequently. This one is based on LUVOIR Apertures dimensions from Matt Bolcar, LUVOIR lead engineer (as of 10 April 2019) Spiders and segment gaps can be included or excluded, and the transmission for each of the segments can also be changed. Segements can be returned as well.

Parameters
normalizedboolean

If this is True, the pupil diameter will be scaled to 1. Otherwise, the diameter of the pupil will be 15.0 meters.

with_spidersboolean

Include the secondary mirror support structure in the aperture.

with_segment_gapsboolean

Include the gaps between individual segments in the aperture.

gap_paddingscalar

Arbitrary padding of gap size to represent gaps on smaller arrays - this effectively makes the gaps larger and the segments smaller to preserve the same segment pitch.

segment_transmissionsscalar or array_like

The transmission for each of the segments. If this is a scalar, this transmission will be used for all segments.

return_headerboolean

If this is True, a header will be returned giving all important values for the created aperture for reference.

return_segmentsboolean

If this is True, the segments will also be returned as a ModeBasis.

Returns
apertureField generator

The LUVOIR A aperture.

aperture_headerdict

A dictionary containing all quantities used when making this aperture. Only returned if return_header is True.

segmentslist of Field generators

The segments. Only returned when return_segments is True.

hcipy.aperture.make_luvoir_a_lyot_stop(normalized=False, with_spiders=False, spider_oversize=1, inner_diameter_fraction=0.2, outer_diameter_fraction=0.9, return_header=False)

Make a LUVOIR-A Lyot stop for the APLC coronagraph.

Parameters
normalizedboolean

If this is True, the pupil diameter will be scaled to 1. Otherwise, the diameter of the pupil will be 15.0 meters.

with_spidersboolean

Include the secondary mirror support structure in the aperture.

inner_diameter_fractionscalar

The fractional size of the circular central obstruction as fraction of the pupil diameter.

outer_diameter_fractionscalar

The fractional size of the circular outer edge as fraction of the pupil diameter.

spider_oversizescalar

The factor by which to oversize the spiders compared to the LUVOIR-A aperture spiders.

return_headerboolean

If this is True, a header will be returned giving all important values for the created aperture for reference.

Returns
lyot_stopField generator

A field generator for the Lyot stop.

headerdict

A dictionary containing all important values for the created aperture. Only returned if return_header is True.

hcipy.aperture.make_hicat_aperture(normalized=False, with_spiders=True, with_segment_gaps=True, return_header=False, return_segments=False)

Make the HiCAT P3 apodizer mask

Parameters
normalizedboolean

If this is True, the outer diameter will be scaled to 1. Otherwise, the diameter of the pupil will be 15.0 meters.

with_spidersboolean

Include the secondary mirror support structure in the aperture.

with_segment_gapsboolean

Include the gaps between individual segments in the aperture.

return_headerboolean

If this is True, a header will be returned giving all important values for the created aperture for reference.

return_segmentsboolean

If this is True, the segments will also be returned as a list of Field generators.

Returns
apertureField generator

The HiCAT aperture.

headerdict

A dictionary containing all important values for the created aperture. Only returned if return_header is True.

segmentslist of Field generators

The segments. Only returned when return_segments is True.

hcipy.aperture.make_hicat_lyot_stop(normalized=False, with_spiders=True, inner_diameter_fraction=0.2, outer_diameter_fraction=0.9, return_header=False)

Make the HiCAT Lyot stop.

Parameters
normalizedboolean

If this is True, the outer diameter will be scaled to 1. Otherwise, the diameter of the pupil will be 15.0 meters.

with_spidersboolean

Include the secondary mirror support structure in the aperture.

inner_diameter_fractionscalar

The fractional size of the circular central obstruction as fraction of the pupil diameter.

outer_diameter_fractionscalar

The fractional size of the circular outer edge as fraction of the pupil diameter.

return_headerboolean

If this is True, a header will be returned giving all important values for the created aperture for reference.

Returns
lyot_stopField generator

A field generator for the Lyot stop.

headerdict

A dictionary containing all important values for the created aperture. Only returned if return_header is True.

Adaptive optics

Atmospheric model

class hcipy.atmosphere.MultiLayerAtmosphere(layers, scintilation=False)

Bases: hcipy.optics.optical_element.OpticalElement

property Cn_squared

The total Cn^2 value of the simulated atmosphere.

backward(self, wavefront)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

calculate_propagators(self)

Recalculates the list of optical elements used for a propagation.

This function is called automatically by other functions, but a recalculation can be forced by calling it explicitly.

evolve_until(self, t)

Evolve all atmospheric layers to a time t.

Parameters
tscalar

The time to which to evolve the atmospheric layers.

forward(self, wavefront)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

property layers

A list of AtmosphericLayer objects.

property outer_scale

The outer scale of all layers.

phase_for(self, wavelength)

Get the unwrapped phase for the atmosphere.

Parameters
wavelengthscalar

The wavelength at which to calculate the phase screen.

Returns
Field

The total unwrapped phase screen.

reset(self)
property scintilation

Whether to include scintilation effects in the propagation.

property t

The current time.

class hcipy.atmosphere.AtmosphericLayer(input_grid, Cn_squared=None, L0=inf, velocity=0, height=0)

Bases: hcipy.optics.optical_element.OpticalElement

property Cn_squared

The integrated value of Cn^2 for the layer.

property L0

The outer scale of the phase structure function.

backward(self, wf)

Propagate a wavefront backward through the optical element.

A backward propagation is a literal backward propagation through the element. It is not (in general) the inverse of the forward propagation, except in cases where energy is conserved.

This function will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

evolve_until(self, t)

Evolve the atmospheric layer until time t.

Parameters
tscalar

The time to which to evolve the atmospheric layer.

forward(self, wf)

Propagate a wavefront forward through the optical element.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

property outer_scale

The outer scale of the phase structure function.

property output_grid
phase_for(self, wavelength)

Get the phase screen at a certain wavelength.

Each atmospheric layer is modelled as an infinitely-thin phase screen.

Parameters
wavelengthscalar

The wavelength at which to calculate the phase screen.

reset(self)

Reset the phase screen.

This will create a randomized uncorrelated phase screen.

property t

The current time of the atmospheric layer.

property velocity

The two-dimensional velocity of the layer.

hcipy.atmosphere.phase_covariance_von_karman(r0, L0)

Return a Field generator for the phase covariance function for Von Karman turbulence.

Parameters
r0scalar

The Fried parameter.

L0scalar

The outer scale.

Returns
Field generator

The phase covariance Field generator.

hcipy.atmosphere.phase_structure_function_von_karman(r0, L0)

Return a Field generator for the phase structure function for Von Karman turbulence.

Parameters
r0scalar

The Fried parameter.

L0scalar

The outer scale.

Returns
Field generator

The phase structure Field generator.

hcipy.atmosphere.power_spectral_density_von_karman(r0, L0)

Return a Field generator for the power spectral density function for Von Karman turbulence.

Parameters
r0scalar

The Fried parameter.

L0scalar

The outer scale.

Returns
Field generator

The power spectral density Field generator.

hcipy.atmosphere.Cn_squared_from_fried_parameter(r0, wavelength)

Calculate the integrated Cn^2 for a certain Fried parameter.

Parameters
r0scalar

The Fried parameter.

wavelengthscalar

The wavelength at which the Fried parameter is measured.

Returns
scalar

The integrated Cn^2 value for the atmosphere.

hcipy.atmosphere.fried_parameter_from_Cn_squared(Cn_squared, wavelength)

Calculate the Fried parameter from the integrated Cn^2.

Parameters
r0scalar

The integrated Cn^2 value for the atmosphere.

wavelengthscalar

The wavelength at which to calculate the Fried parameter.

Returns
scalar

The Fried parameter.

hcipy.atmosphere.seeing_to_fried_parameter(seeing, wavelength)

Calculate the Fried parameter from the seeing FWHM.

Parameters
seeingscalar

The FWHM of the seeing.

wavelengthscalar

The wavelength at which the seeing is measured.

Returns
scalar

The Fried parameter at wavelength wavelength.

hcipy.atmosphere.fried_parameter_to_seeing(r0, wavelength)

Calculate the FWHM of the seeing from the Fried parameter.

Parameters
scalar

The Fried parameter.

wavelengthscalar

The wavelength at which the Fried parameter is measured.

Returns
scalar

The FWHM of the seeing.

class hcipy.atmosphere.FiniteAtmosphericLayer(input_grid, Cn_squared=None, L0=inf, velocity=0, height=0, oversampling=2)

Bases: hcipy.atmosphere.atmospheric_model.AtmosphericLayer

property Cn_squared

The integrated value of Cn^2 for the layer.

property L0
evolve_until(self, t)

Evolve the atmospheric layer until time t.

Parameters
tscalar

The time to which to evolve the atmospheric layer.

property outer_scale

The outer scale of the phase structure function.

phase_for(self, wavelength)

Get the phase screen at a certain wavelength.

Each atmospheric layer is modelled as an infinitely-thin phase screen.

Parameters
wavelengthscalar

The wavelength at which to calculate the phase screen.

reset(self)

Reset the phase screen.

This will create a randomized uncorrelated phase screen.

class hcipy.atmosphere.InfiniteAtmosphericLayer(input_grid, Cn_squared=None, L0=inf, velocity=0, height=0, stencil_length=2, use_interpolation=False)

Bases: hcipy.atmosphere.atmospheric_model.AtmosphericLayer

property Cn_squared

The integrated value of Cn^2 for the layer.

property L0
evolve_until(self, t)

Evolve the atmospheric layer until time t.

Parameters
tscalar

The time to which to evolve the atmospheric layer.

property outer_scale

The outer scale of the phase structure function.

phase_for(self, wavelength)

Get the phase screen at a certain wavelength.

Each atmospheric layer is modelled as an infinitely-thin phase screen.

Parameters
wavelengthscalar

The wavelength at which to calculate the phase screen.

reset(self)

Reset the phase screen.

This will create a randomized uncorrelated phase screen.

class hcipy.atmosphere.ModalAdaptiveOpticsLayer(layer, controlled_modes, lag)

Bases: hcipy.atmosphere.atmospheric_model.AtmosphericLayer

property Cn_squared

The integrated value of Cn^2 for the layer.

property L0
evolve_until(self, t)

Evolve the atmospheric layer until time t.

Parameters
tscalar

The time to which to evolve the atmospheric layer.

property outer_scale

The outer scale of the phase structure function.

phase_for(self, wavelength)

Get the phase screen at a certain wavelength.

Each atmospheric layer is modelled as an infinitely-thin phase screen.

Parameters
wavelengthscalar

The wavelength at which to calculate the phase screen.

reset(self)

Reset the phase screen.

This will create a randomized uncorrelated phase screen.

hcipy.atmosphere.make_standard_atmospheric_layers(input_grid, L0=10)

Wavefront sensing

class hcipy.wavefront_sensing.WavefrontSensorOptics(optical_elements)

Bases: hcipy.optics.optical_element.OpticalSystem

The optics for a wavefront sensor.

This object serves as the base class for all optics in a wavefront sensor.

class hcipy.wavefront_sensing.WavefrontSensorEstimator

Bases: object

The estimator for a wavefront sensor.

This object serves as the base class for all estimators in a wavefront sensor. It calculates from a list of images what the wavefront is. This wavefront can be anything that responds to wavefront changes, such as slopes, pupil amplitude, etc…

estimate(self, images)

Estimate the wavefront from images.

Parameters
imageslist

The list of images on which to base the estimate.

Returns
Field or ndarray

The estimate of the wavefront.

hcipy.wavefront_sensing.optical_differentiation_surface(filter_size, amplitude_filter, separation, wavelength_0, refractive_index)

Creates a function which can create the complex multiplexed surface for the ODWFS on a grid.

Parameters
filter_sizescalar

The physical size of the filter in lambda/D.

amplitude_filterlambda function

A lambda function which acts on the focal plane grid to create a amplitude filter.

separationscalar

The separation of the pupils in pupil diameters.

wavelength_0scalar

The reference wavelength for the filter specifications.

refractive_indexlambda function

A lambda function for the refractive index which accepts a wavelength.

Returns
funcfunction

The returned function acts on a grid to create the amplitude filters for that grid.

class hcipy.wavefront_sensing.OpticalDifferentiationWavefrontSensorOptics(filter_size, amplitude_filter, pupil_grid, pupil_diameter, pupil_separation, num_pupil_pixels, q, wavelength_0, refractive_index, num_airy=None)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorOptics

The value of some physical quantity for each point in some coordinate system.

Parameters
filter_sizescalar

The physical size of the filter in lambda/D.

amplitude_filterlambda function

A lambda function which acts on the focal plane grid to create a amplitude filter.

pupil_gridGrid

The input pupil grid.

pupil_diameterscalar

The size of the pupil. If it is set to None the pupil_diameter will be the diameter of the pupil_grid.

pupil_separationscalar

The separation distance between the pupils in pupil diameters.

num_pupil_pixelsint

The number of pixels that are used to sample the output pupil.

qscalar

The focal plane oversampling coefficient.

wavelength_0scalar

The reference wavelength which determines the physical scales.

refractive_indexfunction

A function that returns the refractive index as function of wavelength.

num_airyint

The size of the intermediate focal plane grid that is used in terms of lambda/D at the reference wavelength.

Attributes
output_gridGrid

The output grid of the wavefront sensor.

focal_gridGrid

The intermediate focal plane grid where the focal plane is sampled.

pupil_to_focalFraunhoferPropagator

A propagator for the input pupil plane to the intermediate focal plane.

focal_to_pupilFraunhoferPropagator

A propagator for the intermediate focal plane to the output pupil plane.

focal_maskMultiplexedComplexSurfaceApodizer

The filter that is applied in the focal plane.

forward(self, wavefront)

Propagates a wavefront through the wavefront sensor.

Parameters
wavefrontWavefront

The input wavefront that will propagate through the system.

Returns
wfWavefront

The output wavefront.

class hcipy.wavefront_sensing.gODWavefrontSensorOptics(filter_size, beta, pupil_grid, pupil_diameter=None, pupil_separation=1.5, num_pupil_pixels=32, q=4, wavelength_0=1, refractive_index=<function gODWavefrontSensorOptics.<lambda>>, num_airy=None)

Bases: hcipy.wavefront_sensing.optical_differentiation_wavefront_sensor.OpticalDifferentiationWavefrontSensorOptics

A generalised optical differentiation wavefront sensor based on linear amplitude filters.

Parameters
filter_sizescalar

The physical size of the filter in lambda/D.

betascalar

The step size. A value of 0 corresponds to a linear filter and a value of 1 to a full step.

pupil_gridGrid

The input pupil grid.

pupil_diameterscalar

The size of the pupil. If it is set to None the pupil_diameter will be the diameter of the pupil_grid.

pupil_separationscalar

The separation distance between the pupils in pupil diameters.

num_pupil_pixelsint

The number of pixels that are used to sample the output pupil.

qscalar

The focal plane oversampling coefficient.

wavelength_0scalar

The reference wavelength which determines the physical scales.

refractive_indexfunction

A function that returns the refractive index as function of wavelength.

num_airyint

The size of the intermediate focal plane grid that is used in terms of lambda/D at the reference wavelength.

Attributes
output_gridGrid

The output grid of the wavefront sensor.

focal_gridGrid

The intermediate focal plane grid where the focal plane is sampled.

pupil_to_focalFraunhoferPropagator

A propagator for the input pupil plane to the intermediate focal plane.

focal_to_pupilFraunhoferPropagator

A propagator for the intermediate focal plane to the output pupil plane.

focal_maskMultiplexedComplexSurfaceApodizer

The filter that is applied in the focal plane.

class hcipy.wavefront_sensing.RooftopWavefrontSensorOptics(pupil_grid, pupil_diameter=None, pupil_separation=1.5, num_pupil_pixels=32, q=4, wavelength_0=1, refractive_index=<function RooftopWavefrontSensorOptics.<lambda>>, num_airy=None)

Bases: hcipy.wavefront_sensing.optical_differentiation_wavefront_sensor.OpticalDifferentiationWavefrontSensorOptics

A rooftop wavefront sensor.

Parameters
pupil_gridGrid

The input pupil grid.

pupil_diameterscalar

The size of the pupil. If it is set to None the pupil_diameter will be the diameter of the pupil_grid.

pupil_separationscalar

The separation distance between the pupils in pupil diameters.

num_pupil_pixelsint

The number of pixels that are used to sample the output pupil.

qscalar

The focal plane oversampling coefficient.

wavelength_0scalar

The reference wavelength which determines the physical scales.

refractive_indexfunction

A function that returns the refractive index as function of wavelength.

num_airyint

The size of the intermediate focal plane grid that is used in terms of lambda/D at the reference wavelength.

Attributes
output_gridGrid

The output grid of the wavefront sensor.

focal_gridGrid

The intermediate focal plane grid where the focal plane is sampled.

pupil_to_focalFraunhoferPropagator

A propagator for the input pupil plane to the intermediate focal plane.

focal_to_pupilFraunhoferPropagator

A propagator for the intermediate focal plane to the output pupil plane.

focal_maskMultiplexedComplexSurfaceApodizer

The filter that is applied in the focal plane.

class hcipy.wavefront_sensing.PolgODWavefrontSensorOptics(filter_size, beta, pupil_grid, pupil_diameter=None, pupil_separation=1.5, num_pupil_pixels=32, q=4, wavelength_0=1, refractive_index=<function PolgODWavefrontSensorOptics.<lambda>>, num_airy=None)

Bases: hcipy.wavefront_sensing.optical_differentiation_wavefront_sensor.OpticalDifferentiationWavefrontSensorOptics

A generalised optical differentiation wavefront sensor based on linear amplitude filters.

Parameters
filter_sizescalar

The physical size of the filter in lambda/D.

betascalar

The step size. A value of 0 corresponds to a linear filter and a value of 1 to a full step.

pupil_gridGrid

The input pupil grid.

pupil_diameterscalar

The size of the pupil. If it is set to None the pupil_diameter will be the diameter of the pupil_grid.

pupil_separationscalar

The separation distance between the pupils in pupil diameters.

num_pupil_pixelsint

The number of pixels that are used to sample the output pupil.

qscalar

The focal plane oversampling coefficient.

wavelength_0scalar

The reference wavelength which determines the physical scales.

refractive_indexfunction

A function that returns the refractive index as function of wavelength.

num_airyint

The size of the intermediate focal plane grid that is used in terms of lambda/D at the reference wavelength.

Attributes
output_gridGrid

The output grid of the wavefront sensor.

focal_gridGrid

The intermediate focal plane grid where the focal plane is sampled.

pupil_to_focalFraunhoferPropagator

A propagator for the input pupil plane to the intermediate focal plane.

focal_to_pupilFraunhoferPropagator

A propagator for the intermediate focal plane to the output pupil plane.

focal_maskMultiplexedComplexSurfaceApodizer

The filter that is applied in the focal plane.

class hcipy.wavefront_sensing.OpticalDifferentiationWavefrontSensorEstimator(aperture, output_grid)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorEstimator

Estimates the wavefront slopes from OD wavefront sensor images.

Parameters
aperturefunction

A function which mask the pupils for the normalized differences.

output_gridGrid

The grid on which the output of an OD wavefront sensor is sampled.

Attributes
measurement_gridGrid

The grid on which the normalized differences are defined.

pupil_maskarray_like

A mask for the normalized differences.

num_measurementsint

The number of pixels in the output vector.

estimate(self, images)

A function which estimates the wavefront slope from a ODWFS image.

Parameters
imagesList

A list of scalar intensity fields containing OD wavefront sensor images.

Returns
resField

A field with wavefront sensor slopes.

class hcipy.wavefront_sensing.ModulatedPyramidWavefrontSensor(pyramid_wavefront_sensor, modulation, num_steps=12)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorOptics

The optical elements for a modulated pyramid wavefront sensor.

Parameters
pyramid_wavefront_sensorWavefrontSensorOptics

The pyramid wavefront sensor optics that are used.

modulationscalar

The modulation radius in radians.

num_stepsint

The number of steps per modulation cycle.

backward(self, wavefront)

Propagate a wavefront backward through the optical system.

This will be implemented by the derived class.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagates a wavefront through the modulated pyramid wavefront sensor.

Parameters
wavefrontWavefront

The input wavefront that will propagate through the system.

Returns
wf_modulatedlist

A list of wavefronts for each modulation position.

class hcipy.wavefront_sensing.PyramidWavefrontSensorOptics(input_grid, separation=None, wavelength_0=1, q=None, num_airy=None, refractive_index=<function PyramidWavefrontSensorOptics.<lambda>>)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorOptics

The optical elements for a pyramid wavefront sensor.

Parameters
input_gridGrid

The grid on which the input wavefront is defined.

separationscalar

The separation between the pupils. The default takes the input grid extent as separation.

wavelength_0scalar

The reference wavelength that determines the physical scales.

qscalar

The focal plane oversampling coefficient. The default uses the minimal required sampling.

refractive_indexcallable

A callable that returns the refractive index as function of wavelength. The default is a refractive index of 1.5.

num_airyscalar

The radius of the focal plane spatial filter in units of lambda/D at the reference wavelength.

backward(self, wavefront)

Propagates a wavefront backwards through the pyramid wavefront sensor.

Parameters
wavefrontWavefront

The input wavefront that will propagate through the system.

Returns
wf_pupilWavefront

The output wavefront.

forward(self, wavefront)

Propagates a wavefront through the pyramid wavefront sensor.

Parameters
wavefrontWavefront

The input wavefront that will propagate through the system.

Returns
wf_wfsWavefront

The output wavefront.

class hcipy.wavefront_sensing.PyramidWavefrontSensorEstimator(aperture)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorEstimator

Estimates the wavefront slopes from pyramid wavefront sensor images.

Parameters
aperturefunction

A function which mask the pupils for the normalized differences.

output_gridGrid

The grid on which the output of a pyramid wavefront sensor is sampled.

Attributes
measurement_gridGrid

The grid on which the normalized differences are defined.

pupil_maskarray_like

A mask for the normalized differences.

num_measurementsint

The number of pixels in the output vector.

estimate(self, images)

A function which estimates the wavefront slope from a pyramid image.

Parameters
images - list

A list of scalar intensity fields containing pyramid wavefront sensor images.

Returns
res - Field

A field with wavefront sensor slopes.

class hcipy.wavefront_sensing.ShackHartmannWavefrontSensorOptics(input_grid, micro_lens_array)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorOptics

class hcipy.wavefront_sensing.SquareShackHartmannWavefrontSensorOptics(input_grid, f_number, num_lenslets, pupil_diameter)

Bases: hcipy.wavefront_sensing.shack_hartmann.ShackHartmannWavefrontSensorOptics

class hcipy.wavefront_sensing.ShackHartmannWavefrontSensorEstimator(mla_grid, mla_index, estimation_subapertures=None)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorEstimator

estimate(self, images, use_par_map=True)

Estimate the wavefront from images.

Parameters
imageslist

The list of images on which to base the estimate.

Returns
Field or ndarray

The estimate of the wavefront.

class hcipy.wavefront_sensing.ZernikeWavefrontSensorOptics(input_grid, phase_step=1.5707963267948966, phase_dot_diameter=1.06, num_pix=128, pupil_diameter=1, reference_wavelength=1)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorOptics

The optical elements for a Zernike wavefront sensor.

This class uses a propagation scheme similar to that of Lyot coronagraphs with a small blocking mask, see [R6ba030122989-1].

R6ba030122989-1

Soummer et al. 2007, “Fast computation of Lyot-style

coronagraph propagation”

Parameters
input_gridGrid

The grid on which the input wavefront is defined.

phase_stepscalar

The phase of the phase dot of the zernike wavefront sensor. The default is pi/2.

phase_dot_diameterscalar

The diameter of the phase dot. This has units of lambda_0/D.

num_pixscalar

The number of pixels across the phase dot.

pupil_diameterscalar

The diameter of the pupil. This is used for calculating the size of the phase dot.

reference_wavelengthscalar

The reference wavelength. This is used for calcualting the size of the phase dot.

backward(self, wavefront)

Propagates a wavefront backwards through the wavefront sensor.

Parameters
wavefrontWavefront

The input wavefront that will propagate through the system.

Returns
wfWavefront

The output wavefront.

forward(self, wavefront)

Propagates a wavefront through the wavefront sensor.

Parameters
wavefrontWavefront

The input wavefront that will propagate through the system.

Returns
wfWavefront

The output wavefront.

class hcipy.wavefront_sensing.ZernikeWavefrontSensorEstimator(aperture, output_grid, reference)

Bases: hcipy.wavefront_sensing.wavefront_sensor.WavefrontSensorEstimator

Estimates the wavefront slopes from pyramid wavefront sensor images.

Parameters
aperturefunction

A function which mask the output phase measurements.

output_gridGrid

The grid on which the output of a pyramid wavefront sensor is sampled.

referenceField

A reference image to subtract from the Zernike wavefront sensor data.

Attributes
measurement_gridGrid

The grid on which the phase measurements are defined.

pupil_maskarray_like

A mask for the phase measurements.

num_measurementsint

The number of pixels in the output vector.

referenceField

A reference image to subtract from the Zernike wavefront sensor data.

estimate(self, images)

A function which estimates the phase from a Zernike wavefront sensor image.

Parameters
images - List

A list of scalar intensity fields containing Zernike wavefront sensor images.

Returns
res - Field

A field with phase estimates.

Wavefront control

Coronagraphy

hcipy.coronagraphy.generate_app_keller(wavefront, propagator, contrast, num_iterations, beta=0)

Accelerated Gerchberg-Saxton-like algorithm for APP design by Christoph Keller [1] and based on Douglas-Rachford operator splitting. The acceleration was inspired by the paper by Jim Fienup [2_]. The acceleration can provide speed-ups of up to two orders of magnitude and produce better APPs.

1

Keller C.U., 2016, “Novel instrument concepts for characterizing directly imaged exoplanets”, Proc. SPIE 9908, Ground-based and Airborne Instrumentation for Astronomy VI, 99089V doi: 10.1117/12.2232633; https://doi.org/10.1117/12.2232633

2

J. R. Fienup, 1976, “Reconstruction of an object from the modulus of its Fourier transform,” Opt. Lett. 3, 27-29

Parameters
wavefontWavefront

The input aperture as a wavefront; a phase can be provided as a starting point for the APP generation.

propagatorPropagator

The propagator from the pupil grid to the focal plane grid.

contrastarray_like

The required contrast in the focal plane; this is a float mask that is 1.0 everywhere except for the dark zone where it is the contrast such as 1e-5.

num_iterationsint

The maximum number of iterations.

betascalar

The acceleration parameter. The default is 0 (no acceleration). Good values for beta are typically between 0.3 and 0.9. Values larger than 1.0 will not work.

Returns
Wavefront

The APP as a wavefront.

Raises
ValueError

If beta is not between 0 and 1.

hcipy.coronagraphy.generate_app_por(wavefront, propagator, propagator_max, contrast, num_iterations=1)

Optimize a one-sided APP using a globally optimal algorithm. This algorithm does not apply any symmetries for two-sided dark zones or circularly-symmetric pupils. This function requires that you have installed the Gurobi optimizer.

Parameters
wavefontWavefront

The input aperture as a wavefront.

propagatorPropagator

The propagator from wavefront to the focal plane grid.

propagator_maxPropagator

The propagator from wavefront to the point in the focal-plane that we want to maximize.

contrastarray_like or scalar

The required contrast in the focal plane.

num_iterationsint

The number of iterations for the Strehl ratio to converge.

Returns
Field

The resultant electric field transmission function.

class hcipy.coronagraphy.KnifeEdgeLyotCoronagraph(input_grid, q=8, apodizer=None, lyot_stop=None)

Bases: hcipy.optics.optical_element.OpticalElement

A Lyot-style coronagraph with a centered, knife-edge focal-plane mask.

As the knife-edge is invariant along one axis, the Fourier transforms can be sped up by only taking them along one axis. Also, the zero-padding only needs to be done along that axis, reducing memory usage while doing the transform.

The knife-edge is set along the y-axis, so perpendicular to the x-axis.

Parameters
input_gridGrid

The grid of the wavefront that is to be propagated.

qscalar

The amount of oversampling used for the knife edge.

apodizerOpticalElement or Field or None

The pre-apodizer in the pupil before the focal-plane mask. If this is a Field, it will be converted into an apodizer. If this is None, no apodizer will be used.

lyot_maskOpticalElement or Field

The Lyot stop in the pupil after the focal-plane mask. If this is a Field, it will be converted to an apodizer. If this is None, no Lyot stop will be used.

backward(self, wavefront)

Propagate a wavefront backward through the knife-edge coronagraph.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

forward(self, wavefront)

Propagate a wavefront forward through the knife-edge coronagraph.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The propagated wavefront.

class hcipy.coronagraphy.LyotCoronagraph(input_grid, focal_plane_mask, lyot_stop=None)

Bases: hcipy.optics.optical_element.OpticalElement

A Lyot coronagraph with a small focal-plane mask.

The area outside of this focal-plane mask is assumed to be fully transmisive. The method for propagation is based on [Re6cf568957a6-1].

Re6cf568957a6-1

Soummer et al. 2007, “Fast computation of Lyot-style

coronagraph propagation”.

Parameters
input_gridGrid

The grid on which the incoming wavefront is defined.

focal_plane_maskField or OpticalElement

The (complex) transmission of the focal-plane mask. If this is an OpticalElement, this will be used instead. This allows for more realistic implementations of focal-plane masks.

lyot_stopField or OpticalElement or None

The (complex) transmission of the Lyot stop. If this is an OpticalElement, this will be used instead. This allows for more realistic implementations of Lyot stops.

backward(self, wavefront)

Propagate the wavefront from the Lyot plane to the pupil plane.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The pupil-plane wavefront.

forward(self, wavefront)

Propagate the wavefront through the Lyot coronagraph.

Parameters
wavefrontWavefront

The wavefront to propagate. This wavefront is assumed to be in the pupil plane.

Returns
Wavefront

The Lyot-plane wavefront.

class hcipy.coronagraphy.OccultedLyotCoronagraph(input_grid, focal_plane_mask)

Bases: hcipy.optics.optical_element.OpticalElement

A Lyot coronagraph with a focal-plane mask.

The area outside of this focal-plane mask is assumed to be fully absorbing.

Parameters
input_gridGrid

The grid on which the incoming wavefront is defined.

focal_plane_maskField or OpticalElement

The (complex) transmission of the focal-plane mask. If this is an OpticalElement, this will be used instead. This allows for more realistic implementations of focal-plane masks.

lyot_stopField or OpticalElement or None

The (complex) transmission of the Lyot stop. If this is an OpticalElement, this will be used instead. This allows for more realistic implementations of Lyot stops.

backward(self, wavefront)

Propagate the wavefront from the Lyot plane to the pupil plane.

Parameters
wavefrontWavefront

The wavefront to propagate.

Returns
Wavefront

The pupil-plane wavefront.

forward(self, wavefront)

Propagate the wavefront through the Lyot coronagraph.

Parameters
wavefrontWavefront

The wavefront to propagate. This wavefront is assumed to be in the pupil plane.

Returns
Wavefront

The Lyot-plane wavefront.

class hcipy.coronagraphy.PerfectCoronagraph(aperture, order=2, coeffs=None)

Bases: hcipy.optics.optical_element.OpticalElement

A perfect coronagraph for a certain aperture and order.

These type of coronagraphs suppress all light for a flat wavefront. The incoming complex amplitude \(A\) is modified as follows (following [Rfa5357f0a262-1]):

\[\overline{A} = A - \Pi \sqrt{S}\]

where \(\overline{A}\) is the resulting complex ampliutude, \(\Pi\) is the telescope pupil, and \(S\) is the Strehl ratio of the incoming wavefront.

Higher orders are added by fitting higher-order electric field modes to the incoming wavefront and subtracting those, following [Rfa5357f0a262-2].

Rfa5357f0a262-1

Celine Cavarroc et al. “Fundamental limitations on Earth-like planet detection with extremely large telescopes.” Astronomy & Astrophysics 447.1 (2006): 397-403

Rfa5357f0a262-2(1,2)

Olivier Guyon et al. “Theoretical limits on extrasolar terrestrial planet detection with coronagraphs.” The Astrophysical Journal Supplement Series 167.1 (2006): 81

Parameters
apertureField

The reference aperture. The perfect coronagraph is designed for this aperture.

orderinteger

The order of the perfect coronagraph. This must be even.

coeffslist or ndarray or None

The coefficients that are used for subtraction. This allows for partial suppression of certain modes, which can be used to design perfect coronagraphs that are insensitive to stellar radius [Rfa5357f0a262-2]. If it is None, all modes are completely suppressed.

backward(self, wavefront)

Propagate the wavefront backwards through the perfect coronagraph.

This method behaves the same as the forward propagation.

Parameters
wavefrontWavefront

The incoming wavefront (in the pupil plane)

Returns
Wavefront

The post-coronagraphic wavefront (in the pupil plane).

forward(self, wavefront)

Propagate the wavefront through the perfect coronagraph.

Parameters
wavefrontWavefront

The incoming wavefront (in the pupil plane)

Returns
Wavefront

The post-coronagraphic wavefront (in the pupil plane).

get_transformation_matrix_backward(self, wavelength=1)

Get the backwards propagation transformation matrix.

This method behaves the same as the forward propagation.

Parameters
wavelengthscalar

The wavelength at which to calculate the transformation matrix.

Returns
ndarray

The backward transformation_matrix.

get_transformation_matrix_forward(self, wavelength=1)

Get the forward propagation transformation matrix.

Parameters
wavelengthscalar

The wavelength at which to calculate the transformation matrix.

Returns
ndarray

The forward transformation_matrix.

class hcipy.coronagraphy.VortexCoronagraph(input_grid, charge=2, levels=4, scaling_factor=4)

Bases: hcipy.optics.optical_element.OpticalElement

An optical vortex coronagraph.

This OpticalElement simulations the propagation of light through a vortex in the focal plane. To resolve the singularity of this vortex phase plate, a multi-scale approach is made. Discretisation errors made at a certain level are corrected by the next level with finer sampling.

Parameters
input_gridGrid

The grid on which the incoming wavefront is defined.

chargeinteger

The charge of the vortex.

levelsinteger

The number of levels in the multi-scale sampling.

scaling_factorscalar

The fractional increase in spatial frequency sampling per level.

backward(self, wavefront)

Propagate backwards through the vortex coronagraph.

This essentially is a forward propagation through a the same vortex coronagraph, but with the sign of the its charge flipped.

Parameters
wavefrontWavefront

The Lyot plane wavefront.

Returns
Wavefront

The pupil-plane wavefront.

forward(self, wavefront)

Propagate a wavefront through the vortex coronagraph.

Parameters
wavefrontWavefront

The wavefront to propagate. This wavefront is expected to be in the pupil plane.

Returns
Wavefront

The Lyot plane wavefront.

hcipy.coronagraphy.make_ravc_masks(central_obscuration, charge=2, pupil_diameter=1, lyot_undersize=0)

Make field generators for the pupil and Lyot-stop masks for a ring apodized vortex coronagraph.

The formulas were implemented according to [1].

1

Dimitri Mawet et al. 2013 “Ring-apodized vortex coronagraphs for obscured telescopes. I. Transmissive ring apodizers” The Astrophysical Journal Supplement Series 209.1 (2013): 7

Parameters
central_obscurationscalar

The diameter of the central obscuration.

chargeinteger

The charge of the vortex coronagraph used.

pupil_diameterscalar

The diameter of the pupil.

lyot_undersizescalar

The fraction of the pupil diameter to which to undersize the Lyot stop.

Returns
pupil_maskField generator

The complex transmission of the pupil mask.

lyot_maskField generator

The complex transmission of the Lyot-stop mask.

hcipy.coronagraphy.get_ravc_planet_transmission(central_obscuration_ratio, charge=2)

Get the planet transmission for a ring-apodized vortex coronagraph.

The formulas were implemented according to [1].

1

Dimitri Mawet et al. 2013 “Ring-apodized vortex coronagraphs for obscured telescopes. I. Transmissive ring apodizers” The Astrophysical Journal Supplement Series 209.1 (2013): 7

Parameters
central_obscuration_ratioscalar

The ratio of the central obscuration diameter and the pupil diameter.

chargeinteger

The charge of the vortex coronagraph used.

Returns
scalar

The intensity transmission for a sufficiently off-axis point source for the ring-apodized vortex coronagraph. Point sources close to the vortex singularity will be lower in intensity.

Data reduction

Miscellaneous

Math utilities

hcipy.math_util.inverse_truncated(M, rcond=1e-15, svd=None)

Invert M truncating the number of modes.

Modes are given by a singular value decomposition of the input matrix. If svd is given, it is used instead. Modes are ordered in descending order by their singular values. All modes with a singular value lower than rcond times the maximum singular value, will be ignored.

Parameters
Mndarray

The matrix to invert. This matrix must be two-dimensional.

rcondscalar

The relative condition number of the highest-order mode that must be used for inversion.

svdSVD object

A precalculated singular value decomposition object. This will be used if supplied, to avoid recalculation of an SVD.

Returns
ndarray

The inverted matrix.

hcipy.math_util.inverse_truncated_modal(M, num_modes, svd=None)

Invert M with num_modes modes.

Modes are given by a singular value decomposition of the input matrix. If svd is given, it is used instead. Modes are ordered in descending order by their singular values.

Parameters
Mndarray

The matrix to invert. This matrix must be two-dimensional.

num_modesinteger

The number of modes to use for the inversion. Higher-order modes are ignored.

svdSVD object

A precalculated singular value decomposition object. This will be used if supplied, to avoid recalculation of an SVD.

Returns
ndarray

The inverted matrix.

hcipy.math_util.inverse_tikhonov(M, rcond=1e-15, svd=None)

Invert M using Tikhonov regularization.

Tikhonov regularization will be an identity matrix, with strength rcond * the maximum singular value of the matrix.

Parameters
Mndarray

The matrix to invert. This matrix must be two-dimensional.

rcondscalar

The relative strength of the regularization. An identity matrix will be used for the regularization.

svdSVD object

A precalculated singular value decomposition object. This will be used if supplied, to avoid recalculation of an SVD.

Returns
ndarray

The inverted matrix.

class hcipy.math_util.SVD(M, num_modes=None)

Bases: object

The Singular Value Decomposition for the provided matrix.

This class wraps two versions of the SVD in numpy and scipy, and provides easy access to singular modes (as mode bases) and allows for calculation of the SVD for a limited number of modes.

When a sparse matrix is passed, and no number of modes is given, all but one mode will be calculated. The reason is that the sparse SVD implementation in Scipy doesn’t allow calculation of all modes. If all modes are required, the user must pass a densified version of the matrix (ie. M.toarray()).

Parameters
Mndarray or any sparse matrix

The matrix on which to perform the SVD.

num_modesint or None

The number of singular values and modes to calculate. If this is None, and M is not sparse, all modes will be computed. If this is None and M is sparse, all but one mode will be computed.

property M

The matrix for which the SVD was calculated.

property S

The singular values of the matrix.

property U

The U matrix of the SVD.

property Vt

The V^T matrix of the SVD.

property left_singular_modes

The left singular modes of the matrix, as a ModeBasis.

property num_modes

The number of singular modes that were calculated in this SVD.

property right_singular_modes

The right singular modes of the matrix, as a ModeBasis.

property singular_values

The singular values of the matrix.

property svd

The raw U, S, and V^T matrices of the SVD as a tuple.

Interpolation

hcipy.interpolation.make_linear_interpolator_separated(field, grid=None, fill_value=nan)

Make a linear interpolators for a separated grid.

Parameters
fieldField or ndarray

The field to interpolate.

gridGrid or None

The grid of the field. If it is given, the grid of field is replaced by this grid.

fill_valuescalar

The value to use for points outside of the domain of the input field. If this is None, the values outside the domain are extrapolated.

Returns
Field generator

The interpolator, as a Field generator. The grid on which this field generator will evaluated, does not have to be separated.

hcipy.interpolation.make_linear_interpolator_unstructured(field, grid=None, fill_value=nan)

Make a linear interpolator for an unstructured grid.

Parameters
fieldField or array_like

The field to interpolate.

gridGrid or None

The grid of the field. If it is given, the grid of field is replaced by this grid.

fill_valuescalar

The value to use for points outside of the domain of the input field. Extrapolation is not supported.

Returns
Field generator

The interpolator as a Field generator. The grid on which this field generator will be evaluated does not need to have any structure.

hcipy.interpolation.make_linear_interpolator(field, grid=None, fill_value=None)

Make a linear interpolator for any type of grid.

Parameters
fieldField or array_like

The field to interpolate.

gridGrid or None

The grid of the field. If it is given, the grid of field is replaced by this grid.

fill_valuescalar or None

The value to use for points outside of the domain of the input field. Extrapolation is not supported. If it is None, a numpy.nan value will be used for points outside of the domain.

Returns
Field generator

The interpolator as a Field generator. The grid on which this field generator will be evaluated does not need to have any structure.

hcipy.interpolation.make_nearest_interpolator_separated(field, grid=None)

Make a nearest interpolator for a field on a separated grid.

Parameters
fieldField or ndarray

The field to interpolate.

gridGrid or None

The grid of the field. If it is given, the grid of field is replaced by this grid.

Returns
Field generator

The interpolator, as a Field generator. The grid on which this field generator will evaluated, does not have to be separated.

hcipy.interpolation.make_nearest_interpolator_unstructured(field, grid=None)

Make a nearest interpolator for an unstructured grid.

Parameters
fieldField or array_like

The field to interpolate.

gridGrid or None

The grid of the field. If it is given, the grid of field is replaced by this grid.

Returns
Field generator

The interpolator as a Field generator. The grid on which this field generator will be evaluated does not need to have any structure.

hcipy.interpolation.make_nearest_interpolator(field, grid=None)

Make a nearest interpolator for any type of grid.

Parameters
fieldField or array_like

The field to interpolate.

gridGrid or None

The grid of the field. If it is given, the grid of field is replaced by this grid.

Returns
Field generator

The interpolator as a Field generator. The grid on which this field generator will be evaluated does not need to have any structure.

Metrics

hcipy.metrics.get_strehl_from_focal(img, ref_img)

Get the Strehl ratio from a focal-plane image.

Parameters
imgField or array_like

The focal-plane image.

ref_imgField or array_like

The reference focal-plane image without aberrations.

Returns
scalar

The Strehl ratio.

hcipy.metrics.get_strehl_from_pupil(aperture, ref_aperture)

Get the Strehl ratio from a pupil-plane electric field.

Parameters
apertureField or array_like

The pupil-plane electric field.

ref_apertureField or array_like

The reference pupil-plane electric field without aberrations.

Returns
scalar

The Strehl ratio.

hcipy.metrics.get_mean_intensity_in_roi(img, mask)

Get the mean intensity in a masked region of interest.

Parameters
imgField or array_like

The focal-plane image.

maskField or array_like

A binary array describing the region of interest.

Returns
scalar

The mean intensity in the region of interest.

hcipy.metrics.get_mean_raw_contrast(img, mask, ref_img)

Get the mean raw contrast in a masked region of interest.

Parameters
imgField or array_like

The focal-plane image.

maskField or array_like

A binary array describing the region of interest.

img_refField or array_like

A reference focal-plane image without aberrations. This is used to determine the Strehl ratio.

Returns
scalar

The mean raw contrast in the region of interest.

hcipy.metrics.binned_profile(y, x, bins=20)

Create a profile of y(x) in the specified bins.

Parameters
yarray_like

The y-coordinates of the data points. This should be 1-dimensional.

xarray_like

The x-coordinates of the data points. This should be 1-dimensional and the same size as y.

binsarray_like or int

The bin edges of the profile. If this is an integer, bins is the number of bins that will be equally distributed along the whole range of x.

Returns
bin_centersarray_like

The center of each of the bins.

profilearray_like

The y-values of the resulting profile.

std_profilearray_like

The standard deviation within each bin.

num_per_binarray_like

The number of samples per bin.

hcipy.metrics.azimutal_profile(image, num_bins)

Create an azimuthal profile of the image around its center.

Parameters
imageField

The image that we want an azimuthal profile from. This image must be two-dimensional.

num_binsint

The number of bins in theta. Bins will be equally distributed in theta.

Returns
bin_centersarray_like

The center of each of the bins.

profilearray_like

The y-values of the resulting azimuthal profile.

std_profilearray_like

The standard deviation within each bin.

num_per_binarray_like

The number of samples per bin.

hcipy.metrics.radial_profile(image, bin_size)

Create a radial profile of the image around its center.

Parameters
imageField

The image that we want an azimuthal profile from. This image must be two-dimensional.

bin_sizescalar

The extent of each bin. Each bin will be a ring from r to r+`bin_size`.

Returns
bin_centersarray_like

The center of each of the bins.

profilearray_like

The y-values of the resulting radial profile.

std_profilearray_like

The standard deviation within each bin.

num_per_binarray_like

The number of samples per bin.

Plotting

class hcipy.plotting.GifWriter(filename, framerate=15)

Bases: object

add_frame(self, fig=None, arr=None, cmap=None)
close(self)
class hcipy.plotting.FFMpegWriter(filename, codec=None, framerate=24, quality=None, preset=None)

Bases: object

add_frame(self, fig=None, arr=None, cmap=None)
close(self)
hcipy.plotting.set_color_scheme(dark=False, publication_quality=False, cmap='viridis')

Apply a color scheme to all matplotlib figures. The setting publication_quality uses LaTeX for all text in the figure.

hcipy.plotting.plot_kde_density_1d(x, bw_method=None, n_steps=200, alpha_fill=0.25, rug=False, overshoot=0.1, ax=None, kernel_size=None, **kwargs)

Plot a 1D kernel density estimate function of the data.

hcipy.plotting.plot_kde_density_2d(x, y, bw_method=None, n_steps=200, ax=None, overshoot=0.1, kernel_size=None, **kwargs)

Plot a 2D kernel density estimate function of the data.

hcipy.plotting.plot_rug(x, height=0.05, axis='x', color='k', ax=None)

Plot a rug density plot efficiently. The height parameter is the length of the rug marks given as a fraction of the axis length perpendicular to the axis the marks are attached to.

hcipy.plotting.plot_density_scatter(x, y, xsacle=1, yscale=1, sort=False, **kwargs)
hcipy.plotting.errorfill(x, y, y_err_pos, y_err_neg=None, color=None, alpha_fill=0.25, ax=None, **kwargs)

Plot a line with filled errorbars.

hcipy.plotting.imshow_field(field, grid=None, ax=None, vmin=None, vmax=None, aspect='equal', norm=None, interpolation=None, non_linear_axes=False, cmap=None, mask=None, mask_color='k', *args, **kwargs)

Display a two-dimensional image on a matplotlib figure.

This function serves as an easy replacement for the matplotlib.pyplot.imshow() function. Its signature mostly folows that of matplotlib, with a few minor differences.

Parameters
fieldField or ndarray

The field that we want to display. If this is an ndarray, then the parameter grid needs to be supplied. If the field is complex, then it will be automatically fed into complex_field_to_rgb(). If the field is a vector field with length 3 or 4, these will be interpreted as an RGB or RGBA field.

gridGrid or None

If a grid is supplied, it will be used instead of the grid of field.

axmatplotlib axes

The axes which to draw on. If it is not given, the current axes will be used.

vminscalar

The minimum value on the colorbar. If it is not given, then the minimum value of the field will be used.

vmaxscalar

The maximum value on the colorbar. If it is not given, then the maximum value of the field will be used.

aspect[‘auto’, ‘equal’, scalar]

If ‘auto’, changes the image aspect ratio to match that of the axes. If ‘equal’, changes the axes aspect ratio to match that of the image.

normNormalize

A Normalize instance is used to scale the input to the (0, 1) range for input to the cmap. If it is not given, a linear scale will be used.

interpolationstring

The interpolation method used. The default is ‘nearest’. Supported values are {‘nearest’, ‘bilinear’}.

non_linear_axesboolean

If axes are scaled in a non-linear way, for example on a log plot, then imshow_field needs to use a more expensive implementation. This parameter is to indicate that this algorithm needs to be used.

cmapColormap

The colormap with which to plot the image. It is ignored if a complex field or a vector field is supplied.

maskfield or ndarray

If part of the image needs to be masked, this mask is overlayed on top of the image. This is for example useful when plotting a phase pattern on a certain aperture, which has no meaning outside of the aperture. Masks can be partially translucent, and will be automatically scaled between (0, 1). Zero means invisible, one means visible.

mask_colorColor

The color of the mask, if it is used.

Returns
AxesImage

The produced image.

hcipy.plotting.imsave_field(filename, field, grid=None, vmin=None, vmax=None, norm=None, mask=None, mask_color='w', cmap=None)
hcipy.plotting.contour_field(field, grid=None, ax=None, *args, **kwargs)
hcipy.plotting.contourf_field(field, grid=None, ax=None, *args, **kwargs)
hcipy.plotting.complex_field_to_rgb(field, theme='dark', rmin=None, rmax=None, norm=None)

Takes an array of complex number and converts it to an array of [r, g, b], where phase gives hue and saturaton/value are given by the absolute value. Especially for use with imshow for complex plots.

Statistics

class hcipy.statistics.SpectralNoiseFactory(psd, output_grid, psd_args=(), psd_kwargs={})

Bases: object

make_random(self)
make_zero(self)
class hcipy.statistics.SpectralNoise

Bases: object

copy(self)
evaluate(self)
shift(self, shift)
shifted(self, shift)
class hcipy.statistics.SpectralNoiseFactoryFFT(psd, output_grid, oversample=1, psd_args=(), psd_kwargs={})

Bases: hcipy.statistics.spectral_noise.SpectralNoiseFactory

make_random(self)
make_zero(self)
class hcipy.statistics.SpectralNoiseFFT(factory, C)

Bases: hcipy.statistics.spectral_noise.SpectralNoise

shift(self, shift)
class hcipy.statistics.SpectralNoiseFactoryMultiscale(psd, output_grid, oversampling, psd_args=(), psd_kwargs={})

Bases: hcipy.statistics.spectral_noise.SpectralNoiseFactory

make_random(self)
make_zero(self)
class hcipy.statistics.SpectralNoiseMultiscale(factory, C_1, C_2)

Bases: hcipy.statistics.spectral_noise.SpectralNoise

shift(self, shift)
hcipy.statistics.large_poisson(lam, thresh=1000000.0)

Draw samples from a Poisson distribution, taking care of large values of lam.

At large values of lam the distribution automatically switches to the corresponding normal distribution. This switch is independently decided for each expectation value in the lam array.

Parameters
lamarray_like

Expectation value for the Poisson distribution. Must be >= 0.

threshfloat

The threshold at which the distribution switched from a Poisson to a normal distribution.

Returns
array_like

The drawn samples from the Poisson or normal distribution, depending on the expectation value.

Techniques

class hcipy.techniques.ElectricFieldConjugation(wavefront, dark_hole_grid, influence_functions=None, propagator=None, matrix_invertor=None)

Bases: object

property efc_matrix
get_mode_basis(self, num_modes=-1)
property matrix_invertor
single_step(self)
property svd
hcipy.techniques.make_cgh(pupil_grid, mode, position, amplitude)
hcipy.techniques.make_multiplexed_cgh(pupil_grid, modes, positions, amplitudes)