coffee
Coronagraph Optimization For Fast Exoplanet Exploration
PIAACMCsimul.h File Reference

Go to the source code of this file.

Data Structures

struct  PIAACMCsimul_varType
 
struct  OPTPIAACMCDESIGN
 

Functions

1. INITIALIZATION, configurations

Allocate memory, import/export configurations

void __attribute__ ((constructor)) libinit_PIAACMCsimul()
 
int_fast8_t init_PIAACMCsimul ()
 Module initialization. More...
 
void PIAACMCsimul_free (void)
 Free PIAACMC memory. More...
 
void PIAACMCsimul_init (OPTPIAACMCDESIGN *design, long index, double TTxld, double TTyld)
 initializes the optsyst structure to simulate reflective PIAACMC system More...
 
int PIAACMCsimul_initpiaacmcconf (long piaacmctype, double fpmradld, double centobs0, double centobs1, int WFCmode, int load)
 initializes configuration More...
 
int PIAACMCsimul_update_fnamedescr_conf ()
 Assemble focal plane mask configuration name. More...
 
int PIAACMCsimul_update_fnamedescr ()
 Assemble focal plane mask name. More...
 
int PIAACMCsimul_savepiaacmcconf (const char *dname)
 Save configuration. More...
 
int PIAACMCsimul_loadpiaacmcconf (const char *dname)
 Load configuration. More...
 
2. Focal plane mask construction

Define focal plane mask geometry

long PIAACMCsimul_mkFPM_zonemap (const char *IDname)
 
long PIAACMCsimul_rings2sectors (const char *IDin_name, const char *sectfname, const char *IDout_name)
 Rings to sectors. More...
 
long PIAACMCsimul_mkFocalPlaneMask (const char *IDzonemap_name, const char *ID_name, int mode, int saveMask)
 Make complex amplitude focal plane mask. More...
 
3. PIAA optics (geometrical optics)

Create PIAA opics according to geometrical optics

uint_fast8_t PIAACMCsimul_load2DRadialApodization (const char *IDapo_name, float beamradpix, const char *IDapofit_name)
 
int PIAACMCsimul_init_geomPIAA_rad (const char *IDapofit_name)
 
int PIAACMCsimul_mkPIAAMshapes_from_RadSag (const char *fname, const char *ID_PIAAM0_name, const char *ID_PIAAM1_name)
 Make PIAA OPD screens from radial sag profile. More...
 
int PIAACMCsimul_makePIAAshapes (OPTPIAACMCDESIGN *design, long index)
 
4. Lyot stop(s)

Create, optimize and manage Lyot stop(s)

long PIAACMCsimul_mkSimpleLyotStop (const char *ID_name, float rin, float rout)
 
double PIAACMCsimul_optimizeLyotStop (const char *IDamp_name, const char *IDpha_name, const char *IDincoh_name, float zmin, float zmax, double throughput, long NBz, long NBmasks)
 Lyot stops positions from zmin to zmax relative to current, working back (light goes from 0 to zmax) More...
 
long PIAACMCsimul_mkLyotMask (const char *IDincoh_name, const char *IDmc_name, const char *IDzone_name, double throughput, const char *IDout_name)
 
long PIAACMCsimul_geomProp (const char *IDin_name, const char *IDsag_name, const char *IDout_name, const char *IDoutcnt_name, float drindex, float pscale, float zprop, float krad, float kstep, float rlim)
 Lyot stops positions from zmin to zmax relative to current, working back (light goes from 0 to zmax) More...
 
5. Focal plane mask optimization

Create, optimize and manage Focal plane solutions

double PIAACMCsimul_achromFPMsol_eval (double *fpmresp_array, double *zonez_array, double *dphadz_array, double *outtmp_array, long vsize, long nbz, long nbl)
 
double PIAACMCsimul_achromFPMsol_eval_zonezderivative (long zone, double *fpmresp_array, double *zonez_array, double *dphadz_array, double *outtmp_array, long vsize, long nbz, long nbl)
 
long PIAACMC_FPMresp_rmzones (const char *FPMresp_in_name, const char *FPMresp_out_name, long NBzones)
 
