functions in yao.i -

             func aoinit(disp=,forcemat=)  
 
   Second function of the ao serie.  
   Initialize everything in preparation for the loop (aoloop).  
   Follows a call to aoread,parfile.  
   Keywords:  
   disp: set to display stuff  
   forcemat: set to force measuring new iMat and computing new cMat.  
   keepdmconfig: when forcemat=1, the default behavior is to agregate the  
   previously determined active and extrapolated actuators and do the  
   new interacton matrix with all of them. The selection of valid/extrapolated  
   is then reset (and re-executed when the interaction matrix is done).  
   Setting keepdmconfig=1 impose that the valid/extrapolated setting remains  
   as it was.  
   This routine uses:  
   - the ao structures (atm, wfs, ...)  
   This routine calls:  
   - a bunch of initialization routines  
   This routine sets:  
   - a bunch of things.  

             func aoread(parfile)  
 
   Define the relevant structure/variable, and reads out the  
   AO simulation parameter file (e.g. "sh6.par"),  
   Does a check of the WFS pixel/subaperture sizes.  
   This is the first function to call in the ao serie (normally,  
   aoinit and aoloop follow).  
   This routine was kept separate from aoinit to keep the possibility  
   to change variables inbetween the aoread and the aoinit calls.  
   example:  
   > aoread,"sh6.par"  
   > loop.niter = 1000  
   > aoinit  
   This routine uses:  
   - the parameter file (e.g. "sh6.par")  
       
   This routine calls:  
   - wfsCheckPixelSize  
       
   This routine sets:  
   - the atm,sim,wfs,dm,mat,tel,target,gs,loop structure contents  
   - parprefix  

 atm_struct  
 
struct atm_struct  
{  
  float   dr0at05mic;     // Dr0 at sensing wavelength, at zenith. Required [none].  
  pointer screen;         // string vectorptr. Screen file names. Required [none].  
  pointer layerfrac;      // float vectorptr. Layer fraction. Sum to one is insured  
  // in aoinit. Required [none]  
  pointer layerspeed;     // float vectorptr. Layer speed. Required [none]  
  pointer layeralt;       // float vectorptr. Layer altitude (m). Specified at Zenith.  
  // Required [none]  
  pointer winddir;        // Wind dir (use 0 for now)  
  // Internal variables  
  pointer _layeralt;      // float vectorptr. Actual layer altitude (m), from atm.alt & zen.angle  
};  

             buildComMat(all=,nomodalgain=,disp=)  
 
   Build the command matrix from V,UT, the eigenvalues and the modal gains  
   F.Rigaut, June 17,2002  
   Input keywords:  
   all: if not set, one (1) mode is forced to be discarded (useful if regular  
   AO system using a DM with a piston component and condition number too  
   large). Normally, set all=1.  
   nomodalgain: if set, the modal gain are not taken into account.  
   disp: set to display stuff.  
   This routine uses:  
   - dm._def, _nact, _n1, _n2 (extern)  
   - ipupil (extern)  
   - mat.condition (extern)  
   - modalgain (extern)  
   - eigenvalues (extern)  
   - modToAct (extern)  
   - mesToMod (extern)  
       
   This routine calls:  
   - Nothing  
       
   This routine sets:  
   - NModesControlled (extern)  
   This routine returns:  
   - cMat  

             func compDmShape(nm,command)  
 
   compute the DM shape from the command vector  
   branch over _dmsum or _dmsumelt according to case.  

             func correctUpLinkTT(phase)  
 
       

              CurvWfs(pupil,phase,ns,disp=)  
 
   This function computes the signal from a Curvature WFS for a   
   given phase and pupil input and WFS config.  

 dm_struct  
 
