1.1 Scope

AO loop control package. Includes high-performance CPU/GPU computation engine and higher level scripts.

1.2 Pre-requisites

Libraries required :

• gcc
• openMP
• fitsio
• fftw (single and double precision)
• gsl
• readline
• tmux
• bash dialog, version 1.2 minimum

Recommended:

• CUDA
• Magma
• shared memory image viewer (shmimview or similar)

1.3 Installing the AdaptiveOpticsControl package

Source code is available on the AdaptiveOpticsControl git hub repository.

Download the latest tar ball (.tar.gz file), uncompress, untar and execute in the source directory (./AdaptiveOpticsControl-<version>/)

./configure

Include recommended high performance compile flags for faster execution speed:

./configure CFLAGS='-Ofast -march=native'

If you have installed CUDA and MAGMA libraries:

./configure CFLAGS='-Ofast -march=native' --enable-cuda --enable-magma

The executable is built with:

make
make install

The executable is ./AdaptiveOpticsControl-<version>/bin/AdaptiveOpticsControl

Add <srcdir>/scripts to PATH environment variable. This is best done in the .bashrc file.

1.4 Setting up the work directory

Conventions:

• <srcdir> is the source code directory, usually .../AdaptiveOpticsControl-<version>
• <workdir> is the work directory where the program and scripts will be executed. Note that the full path should end with .../AOloop<#> where <#> ranges from 0 to 9. For example, AOloop2.

The work directory is where all scripts and high level commands should be run from. You will first need to create the work directory and then load scripts from the source directory to the work directory.

First, execute from the source directory the 'syncscript -e' command to export key install scripts:

mkdir /<workdir>
cd <srcdir>/src/AOloopControl/scripts
./syncscripts -e /<workdir>

The 'syncscript' script should now be in the work directory. Execute it to copy all scripts to the work directory:

cd /<workdir>
./syncscripts

Symbolic links to the source scripts and executable are now installed in the work directory (exact links / directories may vary) :

olivier@ubuntu:/data/AOloopControl/AOloopTest$ ls -l
total 32
drwxrwxr-x 2 olivier olivier 4096 Sep 29 19:27 aocscripts
drwxrwxr-x 2 olivier olivier 4096 Sep 29 19:27 aohardsim
lrwxrwxrwx 1 olivier olivier   57 Sep 29 19:27 aolconf -> /home/olivier/src/Cfits/src/AOloopControl/scripts/aolconf
drwxrwxr-x 2 olivier olivier 4096 Sep 29 19:27 aolconfscripts
drwxrwxr-x 2 olivier olivier 4096 Sep 29 19:27 aolfuncs
lrwxrwxrwx 1 olivier olivier   70 Sep 29 19:26 AOloopControl -> /home/olivier/src/Cfits/src/AOloopControl/scripts/../../../bin/cfitsTK
drwxrwxr-x 2 olivier olivier 4096 Sep 29 19:27 aosetup
drwxrwxr-x 2 olivier olivier 4096 Sep 29 19:27 auxscripts
lrwxrwxrwx 1 olivier olivier   61 Sep 29 19:26 syncscripts -> /home/olivier/src/Cfits/src/AOloopControl/scripts/syncscripts

If new scripts are added in the source directory, running ./syncscripts again from the work directory will add them to the work directory.

2.1 High-level GUI

The top level script is aolconf. Run it with -h option for a quick help

./aolconf -h

The aolconf script starts the main GUI screen from which sub-screens can be accessed. ASCII control GUI scripts are in the aolconfscripts directory.

The scripts are listed below in the order they appear in the GUI menu. Boldface scripts corresponds to GUI screens. Supporting scripts (holding frequently used functions) are boldface italic.

2.2 Supporting Scripts

Scripts are organized in directories according to their purpose

The auxscripts directory are called by aolconf to perform various tasks. To list all commands, type in the auxscripts directory :

./listcommands

For each script, the -h option will print help.

2.3 Main executable

The main precompiled executable is ./AOloopControl, which provides a command line interface (CLI) to all compiled code. Type AOloopControl -h for help. You can enter the CLI and list the available libraries (also called modules) that are linked to the CLI. You can also list the functions available within each module (m? <module.c>) and help for each function (cmd? <functionname>). Type help within the CLI for additional directions, and exit or exitCLI to exit the command line.

olivier@ubuntu:/data/AOloopControl/AOloop1$ ./AOloopControl 
type "help" for instructions
Running with openMP, max threads = 8  (defined by environment variable OMP_NUM_THREADS)
LOADED: 21 modules, 269 commands
./AOloopControl > exitCLI
Closing PID 5291 (prompt process)

2.4 Memory storage and Configuration Parameters

AOCCE adopts a common shared memory data format for all data streams. The data structure is defined in file <srcdir>/src/ImageStruct.h.

Configurations parameters are stored in directory <workdir>/conf as ASCII files. When AOCCEE is launched, it can load all required parameters and populate required shared memory streams from information contained in the <workdir>/conf directory.