long PIAACMC_FPMresp_resample (const char *FPMresp_in_name, const char *FPMresp_out_name, long NBlambda, long PTstep)
 
6. Focal plane processing

Process / resample focal plane solutions

long PIAACMC_FPM_process (const char *FPMsag_name, const char *zonescoord_name, long NBexp, const char *outname)
 
7. High level routines

High level optimization and evaluation routines

int PIAACMCsimul_exec (const char *confindex, long mode)
 Main simulation routine. More...
 
double PIAACMCsimul_computePSF (float xld, float yld, long startelem, long endelem, int savepsf, int sourcesize, int extmode, int outsave)
 Compute PSF. More...
 
long PIAACMCsimul_CA2propCubeInt (const char *IDamp_name, const char *IDpha_name, float zmin, float zmax, long NBz, const char *IDout_name)
 Propagate complex amplitude image into intensity map cube. More...
 
int PIAACMCsimul_run (const char *confindex, long mode)
 
int PIAACMCsimul_exec_compute_image ()
 Compute PSF or image scene. More...
 
int PIAACMCsimul_exec_optimize_lyot_stop_position ()
 
int PIAACMCsimul_exec_optimize_fpmtransmission ()
 
double PIAACMCsimul_exec_computePSF_no_fpm ()
 
int PIAACMCsimul_exec_optimize_PIAA_shapes ()
 
int PIAACMCsimul_exec_optimize_lyot_stops_shapes_positions ()
 
int PIAACMCsimul_exec_multizone_fpm_calib ()
 
int PIAACMCsimul_exec_optimize_fpm_zones ()
 
int PIAACMCsimul_exec_optimize_PIAA_shapes_fpmtransm ()
 
int PIAACMCsimul_measure_transm_curve ()
 
int PIAACMCsimul_eval_poly_design ()
 

Function Documentation

void __attribute__ ( (constructor)  )
int_fast8_t init_PIAACMCsimul ( )

Module initialization.

Registers command line interface (CLI) commands

long PIAACMC_FPM_process ( const char *  FPMsag_name,
const char *  zonescoord_name,
long  NBexp,
const char *  outname 
)
long PIAACMC_FPMresp_resample ( const char *  FPMresp_in_name,
const char *  FPMresp_out_name,
long  NBlambda,
long  PTstep 
)
long PIAACMC_FPMresp_rmzones ( const char *  FPMresp_in_name,
const char *  FPMresp_out_name,
long  NBzones 
)
double PIAACMCsimul_achromFPMsol_eval ( double *  fpmresp_array,
double *  zonez_array,
double *  dphadz_array,
double *  outtmp_array,
long  vsize,
long  nbz,
long  nbl 
)
double PIAACMCsimul_achromFPMsol_eval_zonezderivative ( long  zone,
double *  fpmresp_array,
double *  zonez_array,
double *  dphadz_array,
double *  outtmp_array,
long  vsize,
long  nbz,
long  nbl 
)
long PIAACMCsimul_CA2propCubeInt ( const char *  IDamp_name,
const char *  IDpha_name,
float  zmin,
float  zmax,
long  NBz,
const char *  IDout_name 
)

Propagate complex amplitude image into intensity map cube.

double PIAACMCsimul_computePSF ( float  xld,
float  yld,
long  startelem,
long  endelem,
int  savepsf,
int  sourcesize,
int  extmode,
int  outsave 
)

Compute PSF.

Returns
Average contrast in evaluation zone

Source is defined by parameters sourcesize and extmode :

  • source size = 1e-{sourcesize*0.1}, except if sourcesize = 0 (point source)
  • sourcesize is a 2-digit number ( 10 = 0.1 l/D, 20 = 0.01 l/D etc..)
  • extmode = 0 : 1 point (point source)
  • extmode = 1 : 3 point sources, 120 apart on circle radius = source size
  • extmode = 2 : 6 point sources. 3 as above on circle radius 1/sqrt(2.5) + 3 on outer circle, radius 2/sqrt(2.5), 120 apart, clockled 60 deg off inner points
Note
If opderrcube exists, include each slice as a WF mode

