PyStarshade API Reference

class pystarshade.propagator.StarshadeProp(drm=None, d_s_mas=2, d_t_mas=0.05, d_p_mas=2, d_wl=50)

Pre-compute files and propagate light past a starshade.

Parameters:

drm (str) – Design reference mission (e.g., ‘wfirst’ or ‘hwo’).
d_s_mas (float, optional) – Source angular resolution in milliarcseconds, defaults to 2.
d_t_mas (float, optional) – Pixel shift in the pupil plane corresponding to the angular field, defaults to 0.05.
d_p_mas (float, optional) – Pixel size in the focal plane in milliarcseconds, defaults to 2.
d_wl (float, optional) – Wavelength step size in nanometers, defaults to 50.

Examples

>>> hwo_starshade = StarshadeProp(drm='hwo')
>>> hwo_starshade.gen_pupil_field()
>>> hwo_starshade.gen_psf_basis(pupil_type='hex')
>>> hwo_starshade.gen_scene(pupil_type='hex', source_field, 500e-9)

gen_psf_basis(pupil_type, pupil_symmetry=False)

Generate the incoherent PSF basis for a particular pupil and starshade.

Contrast is measured in units of if no starshade were present, i.e., just FFT of the pupil_mask. If the pupil is symmetric, only generate the positive quadrant of PSFs.

Parameters:

pupil_type (str) – The type of pupil aperture (e.g., ‘circ’, ‘hex’).
pupil_symmetry (bool, optional) – Whether to use symmetry to reduce computation, defaults to False.

gen_pupil(pupil_type)

Generate a pupil mask (uses HCIPy). Pupil options are:

circ, ELT, GMT, TMT, Hale, LUVOIR-A, LUVOIR-B, Magellan, VLT, HiCAT, HabEx, HST, JWST, Keck, hex

Parameters:: pupil_type (str) – The type of pupil aperture (e.g., ‘circ’, ‘hex’).

gen_pupil_field(chunk=1, use_gpu=None)

Generate the field at the pupil for the chosen starshade.

Parameters:

chunk (int, optional) – Whether to use chunked parallel processing (if so, must use a memmap file).
use_gpu (bool or None, optional) – If None (default), auto-detect GPU. If True, require GPU. If False, force CPU.

gen_scene(pupil_type, source_field, wl, pupil_symmetry=False)

Generate the output scene intensity.

Parameters:

pupil_type (str) – The type of pupil used (e.g., circular, hex).
source_field (np.ndarray) – The input source field array, representing the spatial distribution of the source.
wl (float) – The wavelength of light in meters.
pupil_symmetry (bool, optional) – Whether the pupil symmetry should be considered, defaults to False.

Returns:

A 2D imaged field representing the output intensity.

Return type:

np.ndarray

Notes

psf_off_axis can be much larger than the output N_p.
N_s: Number of source pixels.
N_p: Number of output pixels.

set_mission_params(drm, mask_choice=1, band_i=0)

Load the design reference mission (defined inside data/telescope_drm.py).

Parameters:

drm (str) – Design reference mission (‘wfirst’, ‘hwo’, etc.).
mask_choice (int, optional) – Mask sampling choice.
band_i (int, optional) – Wavelength band index.

class pystarshade.diffraction.diffract.Fresnel(d_x, N_in, z, wavelength)

Represents a Fresnel diffraction computation setup.

Variables:

d_x (float) – Spatial sampling interval of the input field [m].
N_in (int) – Number of non-zero input samples.
z (float) – Propagation distance [m].
wavelength (float) – Wavelength of the light [m].
wl_z (float) – Product of the wavelength and propagation distance.
k (float) – Wave number.
max_freq (float) – Maximum frequency of the input field.

class pystarshade.diffraction.diffract.FresnelSingle(d_x, d_f, N_in, z, wavelength, use_gpu=None)

Single FFT Fresnel diffraction.

Variables:

d_x (float) – Spatial sampling interval of the input field [m].
d_f (float) – Desired frequency sampling interval [m^-1].
N_in (int) – Number of non-zero input samples.
z (float) – Propagation distance [m].
wavelength (float) – Wavelength of the light [m].
wl_z (float) – Product of the wavelength and propagation distance.
ZP (float) – Zero-padding factor.
N_X (float) – Phantom length for zero-padded signal.
From (Inherits) –
------------- –
Fresnel –

calc_phantom_length()

Calculate the equivalent zero-padded signal length N_X to achieve a specified output frequency (d_f) for spatial sampling (d_x) using the single FT method.

Returns:: Zero-padded signal length (N_X). N_X = Z_pad * N_in + 1 - phantom padded length of input signal
Return type:: float

calc_zero_padding()

Calculate the zero-padding factor (ZP * N_in) to achieve a specified frequency spacing (d_f) for a given spatial sampling (d_x) using the Fresnel single FT method.

Returns:: Zero-padding factor (ZP * N_in) to achieve the desired frequency spacing.
Return type:: float

nchunk_zoom_fresnel_single_fft(x_file, N_out, N_chunk=None)

Single FFT Fresnel diffraction calculated using an N_chunk*N_chunk -way chunked Bluestein FFT (caps peak memory usage). Use me if the mask is big!

If use_gpu was set (or auto-detected) at construction time, this method uses the GPU-accelerated Bluestein FFT.

Define x_file as: arr = np.memmap(‘x.dat’, dtype=np.complex128,mode=’w+’,shape=(N_x, N_x)) arr[:] = x arr.flush()