3.1 Overview

There are 3 methods for users to simulate hardware

• METHOD 1: Provide an external simulation that adheres to AOloopControl input/output conventions

• METHOD 2: Use the physical hardware simulation provided by the package

• METHOD 3: Use the linear hardware simulation: this option is fastest, but only captures linear relationships between DM actuators and WFS signals

3.2 METHOD 1: Provide an external simulation that adheres to AOloopControl input/output conventions

The user runs a loop that updates the wavefront sensor image when the DM input changes. Both the DM and WFS are represented as shared memory image streams. When a new DM shape is written, the DM stream semaphores are posted by the user, triggering the WFS image computation. When the WFS image is computed, its semaphores are posted.

3.3 METHOD 2: Physical hardware simulation

The AOsim simulation architecture relies on individual processes that simulate subsystems. Each process is launched by a bash script. ASCII configuration files are read by each process. Data I/O can be done with low latency using shared memory and semaphores: a process operation (for example, the wavefront sensor process computing WFS signals) is typically triggered by a semaphore contained in the shared memory wavefront stream. A low-speed file system based alternative to shared memory and semaphores is also provided.

Method 2 simulates incoming atmospheric WFs, a pyramid WFS based loop feeding a DM, a coronagraphic LOWFS and coronagraphic PSFs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

# ======== AO simulation : creating atmospheric wavefronts stream =================
# script relies on pre-computed physical atmospheric wavefronts


MODE             0                # 0: read pre-computed WFs, 1: empty WFs
WFDIR            ./atmwf          # atmospheric wavefronts directory

LAMBDANM         1650             # wavelength [nm]

# ============== OUTPUT TYPE (OPD unit = um) ====================
OUT0FITSFILE         0                 # 0: none, 1 if FITS file output OPD only, 2 if OPD+AMP
OUT0FITSFILENAMEOPD  wf0opd.fits       # FITS file name output (OPD)
OUT0FITSFILENAMEAMP  wf0amp.fits       # FITS file name output (AMP)
OUTPHYSTIME          aosim_phystime    # physical time [s]
OUT0STREAM           2                 # 1 if shared memory stream OPD only, 2 if OPD+AMP 
OUT0STREAMNAMEOPD    wf0opd            # output WF stream name (OPD)
OUT0STREAMNAMEAMP    wf0amp            # output WF stream name (AMP)

# ============== PROCESS TRIGGER ==================================
TRIGGERMODE           2                # 0: file, 1: semaphore from stream, 2: time interval
TRIGGERFILE           wfup.txt         # update file name (TRIGGERMODE=0,1
TRIGGERDT             0.01             # update interval (TRIGGERMODE=0,2)
TRIGGER0STREAM        WFSinst          # trigger stream
TRIGGER0SEM           5                # trigger semaphore in TRIGGERSTREAM
TRIGGER1STREAM        dm05dispmap      # trigger stream
TRIGGER1SEM           5                # trigger semaphore in TRIGGERSTREAM

# ============== PARAMETERS ======================================
DT                    0.0000625        # time interval between computed wavefronts
OPDMFACT              1.0              # OPD multiplicative factor
AMPMFACT              1.0              # AMP multiplicative factor
ARRAYSIZE             128              # output size [pix]
PIXSCALEMODE          2                # 0: adopt input WF pixel scale, 1: custom pixel scale, 2: bin
PIXSCALECUSTOM        0.1              # custom pixel size
PIXBINFACTOR          4                # bin factor
PUPDIAMM              8                # Pupil diameter [m]

# ============== POST-PROCESSING =============================
DM0MODE               1                # 0 if no DM0, 1 if OPD DMn
DM0NAME               dm05dispmap      # DM displacement map stream
OUT1FITSFILENAMEOPD   wf1opd.fits      # FITS file name output (OPD)
OUT1FITSFILENAMEAMP   wf1amp.fits      # FITS file name output (AMP)
OUT1STREAM            1                # 1 if shared memory stream OPD only, 2 if OPD+AMP 
OUT1STREAMNAMEOPD     wf1opd           # output WF stream name (OPD)
OUT1STREAMNAMEAMP     wf1amp           # output WF stream name (AMP)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# ============== AOsim: DM process =============================
# DM process is triggered by WF OPD, not by DM command

# ============== INPUT & TRIGGER (OPD unit = um) ===============
INMODE                   0                 # 0:stream, 1:file system (FITS)
INSTREAMNAMEDM           dm05disp          # input DM command stream
INFITSFILENAMEDM         dm05disp.fits     # input FITS file name (DM command)
INTRIGSTREAMNAME         wf1opd            # input trigger stream
INTRIGSEMCHAN            6                 # input semaphore channel (using OPD input)
INTRIGGERFILE            inwf.txt          # input trigger file

# ============== OUTPUT TYPE ===================================
OUTMODE                  0                 # 0: stream, 1: file system
OUTSTREAMNAMEDM          dm05dispmap       # output WF stream name 
OUTFITSFILENAMEDM        dm05dispmap.fits  # FITS file name output [um]
OUTTRIGGERFILE           outdm.txt         # output trigger file

