yao

Examples, Startup, Tips & Scripts

A very simple but typical run of yao starts with your favorite text editor. First, you have to define the parameter file for your system. Start from one of the given examples (*.par in the example directory). Run it. Then go back to the file, and together with these web pages (in particular, have a look at the Data Structure and the Controlling features pages), try to figure out what all the variables mean and what they do. Next you can edit the parfiles and change them as you see fit.

The Basics

Is yorick installed ? All set up as per the installation instructions ? Then go to the example directory (~/yorick-1.15/contrib/yao/examples/ or ~/Yorick/examples/ if you already created it [recommended]) of the yao distribution and type:
% yorick
at the unix prompt. You get the welcome message and the yorick prompt:
frigaut:examples% yorick
 Copyright (c) 1996.  The Regents of the University of California.
 All rights reserved.  Yorick 1.6.01 ready.  For help type 'help'
> 
Every time you start yorick to run a yao session, you should include the package as follow:
> #include "yao/aosimul.i"
(don't type the ">", it's the yorick prompt). Make sure the package has been loaded by typing
> info,aoread
func aoread(parfile)
if you get this message, you are in business. If not, fix your yorick installation. In the future, you can avoid to type this include line by putting the same directive (#include "yao/aosimul.i") in a file named custom.i in a directory ~/Yorick. It is useful to create ~/Yorick in any case. This will be your yorick home, when you will write yorick routines (you will come to it :-). See an example of custom.i in ~/yorick-1.6/i/.

Notes on Yorick:

Before running a simulation, we need to create phase screens (if you are running yao on Linux, you will also need to initialize fftw_wisdom, see below on how to do that). These are not included in the yao distribution as they would x10 the download size. At the yorick prompt, type:

> CreatePhaseScreens,2048,256,prefix="screen"
This will create 8 2048x256 phase screens suitable for use by yao. Depending on your platform and CPU, it may take some time (1mn or so), as this routine is absolutely not optimized. This is a one shot run. You will not need to do that everytime you run yao, as you can, and are encouraged, to use the same phase screens. You may need to run it once more to create larger phase screens if the need arises, but that's about it.

Move these phase screens somewhere convenient. You will need to edit the yao parameter files to reflect the path and names of these phase screens (look for "atm.screen").

Next, we will try to run "sh6m2", which is a simple 6x6 Shack-Hartmann example. After you have edited the "sh6m2.par" file and modified the path and filename of the newly created phase screens, type:

> aoread,"sh6m2.par"
Aosimul, Version 2.4, 2004jan21
Checking parameters ... 
dm(1).iffile set to sh6m2-if1.fits
dm(2).iffile set to sh6m2-if2.fits
 OK
> aoinit,clean=1,disp=1
Checking parameters ... 
 OK
 WFS# |       Pixel sizes         | Subap. size | Number of pixels | #photons
      | Desired  Quantum  Actual  | Max  Actual | Desired   Actual | /sub/iter
 1      0.10000  0.03182  0.09547   1.02  0.95    10x10      10x10   70735.5
> 
At this point you have read the parameter file and initialized everything. The keyword clean indicates that you want to start from scratch, and ignore any influence function or interaction/command matrix files on your disk. The disp=1 is to initialize the displays. You are ready to run the loop.
> aoloop,disp=20
      /Short expo. image/Long expos. image/
 Iter#/Max.S/Min.S/Avg.S/Max.S/Min.S/Avg.S/Time Left
     1 0.000 0.000 0.000 0.000 0.000 0.000 Time left 00:00:00.0
    51 0.345 0.345 0.345 0.371 0.371 0.371 Time left 00:00:00.0
   101 0.371 0.371 0.371 0.391 0.391 0.391 Time left 00:00:-0.0
   [...]
   951 0.468 0.468 0.468 0.435 0.435 0.435 Time left 00:00:-0.0
Finished on 00:38:50
61.011659 iterations/second in average

         lambda  XPos  YPos  FWHM[mas]  Strehl  E50d[mas]  #modes comp.
Star# 1    1.65   0.0   0.0       44.5   0.434      207.8         27.5
Field Avg  1.65                   44.5   0.434      207.8
Field rms                          0.0   0.000        0.0
>
You have ran 1000 iterations. disp=20 in the call means "do your displays every 20 iterations". Depending on your graphic card, displays can be pretty expensive (time), thus it helps to display less frequently.

The resulting average images have been saved on disk ("sh6m2-imav.fits"), together with a small postscript file ("sh6m2.ps") that contains some graphics. Strehl, FWHM and 50 percent encircled energy are available as extern variables under the name strehl, fwhm and e50:

> strehl
[[0.434317]]
These variables contains the values for all the images (here there is only one, but there can be an arbitrary number of positions and wavelengths at which you want to estimate the performance). This can be useful in script, as detailled below.

Modelling your system

Now you can edit sh6m2.par (make a copy before that), or any other example file provided, and change it to your taste. Be extra careful to understand the significance of the parameters. Many of them have default value too (see the Data Structure page), so you may want to rely on defaults when in doubt. Read twice your modifications and be sure that the defined set up makes sense. Then go into yorick and repeat the above instructions with your new parameter file. In aoread(), some basic checks are done on the parameters. Nothing fancy, but it should grab the most obvious errors. You can also read the FAQ and frequent mistake page (to be written).

One level up is to run the ao routines inside a script. There are many reason to do that; if you want to scan a parameter space for best performance for instance. It is very easy to do that in yorick with yao if you have any experience with coding and scripting languages. I give a few examples below.

Script Examples

Example 1 Assume I want to find the best integration time/loop gain compromise for a 6x6 Shack-Hartmann for a guide star of magnitude 14. Here is a script to do this ("sh6m2-script1.i" in the yao example directory):
// file sh6m2-script1.i
// example script
// find the best integration time/loop gain compromise for a 6x6
// Shack-Hartmann as defined in "sh6m2.par" for magnitudeGS=14.
aoread,"sh6m2.par";
wfs(1).noise=1;
wfs(1).ron = 4.; // of course you could have put that in the parfile
wfs(1).shthreshold = 4.;
wfs(1).gsmag = 5.;
aoinit,disp=1,clean=1;
wfs(1).gsmag = 13.;
ncycles = [1,2,3,5,10];
gainvect=[0.1,0.2,0.4,0.8];
strehlmap = array(float,[2,numberof(ncycles),numberof(gainvect)]);
for (i=1;i<=numberof(ncycles);i++) {
  for (j=1;j<=numberof(gainvect);j++) {
    wfs(1).nintegcycles = ncycles(i);
    loop.gain = gainvect(j);
    write,format="\nAOLOOP for ncycles=%d and loopgain=%f\n",wfs(1).nintegcycles,loop.gain;
    aoloop,disp=10;
    strehlmap(i,j) = max(strehl); 
  }
}
w = where2(strehlmap == max(strehlmap));
write,format="Best Strehl = %f for integration time = %.0f ms and gain=%f\n",\
  max(strehlmap),loop.ittime*ncycles(w(1))*1e3,gainvect(w(2));

This is to be executed from the command line:
> #include "sh6m2-script1.i"
[... lots of things printed on the screen as we go through the many aoloop()...]
Best Strehl = 0.161815 for integration time = 2 ms and gain=0.400000
Other examples can include:

Variables (aoinit or not aoinit?)

A useful thing to know is what variables can be modified where, or more precisely, what do you need to (re)run for the change to be effective. For instance, it is obvious that changing the inversion condition number once the inversion is done is going to have very little effect. Many of the variables used into aoloop() are initialized beforehand in aoinit() (hence the name), and changing them after aoinit() will have no effect.

In many cases, and in scripts in particular one will want to loop on a variable (e.g. determine the performance for various GS magnitude and loop gain), and it can be annoying and time consuming to restart from aoinit() before each aoloop() run. The following list states at which level a variable can be changed and still be taken into account in aoloop().

The syntax in this list is to be understood as "If you change this variable, you have to take this action for the variable to be taken into account in a new aoloop() run".

Page updated on UT $Date: 2007/12/12 23:29:28 $

Valid CSS!