yao
Links
Main pageInstallation
Examples and Scripts
Performance
Data structures and parfiles
Controlling Features
Screenshots
Algorithms
Yao tk dynamic control
News/Weblog
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:
- System: Multi-WFS or multi-DM configuration
- WFS: Shack-Hartmann methods (gradient average vs full propagation)
- WFS: Separately adjust the integration time for each sensors
- WFS: Frame delay
- WFS: Centroid Gain Optimization (LGS+Shack-Hartmann only)
- DM: Separate loop gain per DM
- DM: Actuator validation threshold
- DM: Anisoplanatism modes for MCAO
- DM: Extrapolated actuators
- DM:Making things faster for large problems
- Performance:Multi-wavelength, multi-position performance estimate
- Performance:Skip and reset
- LGS: Use a Laser Guide Star
- LGS: Uplink compensation of a LGS tilt
- LGS: Laser Guide Star elongation
- LGS: Rayleigh Fratricide effect in multiple LGS systems
- Working off-zenith
- r0 versus fraction per layer
- 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 usingwfs().subsystem
anddm().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. - 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.
- 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 bywfs.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
- The clock time, i.e. quantum time for the simulation is set by
- Separate loop gain per DM
- Just set
dm.gain
. The total gain for DM n isdm(n).gain * loop.gain
. At version 3.0, only a simple integrator with gain is implemented.
- Just set
- 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 bymax(abs(iMat row for this actuator))/max(abs(iMat))
) is larger thandm.thresholdresp
.dm.thresholdresp=0
will of course select all actuators, whiledm.thresholdresp=1
will select none. Values of 0.3 to 0.5 are typical. Settingdm.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 ofdm.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 ofdm.thresholdresp
for this DM in the parfile.
- When configuring a DM, one may fine tune which actuators are
enabled with the parameter
- 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 exampletarget.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 thetarget.xposition
andyposition
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.
- 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
- 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 ;-)
- "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
andloop.skipby=10000
, combined withloop.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.
- 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 (
- 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 lasergs.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 aswfs.gsalt
(meters). See below for more details and options.
- 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
- 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 enlargesim.pupildiam
to get a larger field of view per subaperture. - If any of
wfs.gsdepth
orwfs.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).
- 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. - 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). - 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)
- set
- 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
anddm.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)
- 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
- 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
andwfs.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
andditherPeriod
). - 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
- the uplink fast steering mirror (the one used to re-center the
beam on the LGS WFS, operation enabled with
- Setting
- 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. - 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.)
thusf(i) = (r0tot/r0(i))^(5./3) inversely, we have: r0(i) = r0tot / f(i)^(3./5)
- More features to come in this help