# ============== GEOMETRY, TIME =============================
ARRAYSIZE                128               # array size, pix
DMRAD                    52                # DM radius on array
DMDT                     0.0003            # DM time sampling
NBTSAMPLES               100               # number of time samples
DMLAGSTART               0.0003            # time lag start
DMTIMECST                0.0001            # DM time constant

3.3.4 AO loop control

The aolconf script is used to configure and launch the AO control loop. It can be configured with input/output from real hardware or a simulation of real hardware.

3.3.4.1 Shared memory streams

Script	Description
wf0opd	Wavefront OPD prior to wavefront correction [um]
wf1opd	Wavefront OPD after correction [um] ( = wf0opd - 2 x dm05dispmap )
dm05disp	DM actuators positions
dm05dispmap	DM OPD map
WFSinst	Instantaneous WFS intensity
pWFSint	WFS intensity frame, time averaged to WFS frame rate and sampled to WFS camera pixels

3.3.4.2 Hardware simulation architecture

data flow

Close-loop simulation requires the following scripts to be launched to simulate the hardware, in the following order :

• aosimDMstart: This script creates DM channels (uses dm index 5 for simulation). Shared memory arrays dm05disp00 to dm05disp11 are created, along with the total displacement dm05disp. Also creates the wf1opd shared memory stream which is needed by aosimDMrun and will be updated by runWF. wf1opd is the master clock for the whole simulation, as it triggers DM shape computation and WFS image computation.
• aosimDMrun: Simulates physical deformable mirror (DM)
• aosimmkWF: Creates atmospheric wavefronts
• aosimWFS: Simulates WFS

Some key script variables need to coordinated between scripts. The following WF array size should match :

• WFsize in script aosimDMstart
• ARRAYSIZE in aosimmkWF.conf
• ARRAYSIZE in aosimDMrun.conf

The main hardware loop is between aosimmkWF and aosimWFS: computation of a wavefront by aosimmkWF is triggered by completion of a WFS instantaneous image computation by aosimWFS. The configuration files are configured for this link.

3.3.4.3 DM temporal response

The DM temporal response is assumed to be such that the distance between the current position \(p\) and desired displacement \(c\) values is multiplided by coefficient \(a<1\) at each time step \(dt\). The corresponding step response is :

\(c - p((k+1) dt) = (c - p(k dt)) a\)

\(c - p(k dt) = (c-p0) a^k\)

\(p(k dt) = 1-a^k\)

The corresponding time constant is

\(a^{\frac{t0}{dt}} = 0.5\)

\(\frac{t0}{dt} ln(a) = ln(0.5)\)

\(ln(a) = ln(0.5) dt/t0\)

\(a = 0.5^{\frac{dt}{t0}}\)

3.3.5 Processes and scripts: system ouput

The output (corrected) wavefront is processed to compute ouput focal plane images, and optionally LOWFS image.

3.3.5.1 Process aosimcoroLOWFS

Computes coronagraphic image output and LOWFS image

File aosimcoroLOWFS.conf.default:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35

# ============== AOsim: coro LOWFS process ============================= # LOWFS process is triggered by WF OPD # ============== INPUT & TRIGGER (OPD unit = um) =============== INMODE 0 # 0:stream, 1:file system (FITS) INAMPSTREAMNAME wf1amp # input AMP stream INOPDSTREAMNAME wf1opd # input OPD stream INAMPFITSFILENAME wf1amp.fits # input FITS file name INOPDFITSFILENAME wf1opd.fits # input FITS file name INTRIGSTREAMNAME wf1opd # input trigger stream INTRIGSEMCHAN 4 # input semaphore channel (using OPD input) INTRIGGERFILE inwf.txt # input trigger file INPHYSTIME aosim_phystime # physical time # ============== OUTPUT TYPE =================================== OUTMODE 0 # 0: stream, 1: file system OUTLOWFSARRAYSIZE 16 # output LOWFS array size, pix OUTLOWFSSTREAMNAME aosim_imcamLOWFS # output WF stream name OUTLOWFSFITSFILENAME aosim_imcamLOWFS.fits # FITS file name output [um] OUTTRIGGERFILE outLOWFS.txt # output trigger file # ============== GEOMETRY, OPTICAL DESIGN ============================= LAMBDAum 1.65 # wavelength [um] ARRAYSIZE 256 # array size, pix, used for internal computations COROFPMAMP corofpmamp # coronagraph focal plane mask amplitude COROFPMPHA corofpmpha # coronagraph focal plane mask amplitude LYOTSTOPREFLAMP lyotstopreflamp # LYOT stop reflectivity map (amp) LYOTSTOPREFLPHA lyotstopreflpha # LYOT stop reflectivity map (pha) LYOTSTOPTRANSMAMP lyotstoptransmamp # LYOT stop transmission map (amp) LYOTSTOPTRANSMPHA lyotstoptransmpha # LYOT stop transmission map (pha) # ============== LOWFS ============================= LOWFSOPDMAP lowfsopdmap # LOWFS defocus map [um] LOWFSCAMETIME 0.01 # LOWFS camera exposure time [s]