PSF is held in shared memory by default


Output

name type Description
scoringmask 2D image focal plane points used for evaluation
<piaacmcdir>/scoringmask<N>.fits 2D FITS focal plane points used for evaluation
imvec 1D image output vector
psfi0 3D image output PSF


Create scoring mask if it doesn't exist

The scoring mask is the array of evaluation points on the focal plane

Fast PSF computattion (if piaacmcsimul_var.computePSF_FAST_FPMresp = 1)

Note
Only possible if mode 11 has already been executed

Compute the PSF as the complex amplitude for the evaluation points on the focal plane for a given FPM zone thickness based on the FPMresp array computed in mode 11

PSF result is stored in outtmp_array

  • Use imvect for storage if it exists, or create it
  • Write the result into imvect
  • Total flux in the output vector is stored in piaacmcsimul_var.PIAACMCSIMUL_VAL0 as total flux

set value to average value per area normalized to flux

Full/Slow PSF computation (if piaacmcsimul_var.computePSF_FAST_FPMresp = 0)

The PSF for an extended source is approximated as a collection of point sources. Sourcesize determines the separation of the point sources

OPTIONAL: Add OPD error to list of modes

  • Average over all the PSFs we've created to simulate this extended source
  • If outsave = 1, save PSF to FITS file
  • If outsave = 1, save flux to txt file

calls PIAACMCsimul_init()

calls PIAACMCsimul_makePIAAshapes()

Parameters
yld
[in]xldfloat: Source X position [l/D]
startelem
[in]yldfloat: Source Y position [l/D]
endelem
[in]startelemlong : First element in propagation
savepsf
[in]endelemlong : Last element in propagation
sourcesize
[in]savepsfint : Save PSF flag
extmode
[in]sourceziseint : Source size (10x log10)
outsave
[in]extmodeint : Source extended type
[in]outsaveint : Save output flag
int PIAACMCsimul_eval_poly_design ( )

compute contrast curve

compute contrast curve measure average contrast value, 2-6 lambda/D

int PIAACMCsimul_exec ( const char *  confindex,
long  mode 
)

Main simulation routine.

Parameters
[in]confindexPIAACMC configuration index pointing to the input/output directory number
[in]modeType of operation to be performed
int PIAACMCsimul_exec_compute_image ( )

Compute PSF or image scene.

double PIAACMCsimul_exec_computePSF_no_fpm ( )

Mode 3: Calibrate, no focal plane mask (not currently used)

Compute PSF and contrast with no focal plane mask with the current design.

Provides the denominator for the contrast estimate

Saved by PIAACMCsimul_computePSF as fits file "psfi0"

int PIAACMCsimul_exec_multizone_fpm_calib ( )

Mode 11: Setup multizone ring mask and Compute polychromatic response to zones, store result in FPMresp

here we compute how the light propagates from each individual mask zone to the focal plane (where each mask zone is completely tranparent)

int PIAACMCsimul_exec_optimize_fpm_zones ( )

Mode 13: Optimize focal plane mask zones only

Uses "fast" mode:

After mode 11, we can use the (complex) light propagated from each zone to compute the impact of any thickness (sag) of that zone: the zone thickness induces a phase rotation for that zone, which is applied to the unobstructed light from that zone as a complex rotation.

The search is via steepest descent from random starting points.

This mode only sets up the optimization that actually happens after exiting the switch statement if piaacmcsimul_var.LINOPT = 1 (as does mode 40)

int PIAACMCsimul_exec_optimize_fpmtransmission ( )

Mode 2: Optimize focal plane mask transmission for monochromatic idealized PIAACMC

For monochromatic, idealized PIAACMC, find the scalar transimssion of the uniform focal plane mask that provides best contrast in the evaluation zone

Very similar to the Lyot stop search in mode 1: iterative refined marching, changing the the transmission value piaacmc[0].fpmaskamptransm, which is between 0 and 1

Uses single on-axis light source

Initialize as in mode 0

Initialize search range and step

Scan parameter value

While within the search loop :

int PIAACMCsimul_exec_optimize_lyot_stop_position ( )

