yao

Controlling Features

This page is under construction.

OK. You have installed yao and now, you would like to do stuff with it, but you have edited the parfile and don't really know where to start from. This is a guide to feature control, where I go through what parameter to modify to get the desired effect.

I do not go through the obvious though. Selecting curvature vs shack-hartmann sensor, etc, etc...but only addressed the little more advanced features. You can go back to the Data Structure page for explanation about particular parameters. Again, one of the best way to start is from one of the parfiles you will find in the example directory in the yao distribution.

Content:


  1. Multi-WFS or multi-DM configuration: Set nwfs or ndm in the parfile to the desired number of WFSs/DMs. Edit the variables accordingly (e.g. wfs(2).type). See mcao2-bench.par for an example of this. You might group the DMs/WFSs in subsystem by using wfs().subsystem and dm().subsystem (set this to a number: 1, 2, ...). The interaction matrix for each subsystem is inverted separately, and then re-stuffed into a global command matrix.
  2. Shack-Hartmann methods:
    • wfs.shmethod = 1 for the fast gradient average option. Noise is always disabled with this option which is to be used only for fast evaluation.
    • wfs.shmethod = 2 for the full propagation option. Images are calculated for each lenslets, and noise, bias, flat and threshold are applied.
  3. Separately adjust the integration time for each sensors:
    • The clock time, i.e. quantum time for the simulation is set by loop.ittime. Each sensors can integrate over an integer number of this quantum time, set by wfs.nintegcycles. Note that this option only works with Shack-Hartmann sensors (curvature sensors are mostly photon noise limited, and although there are now consideration to implement curvature sensors with CCD, on a single WFS system, you can adjust loop.ittime).
    • wfs.nintegcycles = 3 will result in an integration time of 3 x loop.ittime
  4. Separate loop gain per DM
    • Just set dm.gain. The total gain for DM n is dm(n).gain * loop.gain. At version 3.0, only a simple integrator with gain is implemented.
  5. Actuator validation threshold
    • When configuring a DM, one may fine tune which actuators are enabled with the parameter dm.thresholdresp. The interaction matrix is done with a larger number of actuators. It is then examined and only actuators for which the WFS response (as defined by max(abs(iMat row for this actuator))/max(abs(iMat))) is larger than dm.thresholdresp.
      dm.thresholdresp=0 will of course select all actuators, while dm.thresholdresp=1 will select none. Values of 0.3 to 0.5 are typical. Setting dm.thresholdresp to negative value will enter an interactive mode at execution: When the time comes to select valid actuators (after taking the iMat), the user is prompted for a value of dm.thresholdresp, and can enter successively new values until satisfied with the result (a graphical configuration of the beams + valid actuator is plotted to help the selection). When you've gone through this step once, I suggest you enter the final value of dm.thresholdresp for this DM in the parfile.
  6. Multi-wavelength, multi-position performance estimate
    • Starting at version 2.3.0, one can now, in the same simulation run, evaluate the performance images at various wavelengths. This has to be specified using target.lambda as a pointer to a wavelength vector, for example target.lambda = &([1.25,1.65,2.2]). The result Strehl and fwhm array, accessible as extern variable once the simulation is finished, are 4-dimensions: (row,column,position, wavelength), where position is the (X,Y) position in the field of view, as specified in the target.xposition and yposition vectors. Because in most case the computation time is not dominated by the PSF estimation, but by the WFS or DM shape computation functions, performance evaluation at multi-positions/multi-wavelengths makes sense.
  7. Frame delay
    • loop.framedelay controls the integer number of frame delay in the close loop, on top of a fixed 1 frame delay due to the nature of the close loop. loop.framedelay=0 means no delay, i.e. the WFS measurement are available for the DM command calculation as soon as the integration on the WFS is finished. This is appropriate for curvature sensors using APDs and very fast real time computer. loop.framedelay=1 is appropriate for Shack-Hartmann sensor (using CCD with usually a frame read out time) and fast real time computers. Larger values can be chosen. You can NOT use negative values ;-)
  8. "Skip and reset" feature

    • By definition, the low spatial frequencies of the wavefront have much larger temporal correlation time than the high spatial frequencies. This is a direct consequence of the Taylor hypothesis of frozen turbulence. thus obtaining good statistics, including on these low spatial frequencies, may result in the need for very large number of iterations in the Monte-Carlo code (aoloop). To circumvent this, I have implemented a feature that runs a number of iterations, then skips a large step and restart at a totally new place (in fact, much later, as if you had skipped thousand of iterations). Providing you are running a sufficient number of screens and these are large enough, this usually works well and provide much smoother resulting PSF and less biased performance estimates.
    • set loop.skipevery to the number of iteration you want to run in a row (continuous).
    • set loop.skipby to the equivalent number of iteration you want to jump in between the continuous run. In short, you want to skyp by "skipby" iterations every "skipevery" iterations. To be perfectly clear, loop.skipevery=100 and loop.skipby=10000, combined with loop.niter=1000, will run 100 iterations, then skip by 10000 iterations (i.e. move the phase screens as if 10000 iterations had passed by), then reset and run another 100 iterations, then skip another 10000, reset and run another 100, until the number of actually executed iteration reaches 1000.
  9. LGS: Use a Laser Guide Star: To set a WFS to use a LGS, set
    • wfs.gsalt to the altitude of the LGS (e.g. 90000 for Na star). Specified at zenith.
    • wfs.laserpower to the power of the laser
    • gs.lgsreturnperwatt to the number of photons received back at the entrance pupil, per cm2, per second, per Watt of laser power on sky, at zenith. The default value is 22, which seems to be in good agreement with theory and measurements (e.g. SOR 2004) for a Sodium LGS.
    • wfs.filtertilt=1: I do not explicitly add the correct uplink tilt to the LGS position. This insures you will not use it unduly.
    • It is advised to use uplink tip-tilt compensation (see below)
    • You may want to use wfs.gsdepth to simulate guide star elongation. gsdepth specifies the depth of the laser guide star, thickness of the sodium layer or range gating for a Rayleigh guide star, in the same units as wfs.gsalt (meters). See below for more details and options.
  10. LGS: Uplink compensation of a LGS tilt: On top of the LGS settings, set
    • wfs.correctUpTT=1
    • wfs.uplinkgain=0.1 or some other value. That is the integrator gain of the control loop steering the uplink LGS tip-tilt mirrors, controlled by the TT signal of the WFS looking at this LGS
  11. LGS: Laser Guide Star elongation
    • For SH WFS only.
    • Starting in version 2.5.0, I have implemented a way to simulate the LGS geometrical off-axis elongation. Just set wfs.gsdepth to the thickness of the sodium layer (or rayleigh depth), in meters. For a sodium LGS system, wfs.gsdepth = 10000 is appropriate.
    • Because the uplink propagation is not yet implemented, one may want to set wfs.kernel(in arcsec) to the value of the spot size, typically 0.8-1.0" to reflect real world conditions (this is then convolved with the seeing and the spot elongation).Because of this, you might have to enlarge sim.pupildiam to get a larger field of view per subaperture.
    • If any of wfs.gsdepth or wfs.kernel is set, the shwfs code then switches into a special section that does the convolution. This adds a noticable overhead to the calculations (it about doubles the shwfs execution time), but is unavoidable for a complete LGS simulation.
    • wfs.LLTxy is an optional parameter that specifies the position of the Laser Launch Telescope (LLT) with respect to the telescope pupil center. wfs.LLTxy=(0,0) means the LLT is centered (e.g. behind the secondary, which is the Gemini MCAO configuration). wfs.LLTxy=(+5,0) means a projection from the side on a large telescope (this example is close to the Keck configuration).
  12. LGS: Rayleigh Fratricide effect in multiple LGS systems:

    To enable this calculation, or simply to enable the evaluation of the Rayleigh backscatter in a single LGS system with very large subapertures, set wfs.rayleighflag=1. During aoinit, yao will compute the backscatter maps for each relevant WFS/beam and subapertures. This takes some time, from a few seconds to a few minutes, depending on the order of the system and your computer's power. This Rayleigh contribution has to be re-calculated for different geometry of the system, i.e. LGS altitude and zenith angle.

  13. Working off-zenith:

    Just set gs.zenithangle to the zenith angle value in degree. ao.init needs to be re-run. This adjusts the value of r0, the lgs altitude and brightness, the atmospheric layer altitude and the thickness of the Na layer (or Rayleigh depth).

  14. Anisoplanatism modes for MCAO:
    • set dm.type="aniso"
    • set dm.alt to the altitude of an existing high order DM (i.e. not a tip-tilt mirror) capable of producing acceptable defocus and astigmatism. There has to be both a DM at altitude 0 and a DM at altitude *not* 0: What the algorithm does is find the actuator commands combination to apply to DM0 (0 altitude DM)
  15. Extrapolated actuators
    • Version 2.5.2 started to implement a (crude) ability to use extrapolated actuators. It goes as follow: First, a set of influence functions is generated (for each DM, of course). The geometry for this set of actuators is defined by the parameters dm.nxact, dm.pitch and dm.pitchMargin. This last parameters was added with version 2.5.2 and represents the extra radius -in pitch units- over which actuators have to be considered actives (i.e. an influence function is computed). dm.pitchMargin=0 will results in every actuator within (nxact-1)/2 from the pupil center to be generated, and nothing else. Usually, one would prefer to include slightly more actuators, and personally I use pitchMargin = 0.5 to 1.2 depending on the DM geometry.
    • The whole actuator set is then used to measured the iMat. The actuator retained as valid will go as valid, meaning actively controlled. The rest will be used as extrapolated actuators, and are controlled from the valid one using an extrapolation matrix.
    • Extrapolation is ON by default. If you want to desactivate it, set dm.noextrap=1.
    • Right now, I use a very crude method to compute the extrapolation. Basically, a simple linear weighting of the closest valid actuators, with weight computed as exp(-distance^2). A parameter is provided for those of you who want finer control. Set dm.ecmatfile to a string that contains the filename of the valid-to-extrapolated conversion matrix. The dimension of ecmat are (number of extrapolated actuators, number of valid actuators)
  16. Centroid Gain Optimization (LGS+Shack-Hartmann only)
    • Setting wfs.centGainOpt=1 will enable centroid gain optimization. This only works for LGS Shack-Hartmann WFS . The method used is as follow:
      • the uplink fast steering mirror (the one used to re-center the beam on the LGS WFS, operation enabled with wfs.filtertilt=1, wfs.correctuptt=1 and wfs.uplinkgain=x, 0A lockin detection is performed on the TT signal detected by this sensor, with the same period.
      • Thanks to the properties of the lock in detection, the resulting measured TT essentially contains only the dithered motion. The idea is that if the measured amplitude is lower than the induced amplitude, the centroid gain is too low. If it is larger, the centroid gain is too large. A low gain loop is implemented within the main AO loop to adjust the centroid gain accordingly. Right now, amplitude and period are hardcoded (but you can either change them using yaotk or edit the code; look for ditherAmp and ditherPeriod).
  17. Work with ELTs: by setting dm.elt=1, one enables several features aimed at reducing the CPU and RAM requirements when simulating very large systems (well, from 50x50 up). For now, what this does is just compute, use and save the influence functions on smaller arrays (the part of the phase map which is non zero). In the very near future, it is very probable that this will make use of Ralf's Sparse Matrix Package SSMP, and store/use not only the influence functions, but also the interaction and control matrices in sparse form.
  18. Relating r0 per layer and "fraction" per layer: Say your input data are in r0 per layer. How do you related this to the yao definition of "fraction" per layer? If you look in the code (getTurbPhaseInit in aosimul.i) you can come up with relationships between the fraction per layer and r0 per layer:
    r0(i)   = r0 of layer i
    r0tot   = total r0
    f(i)    = "fraction" in layer i ( = (*atm.layerfrac)(i) )
    
    We have:
    weight(i) = sqrt(f(i)) * (D/r0tot)^(5/6.) = (D/r0(i))^(5/6.)
    
    thus
    f(i) = (r0tot/r0(i))^(5./3)
    
    inversely, we have:
    r0(i) = r0tot / f(i)^(3./5)
    
  19. More features to come in this help
Page updated on UT $Date: 2007/12/12 23:29:21 $

Valid CSS!