3.3.5.2 Ouput simulation architecture

coroLOWFS data flow

3.4 METHOD 3: Linear Hardware Simulation

mkdir LHScalib

./aolconf -L 5 -N simLHS

4.1 GUI description

The script aolconf starts the main GUI, from which all setup and control can be done. The GUI consists of several main screens, as shown below.

aolconf GUI screens

4.2 Commands log

ALL commands are logged by the script :

./aolconfscripts/aollog

tail -f aolconf.log

# internal log - logs EVERYTHING
function aoconflog {
./aolconfscripts/aollog "$LOOPNAME" "$@"
}

./aollogext <string>

# external log, use for less verbose log
function aoconflogext {
./aolconfscripts/aollog -e "$LOOPNAME" "$@"
}

./aolconfscripts/aollog -i <LOOPNAME> NULL

./aolconfscripts/aollog -ie MISC NULL

tail -f logdit/<UTDATE>/logging/MISC.log

5.1 Top level script

Start aolconf with loop number and loop name (you can ommit these arguments when launching the script again):

./aolconf -L 3 -N testsim

The loop name (testsim in the above example) will both allocate a name for the loop and execute an optional custom setup script. The software package comes with a few such pre-made custom scripts for specific systems / examples. When the -N option is specified, the custom setup script ./setup/setup_<name> is ran. The script may make some of the steps described below optional.

You can check the current loop number and name settings with:

./aolconf -h

The script can also launch a pre-written CPU/OS configuration script named ./aocscripts/cpuconfig_<LOOPNAME> :

./aolconf -C

5.2 Setting the DM interface

There are four options for setting up the DM:

• [A] Connect to an existing DM

• [B] Create a new DM and connect to it

• [C] Create a new modal DM, mapped to an existing DM using another loop's control modes

• [D] Create a new modal DM, mapped to an existing DM channel using a custom set of modes

Before choosing an option, select if the DM to be controlled is MODAL or ZONAL. A zonal DM is one where the DM pixel locations map to physical actuator locations on the DM, allowing spatial filtering when creating control modes. With a zonal DM, each pixel of the DM map corresponds to a wavefront control mode, and spatial filtering functions are turned off.

Options [C] and [D] are MODAL options, as the DM does not represent physical spatial actuators. These options build a virtual DM which controls another DM.

5.3 Setting the camera interface

• link to WFS camera (wfs to Loop Configuration screen). Select the WFS shared memory stream.

5.4 Setup script

An aosetup script may be used to perform all these operations. Inspect the content of directory aosetup to see such scripts. You may use or modify as needed. If you use a aosetup script, execute it from the working directory, and then start aolconf:

./aosetup/aosetup_<myLoop>
./aolconf

6.1 Acquiring a zonal response matrix

• set response matrix parameters in Loop Configure screen: amplitude, time delay, frame averaging, excluded frames

• set normalization and Hadmard modes in Loop Configure screen. Normalization should probably be set to 1.

• start zonal response matrix acquisition (zrespon in Loop Configure screen). The process runs in tmux session aol#zrepM.

• stop zonal response matrix acquistion (zrespoff in Loop Configure screen).

The following files are then created:

Note that at this point, the files are NOT loaded in shared memory, but the archieved file names are stored in the staging area "conf_zrm_staged/conf_streamname.txt" for future loading.

• Adopt staged configuration (upzrm in Loop Configure screen)

• Load zrespm files into shared memory (SMloadzrm in Loop Configure screen)

6.2 Acquiring a modal response matrix (optional, for ZONAL DM only)

In addition to the zonal response matrix, a modal response matrix can be acquired to improve sensitivity to low-oder modes.

To do so:

• activate RMMon to toggle the modal RM on.

• select RM amplitude and maximum cycles per aperture (CPA)

• start the acquisiton (LOresp_on)

• stop the acquisiton (LOresp_off)

The following files are then created:

Note that at this point, the files are NOT loaded in shared memory, but the archieved file names are stored in the staging area "conf_mrm_staged//conf_streamname.txt" for future loading.

• Adopt staged configuration (upmrm in Loop Configure screen)

• Load LOrespm files into shared memory (SMloadmrm in Loop Configure screen)

6.3 Automatic system calibration (recommended)

The automatic system calibration performs all steps listed above under zonal and modal response matrix acquisition.

The old calibrations are archived as follows:

• "conf_zrm_staged" and "conf_mrm_staged" hold the new configuration (zonal and modal respectively)

• "conf_zrm_staged.000" and "conf_mrm_staged.000" hold the previous configuration (previously "conf_zrm_staged" and "conf_mrm_staged")

• "conf_zrm_staged.001" and "conf_mrm_staged.001" hold the configuration previously named "conf_zrm_staged.000" and "conf_mrm_staged.000"