Mode 1: Optimize Lyot stop positions

Lyot stop positions are encoded as piaacmc[0].LyotStop_zpos

there can be multiple LyotStop_zpos

Vary these zpos, looking for the best contrast returned by PIAACMCsimul_computePSF

Search is performed by iterative refined marching

int PIAACMCsimul_exec_optimize_lyot_stops_shapes_positions ( )

Mode 5: Optimize Lyot stops shapes and positions

Initialize as in mode 0

Load CLI variables as appropriate

  • <- PIAACMC_nbpropstep : # of propagation steps along the beam
  • <- PIAACMC_lstransm : desired Lyot stop transmission

Identify post focal plane pupil plane (first pupil after focal plane mask)

Provides reference complex amplitude plane for downstream analysis

Compute incoherent 3D illumination near pupil plane

Multiple off-axis sources are propagated and the corresponding intensities added

  • -> OAincohc Output incoherent image (3D)

OAincohc is the summed light "all" from off-axis sources in the pupil, including the on-axis source(!), giving intensity contribution of all off-axis sources in order to preserve the intensity of the off-axis in the design. load OAincohc if exist, maybe we've been here before

Compute on-axis PSF 3D intensity to define light to reject

call function PIAACMCsimul_CA2propCubeInt() to compute 3D intensity cube

Parameters
[out]iprop003D intensity image

Compute image that has the min along z of OAincohc at each x,y

Function PIAACMCsimul_optimizeLyotStop_offaxis_min() computes minimal intensity image.

Optimize Lyot stops

The actual Lyot stop shape and location optimization is done by PIAACMCsimul_optimizeLyotStop(), producing optimal Lyot stops in optLM*.fits and position relative to elem0 in piaacmc[0].LyotStop_zpos

int PIAACMCsimul_exec_optimize_PIAA_shapes ( )

Mode 4: Optimize PIAA optics shapes, cosine modes only (not currently used, replaced by mode 40. skipping)

int PIAACMCsimul_exec_optimize_PIAA_shapes_fpmtransm ( )

Mode 40: Optimize PIAA optics shapes (and focal plane mask transmission for idealized PIAACMC)

void PIAACMCsimul_free ( void  )

Free PIAACMC memory.

Frees memory for module

long PIAACMCsimul_geomProp ( const char *  IDin_name,
const char *  IDsag_name,
const char *  IDout_name,
const char *  IDoutcnt_name,
float  drindex,
float  pscale,
float  zprop,
float  krad,
float  kstep,
float  rlim 
)

Lyot stops positions from zmin to zmax relative to current, working back (light goes from 0 to zmax)