Parameters:

x_file (np.memmap) – Input mask filename as a memory-mapped object.
N_out (int) – Number of output samples.
N_chunk (int, optional) – Number of chunks along each axis. Default is 8.

Returns:

np.ndarray: Propagated output field.
float: Output grid sampling.

Return type:

tuple

zoom_fresnel_single_fft(field, N_out)

Perform single FFT Fresnel diffraction using a Bluestein FFT. Output on grid defined by (N_out/ZP*N_in)*wl_z/d_x, (N_out/ZP*N_in)*wl_z/d_x

Parameters:

field (np.ndarray) – 2D input field to be propagated.
N_out (int) – Number of output samples in each dimension.

Returns:

np.ndarray: Propagated output field.
float: Output grid sampling.

Return type:

tuple

class pystarshade.diffraction.diffract.Fraunhofer(d_x, d_f, N_in, z, wavelength)

This class computes Fraunhofer diffraction, including zero-padding calculations.

Variables:

d_x (float) – Spatial sampling interval of the input field [m].
d_f (float) – Desired frequency sampling interval [m^-1].
N_in (int) – Number of non-zero input samples.
z (float) – Propagation distance [m].
wavelength (float) – Wavelength of light [m].
wl_z (float) – Product of the wavelength and propagation distance (wavelength * z).
max_freq (float) – Maximum frequency of the input field, defined as 1 / d_x.
ZP (float) – Zero-padding factor, computed to achieve a specified frequency spacing.
N_X (float) – Phantom length for zero-padded signal, calculated based on input parameters.

calc_phantom_length()

Calculate the equivalent zero-padded signal length (N_X) to achieve a specified output frequency (d_f) for spatial sampling (d_x) using the single FT method.

Parameters:: class). (None (all relevant attributes are already part of the) –
Returns:: N_X : N_X = Z_pad * N_in + 1 - phantom padded length of input signal
Return type:: float

calc_zero_padding()

Calculate the zero-padding factor (ZP * N_in) to achieve a specified frequency spacing (d_f) for a given spatial sampling (d_x) using the Fresnel single FT method.

Parameters:: class). (None (all relevant attributes are already part of the) –
Returns:: Zero-padding factor (ZP * N_in) to achieve the desired frequency spacing.
Return type:: float

zoom_fraunhofer(field, N_out)

Perform Fraunhofer diffraction at points within [(N_out/ZP*N_in)*wl_z/d_x, (N_out/ZP*N_in)*wl_z/d_x] using the Bluestein FFT.

Parameters:

field (np.ndarray) – 2D input field to be propagated.
N_out (int) – Number of output samples in each dimension.

Returns:

output_fieldnp.ndarray
Propagated output field.
dffloat
Output grid sampling.

Return type:

tuple

class pystarshade.diffraction.field.SourceField(d_s, N_s, wavelength, z, source_field)

Computes far-field diffraction for an N_s x N_s source field using a Bluestein FFT.

Variables:

d_s (float) – Source field sampling.
N_s (int) – Number of samples in the field.
wavelength (float) – Wavelength of light.
z (float) – Far-field distance.
source_field (np.ndarray) – The source field array.

Notes

The class uses a plane wave description of the far-field. Either d_s_mas or d_s and z must be defined.

farfield(d_x, N_x, z1)

Calculate the far-field diffraction of a source field at a local distance z1 over an (N_x, N_x) grid. Note: z1 is defined as a local distance, the origin is set in the far-field.

Parameters:

d_x (float) – Output spatial sampling.
N_x (int) – Number of output samples.
z1 (float) – Propagation distance (Note: computationally, the origin is treated as the starshade plane).

Returns:

A 2D array representing the computed field over the grid.

Return type:

np.ndarray

class pystarshade.diffraction.field.Field(d_x, N, wavelength, z)

This class returns analytic far-field diffraction for sources, or can be used to generate source fields

Variables:

d_x (float) – Spatial sampling of the field.
N (int) – Number of samples in the field.
wavelength (float) – Wavelength of light.
z (float) – Far-field distance.

Notes

Includes plane-wave fields, Gaussian sources, and point sources.

update(d_x=None, N=None)

Update the sampling (d_x) and number of samples (N).

Parameters:

d_x (float, optional) – New value for spatial sampling.
N (int, optional) – New value for the number of samples.

class pystarshade.diffraction.field.PointSource(d_x, N, wavelength, x, y, z, A)

Computes far-field diffraction for a point source.

Variables:

d_x (float) – Spatial sampling of the output field.
N (int) – Number of samples in the output field.
wavelength (float) – Wavelength of light.
x (float) – x-coordinate of the source.
y (float) – y-coordinate of the source.
z (float) – Far-field distance.
A (float) – Amplitude of the source.
From (Inherits) –
------------- –
Field –

plane_wave(k, z1)

Compute a plane wave with amplitude A and wavevector k on a Cartesian grid.

Parameters:

k (np.ndarray) – Wave vector [k_x, k_y, k_z].
z1 (float) – Propagation distance (Note: computationally, the origin is treated as the starshade plane).

Returns:

A 2D array representing the computed plane wave on the grid.

Return type:

np.ndarray

wave_numbers()

Calculate planar wave numbers for a point source at position (x, y, z).

Returns:: A 1D array [k_x, k_y, k_z] representing planar wave numbers.
Return type:: np.ndarray

Notes

Based on Blahut (Theory of Remote Image Formation, sec 1.7).