• etc for a total of 20 configuration

6.4 Managing configurations

At any given time, the current configuration (including control matrices if they have been computed) can be saved using the SAVE CURRENT SYSTEM CALIBRATION command. Saving a configuration will save all files in the conf directory into a user-specified directory.

Previously saved configurations can be loaded with the LOAD SAVED SYSTEM CALIBRATION command. This will load saved files into the conf directory and load all files into shared memory.

9.1 Extract WFS modes

Launches script ./auxscripts/modesextractwfs :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

#! /bin/bash


# number of arguments to script
NBARGS=1

# ======================= PROCESS NAME =================================
loopnb=$( head -1 LOOPNUMBER 2> /dev/null)
pname="aol${loopnb}mexwfs"



function printHELP {
echo "------------------------------------------------------------------------"
echo "$(tput bold) $pname : EXTRACT MODE VALUES FROM WFS IMAGES $(tput sgr0)"
echo "------------------------------------------------------------------------"
echo "  computes mode coefficients from WFS image stream"
echo "   "
echo " $(tput bold)USAGE:$(tput sgr0)"
echo "     $0 [-hr] <GPUdevice>"
echo ""
echo " $(tput bold)OPTIONS:$(tput sgr0)"
echo "     $(tput bold)-h$(tput sgr0)          help"
echo "     $(tput bold)-r$(tput sgr0)          read from aol${loopnb}_DMmode_meas instead of computing"
echo ""
echo " $(tput bold)INPUT:$(tput sgr0)"
echo "     <GPUdevice>     GPU device"
echo ""
echo " $(tput bold)OUTPUT:$(tput sgr0)"
echo "     aol${loopnb}_modeval      Mode coefficient values"
echo ""
echo "------------------------------------------------------------------------"
}




printHELP1 ()
{
    printf "     $(tput bold)%-25s$(tput sgr0)       Extract mode values from WFS images\n" "$0" 
}




# Transform long options to short ones
singlelinehelp=0
for arg in "$@"; do
  shift
  case "$arg" in
    "--help") set -- "$@" "-h" ;;
    "--help1") 
set -- "$@" "-h" 
singlelinehelp=1;
;;
    *)        set -- "$@" "$arg"
  esac
done




# ================= OPTIONS =============================
IMPORTmodeval="0"
while getopts :hr FLAG; do
  case $FLAG in
    h)  #show help
      if [ "$singlelinehelp" -eq "0" ]; then
      printHELP
      else
      printHELP1
      fi
      exit
      ;;
    r)
    IMPORTmodeval="1"
    ;;
    \?) #unrecognized option - show help
      echo -e \\n"Option -${BOLD}$OPTARG${NORM} not allowed."
      printHELP
      ;;
  esac
done

shift $((OPTIND-1)) 








if [ "$1" = "help" ] || [ "$#" -ne $NBARGS ]; then
if [ "$#" -ne $NBARGS ]; then
    echo "$(tput setaf 1)$(tput bold) Illegal number of parameters ($NBARGS params required, $# entered) $(tput sgr0)"
fi
printHELP
        exit
fi



loopnb=$( head -1 LOOPNUMBER )

# this version does not use masking (yet)

if [ "$IMPORTmodeval" = "0" ]; then

./AOloopControl -n $pname << EOF
csetpmove aol${loopnb}RT1
readshmim aol${loopnb}_respM
readshmim aol${loopnb}_imWFS0
readshmim aol${loopnb}_imWFS0tot
readshmim aol${loopnb}_wfsref
readshmim aol${loopnb}_wfsmask
listim
cudaextrmodes aol${loopnb}_imWFS0 aol${loopnb}_imWFS0tot aol${loopnb}_respM aol${loopnb}_wfsref nullim aol${loopnb}_modeval $1 1 1 1 2 0 0
exitCLI
EOF

else

#echo "Linking    /tmp/aol${loopnb}_DMmode_meas.im.shm  - /tmp/aol${loopnb}_modeval.im.shm"
#rm /tmp/aol${loopnb}_modeval.im.shm
#ln -s /tmp/aol${loopnb}_DMmode_meas.im.shm /tmp/aol${loopnb}_modeval.im.shm

./AOloopControl -n $pname << EOF
csetpmove aol${loopnb}RT1
readshmim aol${loopnb}_respM
readshmim aol${loopnb}_imWFS0
readshmim aol${loopnb}_imWFS0tot
readshmim aol${loopnb}_wfsref
readshmim aol${loopnb}_modeval
readshmim aol${loopnb}_wfsmask
listim
cudaextrmodes aol${loopnb}_imWFS0 aol${loopnb}_imWFS0tot aol${loopnb}_respM aol${loopnb}_wfsref nullim aol${loopnb}_modeval $1 1 1 1 2 0 0
exitCLI
EOF

fi

Converts WFS residuals into modes.

9.2 Extract open loop modes

Launches script C function (CPU-based):