Parameters
[in]IDin_nameimage : Input 2D intensity
[in]IDsag_nameimage : 2D sag
[out]IDout_nameimage : 2D propagated intensity
[out]IDoutcnt_nameimage : 2D rays counter
[in]drindexfloat : refractive index (2 for mirror)
[in]pscalefloat : pixel scale [m]
[in]zpropfloat : propagation distance [m]
[in]kradfloat : kernel radius used to evaluate slope [pixel]
[in]kstepfloat : step size in input pupil [pixel]
[in]rlimfloat : clear aperture radius (don't compute outside this value) [pixel]
void PIAACMCsimul_init ( OPTPIAACMCDESIGN design,
long  index,
double  TTxld,
double  TTyld 
)

initializes the optsyst structure to simulate reflective PIAACMC system

initializes the optsyst structure to simulate reflective PIAACMC system

Fills in an OPTSYST global optsyst (see OptSysProp.h) which describes the optical system as a series of planes based on the input design structure

TTxld and TTyld are tip/tilt x-y coordinates specifying the location of the source relative to the optical axis in units of lambda/D

Note
Index allows multiple configurations, but it's always 0. Nonzero values are untested

call PIAACMCsimul_mkFocalPlaneMask() to make the focal plane mask

int PIAACMCsimul_init_geomPIAA_rad ( const char *  IDapofit_name)

computes radial PIAA optics sag

this function only works for circular PIAA uses radial PIAACMC design to initialize PIAA optics shapes and focal plane mask

int PIAACMCsimul_initpiaacmcconf ( long  piaacmctype,
double  fpmradld,
double  centobs0,
double  centobs1,
int  WFCmode,
int  load 
)

initializes configuration

initializes configuration

List of Configuration Parameters

Each parameter is stored on disk as conf/conf_.txt

PIAA OPTICS DESIGN:

Parameter Meaning
PIAAmode PIAA mode (0: classical apodization, 1: PIAA)
fpmradld Focal plane mask radius [l/D]
PIAAcoeff Fraction of PIAA apodization
coin Central obstruction at input beam [beam radius]
coout Central obstruction at output beam [beam radius]
PIAAmaterial PIAA optics material
PIAAcirc FLAG: 1 if PIAA shapes are circular (no Fourier modes)
REGPIAACCOEFF PIAA regularization amplitude, cosine modes
REGPIAACALPHA PIAA regularization power law, cosine modes
REGPIAAFCOEFF PIAA regularization amplitude, Fourier modes
REGPIAAFALPHA PIAA regularization power law, Fourier modes

LYOT STOP(S) DESIGN:

Parameter Meaning
LStransm Lyot stop transmission
NBls Number of Lyot stops
lambda Wavelength for monochromatic design [nm]

FOCAL PLANE MASK DESIGN:

Parameter Meaning
fpmmaterial focal plane mask material
FPMsectors mask geometry: 0=disk, 1=sectors, 2=hexagonal tiling
NBrings number of rings in focal plane mask
maskradld mask outer radius at central wavelength [l/D]
fpmminsag min focal plane mask sag
fpmmaxsag max focal plane mask sag
fpmregsag_coeff sag regularization coefficient
fpmregsag_alpha sag regularization coefficient exponent
fpmccnbr how many central rings replaced by cone (set to 0 if no central cone
fpmccz sag at cone center (sag at cone edge will be midpoint between minsag and maxsag)
fpmocradld outer cone outer radius [l/D]
fpmocz sag at inner edge of outer cone (sag = 0 at outer edge), set to 0 if no outer cone

OPTIMIZATION PARAMETERS:

Parameter Meaning
mlambda central wavelength for polychromatic design [nm]
mlambdaB spectral bandwidth [%]
nblambda Number of wavelength values
ssize source angular size for mask optimization (20: 0.01 l/D; 10: 0.1 l/D)
extmode source extent mode (0: 1 point, 1: 3 points; 2: 6 points)

OPTICAL DESIGN:

Parameter Meaning
size array size
beamrad beam radius [mm]
pscale pixel scale in pupil [m/pix]
Fratio F ratio at focal plane mask
PIAAr0lim outer edge of PIAA optic 0 [beam radius unit]
PIAAr1lim outer edge of PIAA optic 1 [beam radius unit]
PIAAsep distance between PIAA optics [m]
PIAA0pos PIAA optic 0 distance from pupil plane [m]
invPIAAmode 0: no inv PIAA, 1: inv PIAA after Lyot stops, 2: inv PIAA before Lyot stops
prePIAA0maskpos pre-PIAA optic 0 mask distance from pupil plane m
postPIAA0maskpos post-PIAA optic 0 mask distance from pupil plane m
piaaNBCmodesmax maximum number of radial cosine modes for PIAA optics
piaaCPAmax maximum spatial frequency (CPA) for PIAA optics
LyotZmin minimum value for Lyot stop(s) conjugation range [m] - relative to element named "post focal plane mask pupil"
LyotZmax maximum value for Lyot stop(s) conjugation range [m] - relative to element named "post focal plane mask pupil"
pupoutmaskrad output pupil mask radius (scaled to pupil radius)
Parameters
[in]piaacmctypeType of system: 0=idealized mask, 1=physical mask
[in]fpmradldFocal plane mask nominal radius
[in]centobs0Input central obstruction
[in]centobs1Output central obstruction
[in]WFSmodeNumber of DMs (0: no WFC)
[in]loadif 1, attempt to load configuration from file

piaacmctype:

  • 0: if configuration does not exist, create Monochromatic idealized PIAACMC, otherwise, read configuration
  • 1: physical mask

Wavefront control

uint_fast8_t PIAACMCsimul_load2DRadialApodization ( const char *  IDapo_name,
float  beamradpix,
const char *  IDapofit_name 
)
int PIAACMCsimul_loadpiaacmcconf ( const char *  dname)

Load configuration.

int PIAACMCsimul_makePIAAshapes ( OPTPIAACMCDESIGN design,
long  index 
)

mirror sag shapes: piaam0z, piaam1z

piaa0Cmodescoeff -> piaa0Cz piaa0Fmodescoeff -> piaa0Fz piaa0Cz + piaa0Fz -> piaam0z

int PIAACMCsimul_measure_transm_curve ( )

Mode 101: Measure transmission as a function of angular separation

long PIAACMCsimul_mkFocalPlaneMask ( const char *  IDzonemap_name,
const char *  ID_name,
int  mode,
int  saveMask 
)

Make complex amplitude focal plane mask.

Parameters
[in]IDzonemap_namezones
[in]ID_name
[in]modeif mode = -1, make whole 1-fpm, if mode = zone, make only 1 zone with CA = (1.0, 0.0)
[in]saveMask1 if mask saved to file system

if mode is invalid number, no focal plane mask, AND assume 1-fpm is computed

zone numbering starts here from 1 (zone 1 = outermost ring)

long PIAACMCsimul_mkFPM_zonemap ( const char *  IDname)
Parameters
[out]IDnameName of output image
long PIAACMCsimul_mkLyotMask ( const char *  IDincoh_name,
const char *  IDmc_name,
const char *  IDzone_name,
double  throughput,
const char *  IDout_name 
)

Make Lyot stop geometry param[in] IDincoh_name Incoherent Lyot pupil intensity response to off-axis sources parampin] IDmc_name Intensity Lyot pupil image for on-axis source

explores two thresholding methods applied together : (1) keeps pixels for which offaxisLight / onaxisLight > rsl (2) keeps pixels for which onaxisLight < v0 selects the mask that achieves the strongest on-axis rejection while satifying the throughput constraint

int PIAACMCsimul_mkPIAAMshapes_from_RadSag ( const char *  fname,
const char *  ID_PIAAM0_name,
const char *  ID_PIAAM1_name 
)

Make PIAA OPD screens from radial sag profile.

long PIAACMCsimul_mkSimpleLyotStop ( const char *  ID_name,
float  rin,
float  rout 
)
double PIAACMCsimul_optimizeLyotStop ( const char *  IDamp_name,
const char *  IDpha_name,
const char *  IDincohc_name,
float  zmin,
float  zmax,
double  throughput,
long  NBz,
long  NBmasks 
)

Lyot stops positions from zmin to zmax relative to current, working back (light goes from 0 to zmax)

Parameters
[in]IDamp_nameimage : 2D amplitude
[in]IDpha_nameimage : 2D phase
[in]IDincohc_nameimage : 3D incoherent intensity
[in]zminfloat : minimum propagation value
[in]zmaxfloat : maximum propagation value
[in]throughputdouble: Geometric throughput of Lyot stop(s)
[in]NBzlong : Number of discrete propagation planes between zmin and zmax
[in]NBmaskslong : Number of Lyot stop(s)

call PIAACMCsimul_mkLyotMask()

long PIAACMCsimul_rings2sectors ( const char *  IDin_name,
const char *  sectfname,
const char *  IDout_name 
)

Rings to sectors.

Parameters
[in]IDin_nameinput image: circular mask design
[in]sectfnametext file specifying which zones belong to which rings
[out]IDout_nameoutput sector mask design
int PIAACMCsimul_run ( const char *  confindex,
long  mode 
)
Parameters
mode
[in]confindexconfiguration index (sets name of directory for results)
[in]modeoperation to be executed
int PIAACMCsimul_savepiaacmcconf ( const char *  dname)

Save configuration.

int PIAACMCsimul_update_fnamedescr ( )

Assemble focal plane mask name.

int PIAACMCsimul_update_fnamedescr_conf ( )

Assemble focal plane mask configuration name.