struct dm_struct  
{  
  string  type;           // "bimorph", "stackarray" "tiptilt", "zernike", "aniso". Required [none]  
  long    subsystem;      // Subsystem this DM belongs to. Optional [1]  
  string  iffile;         // Influence function file name. Leave it alone.  
  float   alt;            // Conjugation altitude in meter. Specified @ zenith! Optional [0]  
  float   hyst;           // DM actuator hysteresis (0. to 1.). Optional [0]  
  float   push4imat;      // Voltage to apply for imat calibration. Optional [20].  
  // Note: the default is not OK for many configs. Change at will.  
  float   thresholdresp;  // Normalized response threshold for an act. to be valid. Optional [0.3]  
  float   unitpervolt;    // Influence function sensitivity in unit/volt. Optional [0.01]  
  // Stackarray: mic/volt, Tip-tilt: arcsec/volt.  
  float   maxvolt;        // Saturation voltage (- and +) in volt. Optional [none if not set]  
  float   gain;           // loop gain for this DM (total = this x loop.gain). Optional [1]  
  float   misreg(2);      // dm misregistration (pixels). optional [0,0]  
  // Bimorph-only keywords:  
  pointer nelperring;     // long vectorptr. # of elec. per ring, e.g &([6,12,18]). Required [none]  
  pointer angleoffset;    // float vectorptr. offset angle for first electrode in ring.  
  pointer rint;           // float vectorptr. if set, specify the inner radius for each ring  
  pointer rout;           // float vectorptr. if set, specify the outer radius for each ring  
  float   supportRadius;  // radius of support points, normalized in pupil radius  
  float   supportOffset;  // angle offset of first support points, in degree (default=90)  
  // Stackarray-only keywords:  
  long    nxact;          // # of act. in pupil diameter. Required [none]  
  long    pitch;          // Actuator pitch IN PIXEL. Required [none]  
  float   pitchMargin;    // margin to include more corner actuators when creating inf.functions  
  // optional [1.44]  
  float   coupling;       // coupling coef in influence function. optional [0.2].  
  // valid values from 0.04 to 0.30.  
  string  ecmatfile;      // valid to extrap. actuator matrix (extrap_com). Optional.  
  long    noextrap;       // set to 1 if no extrapolated actuators whatsoever are to be used [0]  
  long    elt;            // set to 1 if fast dmsum to be used  
  // Zernike-only keywords:  
  long    nzer;           // Number of modes, including piston. Required [none]  
  // Internal keywords:  
  float   _alt;           // Actual conjugation altitude in meter, from dm.alt and zen.  
  long    _nact;          // Internal. Tot # of actuators.  
  pointer _def;           // Internal: Pointer to IF data  
  pointer _x;             // Internal: x position of actuator in pixels  
  pointer _y;             // Internal: x position of actuator in pixels  
  pointer _i1;            //   
  pointer _j1;            //   
  pointer _ei1;           //   
  pointer _ej1;           //   
  string  _eiffile;       // Influence function file name for extrap. actuators  
  pointer _edef;          // Internal: Pointer to IF data for extrap. actuators  
  pointer _ex;            // Internal: x position of extrap. actuator in pixels  
  pointer _ey;            // Internal: x position of extrap. actuator in pixels  
  long    _enact;         // Internal. Tot # of extrap. actuators.  
  long    _n1;            // Internal: position of leftmost pixel in ao._size^2 array  
  long    _n2;            // Internal: position of leftmost pixel in ao._size^2 array  
  pointer _vold;          // internal: hysteresis  
  pointer _posold;        // internal: hysteresis  
  pointer _chpos;         // internal: hysteresis  
  pointer _chv;           // internal: hysteresis  
  pointer _dir;           // internal: hysteresis  
  pointer _delta;         // internal: hysteresis  
  pointer _command;       // pointer to command vector  
  pointer _extrapcmat;    // extrapolation matrix: extrap_com = extrapmat(,+)*valid_com(+)  
  int     _eltdefsize;    // size of def in case elt=1  
};  

 do_prompt  
 

             doInter(disp=)  
 
     