key       :    aolcompolm
module    :    AOloopControl.c
info      :    compute open loop mode values
syntax    :    <loop #>
example   :    aolcompolm 2
C call    :    long AOloopControl_ComputeOpenLoopModes(long loop)

This function is entirely modal, and assumes that the WFS modes (see section above) are computed. The key input to the function is aolN_modeval, the WFS residual mode values. The function uses this telemetry and knowledge of loop gain and mult factor to track open loop mode values.

Optionally, it also includes aolN_modeval_pC, the predictive control mode values that are added to the correction in predictive mode.

9.3 Running average of dmC

Launches script ./auxscripts/aol_dmCave 0.0005 :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

#!/bin/bash

NBARGS=1
pname=`echo "$0" | sed "s/\.\///g"`






function printHELP {
echo "------------------------------------------------------------------------"
echo "$(tput bold) $pname : dmC temporal averaging $(tput sgr0)"
echo "------------------------------------------------------------------------"
echo "  dmC temporal averaging"
echo "temporal averaging of zonal correction in AO system"
echo "   "
echo " $(tput bold)USAGE:$(tput sgr0)"
echo "     $0 [-h] <coeff>"
echo ""
echo " $(tput bold)OPTIONS:$(tput sgr0)"
echo "     $(tput bold)-h$(tput sgr0)          help"
echo ""
echo " $(tput bold)INPUT:$(tput sgr0)"
echo "     <coeff>   time interval"
echo ""
echo " $(tput bold)EXAMPLE:$(tput sgr0)"
echo "     $0 0.001"
echo ""
echo "------------------------------------------------------------------------"
}


printHELP1 ()
{
    printf "     $(tput bold)%-25s$(tput sgr0)       dmC temporal averaging\n" "$0" 
}




# Transform long options to short ones
singlelinehelp=0
for arg in "$@"; do
  shift
  case "$arg" in
    "--help") set -- "$@" "-h" ;;
    "--help1") 
set -- "$@" "-h" 
singlelinehelp=1;
;;
    *)        set -- "$@" "$arg"
  esac
done


while getopts :h FLAG; do
  case $FLAG in
    h)  #show help
      if [ "$singlelinehelp" -eq "0" ]; then
      printHELP
      else
      printHELP1
      fi
      exit
      ;;
    \?) #unrecognized option - show help
      echo -e \\n"Option -${BOLD}$OPTARG${NORM} not allowed."
      printHELP
      ;;
  esac
done

shift $((OPTIND-1)) 







if [ "$1" = "help" ] || [ "$#" -ne $NBARGS ]; then
if [ "$#" -ne $NBARGS ]; then
    echo "$(tput setaf 1)$(tput bold) Illegal number of parameters ($NBARGS params required, $# entered) $(tput sgr0)"
fi
printHELP
        exit
fi







loopnb=$( head -1 LOOPNUMBER )
pname="aol${loopnb}-$0"

./AOloopControl -n $pname << EOF
readshmim aol${loopnb}_dmC
aveACshmim aol${loopnb}_dmC $1 aol${loopnb}_dmC_ave aol${loopnb}_dmC_AC aol${loopnb}_dmC_rms
exitCLI
EOF

9.4 Compute and average wfsres

Launches script ./auxscripts/aolmkWFSres 0.0005 :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

#!/bin/bash


NBARGS=1
pname=`echo "$0" | sed "s/\.\///g"`




function printHELP {
echo "------------------------------------------------------------------------"
echo "$(tput bold) $pname : Compute real-time WFS residual image $(tput sgr0)"
echo "------------------------------------------------------------------------"
echo "  Compute real-time residual image"
echo "   "
echo " $(tput bold)USAGE:$(tput sgr0)"
echo "     $0 [-h] <averaging coeff>"
echo ""
echo " $(tput bold)OPTIONS:$(tput sgr0)"
echo "     $(tput bold)-h$(tput sgr0)          help"
echo ""
echo " $(tput bold)INPUT:$(tput sgr0)"
echo "   <averaging coeff>    averaging coefficient"
echo ""
echo " $(tput bold)OUTPUT:$(tput sgr0)"
echo "creates streams :"
echo "        aol<loop>_wfsres"
echo "        aol<loop>_wfsres_ave"
echo "        aol<loop>_wfsres_rms"
echo ""
echo "------------------------------------------------------------------------"
}


printHELP1 ()
{
    printf "     $(tput bold)%-25s$(tput sgr0)       Compute real-time WFS residual image\n" "$0" 
}




# Transform long options to short ones
singlelinehelp=0
for arg in "$@"; do
  shift
  case "$arg" in
    "--help") set -- "$@" "-h" ;;
    "--help1") 
set -- "$@" "-h" 
singlelinehelp=1;
;;
    *)        set -- "$@" "$arg"
  esac
done


while getopts :h FLAG; do
  case $FLAG in
    h)  #show help
      if [ "$singlelinehelp" -eq "0" ]; then
      printHELP
      else
      printHELP1
      fi
      exit
      ;;
    \?) #unrecognized option - show help
      echo -e \\n"Option -${BOLD}$OPTARG${NORM} not allowed."
      printHELP
      ;;
  esac
done

shift $((OPTIND-1)) 







if [ "$1" = "help" ] || [ "$#" -ne $NBARGS ]; then
if [ "$#" -ne $NBARGS ]; then
    echo "$(tput setaf 1)$(tput bold) Illegal number of parameters ($NBARGS params required, $# entered) $(tput sgr0)"
fi
printHELP
        exit
fi









loopnb=$( head -1 LOOPNUMBER )

./AOloopControl -n aol${loopnb}latency << EOF
creaimshm aol${loopnb}_wfsavecoeff 1 1
setpix aol${loopnb}_wfsavecoeff $1 0 0
aolmkwfsres ${loopnb} aol${loopnb}_wfsavecoeff
exitCLI
EOF

10.1 Converting DM offsets to WFS offsets (zonal, CPU mode)

CPU-based zero point offsets will compute WFS offsets from the zero point offset DM channels (04-11) and apply them to the aolN_wfszpo# stream.

• Activate CPU individual zero point offset channels (zplon0 to zplon7) to convert dm zero point displacements to wfs offsets.

Every time one of the activated DM channel changes, the corresponding wfs aolN_wfszpo# zero point offset is CPU-computed.

The process runs inside tmux session aolNzploop#

10.2 Converting DM offsets to WFS offsets (zonal, GPU mode)

A faster GPU-based zero point offset from DM to WFS is provided for each of the 8 offset channels. GPU-based and CPU-based offsetting for a single channel are mutually exclusive.

• Activate GPU individual zero point offset channels (GPUzplon0 to GPUzplon7) to convert dm zero point displacements to wfs offsets.

Every time one of the activated DM channel changes, the corresponding wfs aolN_wfszpo# zero point offset is GPU-computed.

The process runs inside tmux session aolNGPUzploop#

10.3 Modal offsetting from another loop

The two methods above are zonal offsetting: the DM map is multiplied by the zonal WFS response to compute WFS offset.

Modal offsetting, instead, relies on a pre-computed set of WFS modal offets. This is most useful when a separate control loop is driving modal offsets to the current loop.

To implement modal offsetting from a separate loop (refered to as the offsetting loop) :

• Configure the DM of the offsetting loop to write WFS zero point offsets to the current loop (see setting up DM section)

• Do not activate either of the previous two zonal offsetting schemes

• Activate the WFS offsets process (see next subsection)

10.4 Summing and applying WFS offsets to aolN_wfsref

To activate WFS offsets to aolN_wfsref, the user needs to :

• Toggle the zero point offset loop process ON (LPzpo) prior to starting the loop.

Command aolzpwfscloop (C function AOloopControl_WFSzeropoint_sum_update_loop) launches a loop that monitors shared memory streams aolN_wfszpo0 to aolN_wfszpo7, and updates the WFS reference when one of these has changed.

The loop is running inside tmux session aolNwfszpo, and is launched when the loop is closed (Floopon) if the loop zero point offset flag is toggled on (LPzpo)

10.5 WFS average offset

Measures average WFS residual with script :

./auxscripts/aolmkWFSres 0.0005

Running average is in stresm aol_wfsres_ave

11.1 Running the loop

The next steps are similar to the ones previously described, with the following important differences:

• The control matrix should be computed in zonal mode (no modal CPA block decomposition)

12.1 Overview

Predictive control is implemented in two processes:

• The optimal auto-regressive (AR) filter predicting the current state from previous states is computed. The AR filter is computed from open-loop estimates, so the processes computing open-loop telemetry need to be running.

• the AR filter is applied to write a prediction buffer, which can be written asynchronously from the main loop steps.

The predictive filter is modal, and adopts the same modes as the main control loop.

12.2 Scripts

12.3 Data flow

Predictive control is set up by blocks of modes. A block is configured through the aolconf predictive control sub-panel, which writes to configuration files conf/conf_PFblock_XXX.txt, where XXX is the block number (000, 001, 002 etc...). Configuration files specify the modes within each block (index min to index max), the predictive filter order, time lag and and averaging gain.

For each block, there are 3 main processes involved in running the predictive control:

• Watching input telemetry this process listens to the input telemetry stream and periodically writes data to be used to compute a filter. This runs function long AOloopControl_builPFloop_WatchInput(long loop, long PFblock) in AOloopControl.c.

• Computing filter. Runs CLI command mkARpfilt, which runs function LINARFILTERPRED_Build_LinPredictor in linARfilterPred.c.

• Prediction engine (= apply filter). Runs script ./auxscripts/predFiltApplyRT.

All 3 processes work in a chain, and can be turned on/off from the GUI.

13.1 Linking to existing stream

Creates a sym link from an existing stream to a new stream. This is frequently used to connect to hardware (for example pointing aol8_wfsim to the WFS camera stream).

Within AOCCE, setting (new) stream aol#_<deststream> to point to <srcstream> involves:

• writing "<srcstream>" to file conf/streamlink_<deststream>.name.txt
• removing any existing aol#_<deststream> stream
• establishing sym link from <srcstream> to aol#_<deststream>

The corresponding commands, to point aol8_wfsim to imcam, would be:

echo "imcam" > conf/streamlink_wfsim.name.txt
rm /tmp/aol8_wfsim.im.shm
ln -s /tmp/imcam.im.shm /tmp/aol8_wfsim.im.shm

This is implemented in script :

./aolfuncs/aolfunc_StreamLink

13.2 Loading images from FITS to shared memory stream

echo "./wfsref0/wfsref0_today.fits" > ./conf/shmim_wfsref0.name.txt
Fits2shm -c -p aol${LOOPNUMBER}_ wfsref0

 -c           read FITS file name from ./conf/shmim_<streamname>.name.txt directory
 -p <pref>    stream prefix

Fits2shm <FITS file> <stream>

Fits2shm -c <stream>

Fits2shm -c -p aol8_ <stream>

14.1 Overview

The conf directory contains the following file types:

14.2 Parameters

14.3 Stream Links

14.4 Shared memory FITS file initializations to streams

File shmim_<stream>.name.txt contain the FITS file names that are loaded into shared memory streams aol<loop>_<stream>.

14.5 FITS files

16.1 Starting the linear hardware simulator

STEP 1: Create directory <workdir>

STEP 2: Install scripts into <workdir>:

cd <srcdir>/src/AOloopControl/scripts
syncscripts -e <workdir>
cd <workdir>
./syncscripts

STEP 3: Download a calibration, consisting of zonal response matrix and a WFS reference. Place the file in a new directory <workdir>/simLHS

STEP 4: Launch aolconf, loop number 5, loop name simtest:

./aolconf -L 5 -N simtest

Note that you subsequent calls to aolconf should then be without the -L and -N options.

STEP 5: Set DM size to match the calibration. dmxs and dmys GUI top menu.

STEP 6: Autoconfigure DM: dmnolink in GUI top menu.

STEP 7: Turn off dmvolt: dmvolt0 in GUI top menu.

STEP 8: Set DM averaging mode to 2: dmcombam in GUI top menu.

STEP 9: Start DMcomb. initDM in GUI top menu.

STEP 10: Load all memory. M in GUI top menu

STEP 11: Link LHS files

STEP 12: Start the LHS process

16.2 Acquiring calibration, compute control matrix

Under configuration GUI menu :

• Measure hardware timing: mlat
• set Hadamard mode to ON: Hon
• set RM modal to ON: RMMon
• Acquire automatic calibration: nAUTOc

Under control matrix GUI menu :

• Select maximum control spatial frequency: modeCPA
• Create modes and control matrix: mkModes0
• update configuration: confUp

Load and manage configuration :

• load configuration
• save configuration

17.1 Queued process

A queued process is a process that has been sent to a tmux session but is awaiting previous operations, within the same tmux session, to be completed. The process is logged as queued when the corresponding command is sent to the tmux session. When the tmux session reaches the command, it will move it from queued to active.

To log queued processes as such, follow this bash template:

logRunningProcessQ "<process_tag>" <tmux_session_name>
tmux send-keys -t <tmux_session_name> "process_command" C-m

or

logRunningProcessQ0 "<process_tag>" <tmux_session_name> "<comments>"
tmux send-keys -t <tmux_session_name> "mv runproc/<process_tag>.runprocQ runproc/<process_tag>.runproc" C-m
tmux send-keys -t <tmux_session_name> "process_command" C-m

process_tag is a name chosen to represent the operations performed. The second option can be used when writing to a script, so it is more flexible.

17.2 Active process

To mark a process as active, it can either be queued as described above, or the user can include at the time the process starts:

touch runproc/<process_tag>.runproc

Once the process is completed, it needs to be removed from the active process list :

rm runproc/<process_tag>.runproc

17.3 Locking/unlocking processes

The command ./auxscripts/waitforfilek in <srcdir>/scripts locks the bash script execution until a file <tagname>.unlock appears. The command will remove the unlock file once it appears, and continue execution. It can take a timeout option. Typical use:

tmux send-keys -t <tmux_session_name> "command_that_needs_to_be_completed_before_non-tmux_script_commands" C-m
tmux send-keys -t <tmux_session_name> "touch <tagname>.unlock" C-m  # command will unlock the script once the unlock file appears
./auxscripts/waitforfilek -t <timeout_sec> <tagname>
<non-tmux_script_commands_to_be_executed_AFTER_tmux_commands>

The command creates a ".lock" file, and waits for a ".unlock" to appear. When the unlock file is detected, both lock and unlock files are removed. The lock file indicates that a process is currently locked. This scheme can be employed to synchronize multiple scripts.

The lower level ./auxscripts/waitonfile command allows users to manually setup locks between proceses, by waiting for a file to disappear. Typical use:

touch fname.lock
<some other process here, will remove fname.lock file when done>
./auxscripts/waitonfile fname.lock
<more bash instructions here>