Measure the interaction matrix.  
Each actuator are set and a measurement vector is taken.  
The reference (for phase=0) is subtracted.  
Keyword disp: set to display stuff as it goes.  
This routine uses:  
- dm._nact, _n1, _n2, _def (extern)  
- mircube (extern)  
This routine calls:  
- multWfsIntMat  
This routine sets:  
- iMat (extern)  

             func getPhase2dFromDms(mircube, mir_sh)  
 
   adapted from the IDL function of the same name in tomoclose.pro  
   mircube(extern)	= cube or image of phase screen (mirrors)  
   first plan = first mirror shape  
   second plan = second mirror shape  
   etc...  
   should be of size _n*_n  
   mir_sh     = 2d vector of shift in number of pixels per screen  
   *_sh([x,y],screen#)  

             func getPhase2dFromOptics(nn,type)  
 
   adapted from the IDL function of the same name in tomoclose.pro  
   nn = wfs or GS #  
   type = "wfs" or "target"  

             getTurbPhaseInit(void)  
 
   Belongs to the yao package suite.  
   Initializes everything for getTurbPhase (see below), which  
   returns the interpolated, integrated phase to the loop function  
   for iteration number "iter". Returns the "ok" parameter which is  
   set to 0 if this step is not to be used to compute statistics.  
   AUTHOR: F.Rigaut, June 11, 2002.  

 gs_struct  
 
struct gs_struct  
{  
  float   zeropoint;      // Photometric zero point (#photons@pupil/s/full_aper, mag0 star).  
  // Required [none]  
  float   zenithangle;    // zenith angle. Optional [0.]. The zenith angle is used to compute:  
  // - r0 off-zenith  
  // - atmopheric turbulence layer altitude  
  // - LGS altitude and thickness of Na Layer  
  // - LGS brighness  
  // note that dm altitude is unchanged.  
  float  lgsreturnperwatt;// Sodium LGS return in photons/cm2/s at entrance pupil.  
  // Specified at zenith. Modified by gs.zenithangle. Optional [22.]  
  // basically, you have to fold in this the sodium density  
  // and your model of return.  
};  

 loop_struct  
 
struct loop_struct  
{  
  float   gain;            // Loop gain. Optional, but important! [0]  
  long    framedelay;      // # of frame delay ON TOP OF normal 1 frame delay. Optional [0]  
  long    niter;           // # of total iteration. Required [none]  
  float   ittime;          // Iteration time in seconds. Required [none]  
  long    startskip;       // # iter to skip before collecting statistics. Optional [10]  
  long    skipevery;       // skip by "skipby" every "skipevery" iterations. Optional [0=none]  
  long    skipby;          // see above. this is to get better statistical  
  long    stats_every;     // compute stats every so many iteration (default 4)  
  // coverage. Optional [10000]  
  long    jumps2swapscreen;//number of jumps (i.e. niter/skipevery) after which screens  
  //will be swapped (rotation, 2->1, 3->2... 1->last  
  string  modalgainfile;   // Name of file with mode gains. Optional.  
  //  float   dithering;      // TT dithering for centroid gain (volts).  
};  

 mat_struct  
 
struct mat_struct  
{  
  pointer condition;      // float vecorptr. Condition numbers for SVD, per subsystem. Required [none]  
  string  file;           // iMat and cMat filename. Leave it alone.  
};  

 opt_struct  
 
struct opt_struct  
{  
  string   phasemaps;      // filename of phasemap. Z scale should be in microns  
  float    alt;            // float. equivalent altitude in m.  
  float    misreg(2);      // float vector. misreg. (similar to DM, see below)  
  float    _cent;          // center of the phase maps arrays (similar to sim._cent)  
};  

             func prepSVD(imat,disp=)  
 
   Does the SVD decomposition and fill out modToAct  
   and mesToMod matrices for further use by buildComMat()  
   Keyword disp: set if display is required.  
   This routine uses:  
   - imat (input)  
   This routine calls:  
   - SVdec  
   This routine sets:  
   - eigenvalues (extern)  
   - modToAct (extern)  
   - mesToMod (extern)  

 sim_struct  
 
struct sim_struct  
{  
  string  name;           // A name for this simulation run. Optional [none]  
  long    pupildiam;      // Pupil diameter in pixels. Required [none]  
  long    debug;          // set the debug level (0:no debug, 1:some, 2: most). Optional [0]  
  long    verbose;        // set the verbose level (0:none, 1: some, 2: most). Optional [0]  
  // Internal keywords:  
  long    _size;          // Internal. Size of the arrays [pixels]  
  float   _cent;          // Internal. Pupil is centered on (_cent,_cent)  
};  

             func splitDMCommandVector(v)  
 
   splits the single vector (out of cMat matrix multiply in aoloop)  
   into as many individual command vector as there are DMs.  
   Return a pointer vector to the individual command vectors.  

             func splitWfsVector(v)  
 
   splits the single vector (out of multWfs or multWfsIntMat)  
   into as many individual wfs vector as there are sensors.  
   Return a pointer vector to the individual wfs vectors.  

             func swapScreens  
 
   Swap the phase screens. This is to get better statistics  
   out of fewer phase screens and iterations.  
   The 2nd phase screen becomes the 1rst one, 3->2, etc...  
   This routine uses the phase screens and normalization  
   factor stored in extern by getTurbPhaseInit  

 target_struct  
 
struct target_struct  
{  
  pointer lambda;         // float vectorptr. Image wavelengths in micron. Required [none]  
  pointer xposition;      // float vectorptr. X positions in arcsec. Required [none]  
  pointer yposition;      // float vectorptr. Y positions in arcsec. Required [none]  
  pointer dispzoom;       // float vectorptr. Display zoom (typically around 1.). Optional [1.]  
  // Internal keywords  
  long    _ntarget;       // Internal: # of target  
  long    _nlambda;       // Internal: # of lambda  
};  

 tel_struct  
 
struct tel_struct  
{  
  float   diam;           // Telescope diameter in meters. Required [none]  
  float   cobs;           // Central obstruction / telescope diameter ratio. Optional [0]  
};  

 wfs_struct  
 
struct wfs_struct  
{  
  string  type;           // WFS type: "curvature", "hartmann" or "pyramid". Required [none]  
  long    subsystem;      // Subsystem this WFS belongs to. Optional [1]  
  float   lambda;         // WFS wavelength in microns. Required [none]  
  long    noise;          // Enable noise (photon noise/read out noise). Optional [0=no].  
  float   ron;            // Read out noise in electrons. Optional [0]  
  float   darkcurrent;    // dark current in e-/sec/pixel or APD. Optional [0]  
  float   gspos(2);       // This WFS guide star position (x=0. Optional [0]  
  float   biasrmserror;   // rms error on WFS bias in electron. Optional [0]  
  float   flatrmserror;   // rms error on WFS flat, referenced to 1. Optional [0]  
  string  submask;        // fits file with subaperture amplitude mask. It should have  
                          // dimension 2^sdimpow2 square. can be float or long.  
  // Typical value can be 0.01  
  float   kernel;         // FWHM in arcsec of WFS gaussian kernel. Optional.  
  // Default is computed as a function of D/r0  
  int     nintegcycles;   // # of cycles/iterations over which to integrate. Optional [1]  
  float   fracIllum;      // fraction illuminated to be valid. Optional [0.5]  
  float   LLTxy(2);       // 2 element vector with (x,y) of laser projector [m]  
  long    centGainOpt;    // Centroid Gain optimization flag. only for LGS (correctupTT and   
  // filtertilt must be set). Optional [0]  
  int     rayleighflag;   // set to one to take rayleigh into account  
  // Internal keywords:  
  float   _gsalt;         // This WFS guide star altitude in meter. 0 for infinity.  
  float   _gsdepth;       // This WFS GS depth in meter (e.g. Na layer thickness).  
  int     _nsub;          // Internal. Tot # of subs.  
  long    _nmes;          // internal. Tot # of measurements.  
  pointer _sind;          // Internal: see CurvWFS  
  pointer _nsind;         // Internal: see CurvWFS  
  pointer _cxdef;         // Internal: see CurvWFS  
  pointer _sxdef;         // Internal: see CurvWFS  
  pointer _tiltsh;        // Internal: see ShWfs  
  pointer _masks;         // Internal: see ShWfs  
  pointer _fluxpersub;    // Internal: see ShWfs  
  pointer _raylfluxpersub;// Internal: see ShWfs  
  pointer _skyfluxpersub; // Internal: see ShWfs  
  float   _nphotons;      // Internal: see WFS routines  
  float   _skynphotons;   // Internal: see WFS routines  
  float   _tt(2);         // Internal: WFS measured Tip and tilt  
  float   _lastvalidtt(2);// Internal: WFS measured Tip and tilt  
  float   _upttcommand(2);// Internal:  
  pointer _refmes;        // internal: reference measurement vector  
  pointer _tiprefv;       // internal: tip reference meas. vector  
  pointer _tiltrefv;      // internal: tilt reference meas. vector  
  pointer _tiprefvn;      // internal: tip reference meas. vector. normalized (norm=1)  
  pointer _tiltrefvn;     // internal: tilt reference meas. vector. normalized.  
  pointer _istart;        //  
  pointer _jstart;        //  
  pointer _binindices;    //  
  int     _binxy;         //  
  pointer _centroidw;     //  
  pointer _fimage;        //  
  pointer _fimage2;       //  
  pointer _imistart;      //  
  pointer _imjstart;      //  
  int     _fimnx;         //  
  int     _fimny;         //  
  pointer _bias;          // internal: array of bias error  
  pointer _flat;          // internal: array of flat error  
  long    _domask;        // internal. flag to do submask calculations in _shwfs  
  pointer _submask;       // internal: array. subaperture amplitude mask.  
  pointer _kernel;        // internal: kernel for _shwfs. use: dointer or LGS uplink im.  
  pointer _kernels;       // internal: subaperture dependant image kernel  
  pointer _kerfftr;       // internal: storage of FFTs of kernels  
  pointer _kerffti;       // internal: storage of FFTs of kernels  
  int     _kernelconv;    // interal: convolve with kernel in _shwfs?  
  int     _cyclecounter;  // counter in integration sequence (see nintegcycles above)  
  pointer _dispimage;     // image to display (same as fimage except if nintegcycles!=1)  
  pointer _x;             // shwfs: X positions of subaperture centers  
  pointer _y;             // shwfs: Y positions of subaperture centers  
  float   _centroidgain;  // internal: centroid gain if dithering on  
  pointer _rayleigh;      // pointer to rayleigh images array for this sensor  
  pointer _bckgrdcalib;   // pointer to background array calibration  
  int     _bckgrdinit;    // set to one to fill calibration array  
  int     _bckgrdsub;     // set to one to subtract background (default)  
};  

 whereat