Skip to content

running cacao example arch01

Jump to bottom
Olivier Guyon edited this page Jun 1, 2021 · 1 revision

Running a cacao loop: example 01

THIS PAGE IS NOT UP-TO-DATE.

With this first example, we will be running an AO loop and the corresponding linear hardware simulator (LHS). The LHS function is to simulate hardware, and compute WFS signals from DM state. The AO loop, in turn will process WFS signals and issue commands to the DM.

Prerequisites

  • Linux OS
  • cacao package
  • Optional: shmimview or other viewer for milk streams

Conventions, useful tools

Naming conventions for this example :

<workdirectory> = "AOloop-cacao"
    User-created work directory from which commands are executed by default

<AOloopdirectory> = "cacaoloop01dir"
    created by cacao-setup within workdirectory
    directory name is user-specified by ENV CACAO_WORKDIR

<loopname> = "cacaoloop01"
    cacao loop name

In this document:

  • Commands are preceded by $
  • File content (not to be executed) preceded by "FILE <fname> :"

Useful tools that can be run anytime :

$ milk-streamCTRL  # inspect/control current data streams 
$ milk-procCTRL    # inspect/control current processes 
$ milk-fpsCTRL     # inspect/control current function parameter strucutures
$ tmux ls     # list tmux sessions

To exit streamCTRL, procCTRL or fpsCTRL, type "x".

QUICK START

Download cacaoloop-ex01-conf directory

Then run :

$ cacao-task-manager cacaoloop01-ex01

Run again with -x option to advance.

PART 1: Seting up the linear hardware simulator

Getting started

Create a work directory. For example:

$ mkdir AOloop-cacao
$ cd AOloop-cacao

downloading linear hardware simulator (LHS) calibration

Create, within the work directory, a subdirectory simLHS and copy the respM.fits and wfsref.fits files that will be used by the linear hardware simulator:

$ mkdir simLHS
$ cp <respMfile> ./simLHS/cacaoloop01.respM.fits
$ cp <refWFSfile> ./simLHS/cacaoloop01.wfsref.fits

You can find example respM and wfsref files in the cacao data google drive folder. You will need to rename or copy the files to the file names listed above. To do so, you may use wget from the command line:

    $ wget --no-check-certificate 'https://drive.google.com/uc?export=download&id=1x2O_ZVMkEzTT66bthU8t_g9mGs2g_dQK' -O ./simLHS/cacaoloop01.wfsref.fits

    $ ggID='1D1SfU2gZpzEU-tRZK0bJsL6MUYZ09Ils'
    $ ggURL='https://drive.google.com/uc?export=download'
    $ filename="$(curl -sc /tmp/gcokie "${ggURL}&id=${ggID}" | grep -o '="uc-name.*</span>' | sed 's/.*">//;s/<.a> .*//')"
    $ getcode="$(awk '/_warning_/ {print $NF}' /tmp/gcokie)"
    $ curl -Lb /tmp/gcokie "${ggURL}&confirm=${getcode}&id=${ggID}" -o "${filename}"
    $ mv LHS_zrespM_2018-01-25_05:09:52.fits ./simLHS/cacaoloop01.respM.fits

To set up a cacao instance in this directory, we will use the cacao-setup tool. Run with -h option to see instructions :

$ cacao-setup -h

Instructions show four main steps to cacao-setup:

  • STEP 1: Set environment variables
  • STEP 2 [optional]: Set function parameter values
  • STEP 3: Run cacao-setup
  • STEP 4: Start processes
  • STEP 5: Launch control screen

At any time, we can check the status of the configuration (executables, configuration files, environment variables, etc..) :

$ cacao-setup -t cacaoloop01

At this point, the command should return an error message (cacaovars file missing). We will address this in step 1.

Step 1: Setting up key environment variables

Before starting cacao-setup, we need to specify essential parameters, such as the size of the DM, the working directory where files will be installed, and which processes/functions should be enabled.

To do so, we create FILE cacaovars.cacaoloop01.bash :

# cacao environment variables for setup
# This file will be sourced by cacao-setup

# 1 if DM actuators are on a coordinate grid
# This informs processes if a spatial relationship exists 
# between DM actuators
export CACAO_DMSPATIAL="1" 

# Deformable mirror (DM) size
# If DM is single dimension, enter "1" for DMsize
# 
export CACAO_DMxsize="50"
export CACAO_DMysize="50"

export CACAO_WORKDIR="cacaoloop01dir"
export CACAO_DMINDEX="01"
export CACAO_LOOPNUMBER="2"
export CACAO_WFSSTREAM="aol2_linsimWFS"


# ========================================
#       FPS processes to be set up 
# ========================================

# DM combination 
# Manages mutipe DM channels
# 
export CACAO_FPSPROC_DMCOMB="ON"

# Delay stream: emulates time lag in hardware
# Used to simulate a time lag
# 
export CACAO_FPSPROC_STREAMDELAY="ON"

# MVM lop on GPU: used to simulate hardware
# 
export CACAO_FPSPROC_SIMMVMGPU="ON"

# Measure hardware latency
# 
export CACAO_FPSPROC_MLAT="ON"

# Acquire WFS stream
#
export CACAO_FPSPROC_ACQUWFS="ON"

# Acquire linear RM (zonal)
# 
export CACAO_FPSPROC_ACQLINZRM="ON"

# Acquire low-order modal RM
#
export CACAO_FPSPROC_ACQLINLORM="ON"

# Compute control matrix
#
export CACAO_FPSPROC_COMPFCM="ON"

# Extract control modes
#
export CACAO_FPSPROC_MODESEXTRACTWFSGPU="ON"

# Control loop
#
export CACAO_FPSPROC_AOLOOP_RUN="ON"

To check that all variables are set :

$ cacao-setup -t cacaoloop01

We should see "[ OK ] Settings OK": we can proceed to step 2.

Step 2: Setting function parameters values

We have the opportunity to set parameters for cacao processes. Note that this is optional, as default parameters may be used, and the user could change parameters later.

To specify function parameters at startup, we will create/edit FILE fpssetup.setval.cacaoloop01.conf :

# set function parameters

setval DMcomb-01.AveMode 1
setval DMcomb-01.option.dm2dm_mode OFF
setval DMcomb-01.option.wfsrefmode OFF
setval DMcomb-01.option.voltmode OFF

setval streamDelay-01.in_name aol2_dmdisp
setval streamDelay-01.out_name aol2_dmdispD
setval streamDelay-01.delayus 20000
setval streamDelay-01.option.timeavemode 1
setval streamDelay-01.option.avedt 0.005

setval simmvmgpu-2.sname_in aol2_dmdispD
setval simmvmgpu-2.sname_modes aolsimLHSrespM
setval simmvmgpu-2.sname_outmodesval aol2_linsimWFS
setval simmvmgpu-2.option.twait 5000
setval simmvmgpu-2.option.sname_refout aolsimLHSwfsref
setval simmvmgpu-2.option.insem 6
setval simmvmgpu-2.option.axmode 1

setval mlat-2.sn_dm aol2_dmRM
setval mlat-2.sn_wfs aol2_linsimWFS

The file name is such that cacao-setup will automatically load it. For a cacao instance named $loopname, it is important to stick to the naming convention fpssetup.setval.$loopname.conf.

Step 3: Run setup

Lets confirm we are ready to go :

$ cacao-setup -t cacaoloop01

You should see "Settings OK".

To run the setup, create terminal window for fpsCTRL and run cacao-setup:

$ xterm -geometry 160x40 -hold -e 'tty > tty.dat; bash' &
$ cacao-setup -y $(<tty.dat) cacaoloop01

The setup command starts a milk-fpsCTRL instance, as well as a process configuration instance for each of the FPS processes enabled.

To list tmux sessions :

$ tmux ls

The following tmux sessions should appear:

name Description
cacao- cacaoloop01 General purpose session for cacao loop
cacaoloop01_fpsCTRL Function Parameter Structure Control
XXX-conf Configuration process for function XXX
XXX-run Run process for function XXX

Step 4: Start processes

A cacao instance consists of multiple processes. In this example, we have included DMCOMB, STREAMDELAY, SIMMVMGPU and MLAT. Each of these actually consists of two separate proposesses:

  • a conf-process that manages parameters
  • a run-process that runs the computation

cacao-setup automatically starts the conf-processes, but not the run-processes.

run-processes can be started from fpsCTRL tool manually, or by sending a command to fpsCTRL through its fifo.

We will start run-processes in the following order:

  • DMCOMB
  • STREAMDELAY
  • SIMMVMGPU

Together, these processes will implement a linear simulator of an AO system: on each update of a DM channel, an updated WFS image will be computed. This simulation includes a hardware lag.

Starting DMCOMB (manages DM channels)

First, we start the DMcomb process, named DMcomb-01, as it controls DM index 01. To start it by issuing a command to fpsCTRL, type:

$ echo "runstart DMcomb-01" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Alternatively, we can use the fpsCTRL TUI:

$ tmux a -t cacaoloop01_fpsCTRL

and type "R" when the DMcomb-01 entry (or any of its subentries) is selected.

From now on, we will only describe the command line path to issuing commands to fpsCTRL.

Starting STREAMDELAY (emulates hardware lag on the dm01disp stream)

STREAMDELAY requires stream dm00disp to exist, so when we first started the conf-processes, the streamdelay conf-processed returned an error due to missing stream dm01disp. Now that the stream has been created by DMCOMB, we request STREAMDELAY conf-process to scan update (scan again):

$ echo "confupdate streamDelay-01" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

The error should disappear, allowing us to start the run-process:

$ echo "runstart streamDelay-01" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Start SIMMVMGPU (Perform matrix-vector-multiply on GPU)

Similarly to the previous section, we first request a conf update since SIMMVMGPU's input stream (dm01dispD) was just created:

  $ echo "confupdate simmvmgpu-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

and then start the run-process:

$ echo "runstart simmvmgpu-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

PART 2: Calibration

With the simulator running, we can execute AO loop processes just as if we were connected to physical hardware.

Timing calibration (MLAT)

The timing latency process measures loop frequency and hardware latency. To run it, we follow the usual steps:

First, rerun configuration to check all is good:

$ echo "confupdate mlat-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Then, start the run-process:

$ echo "runstart mlat-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

This process will run for about a minute. Once done, we can review results in the fpsCTRL screen under "mlat-2 -> out", were the measured framerate and latency are shown.

The latency curve is in file:

./<loopdirectory>/timingstats/hardwlatency.txt

WFS Acquisition

$ echo "confupdate acquWFS-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo
$ echo "runstart acquWFS-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Zonal Response Matrix

$ echo "confupdate acqlin_zRM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo
$ echo "runstart acqlin_zRM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Low-order Modal Response Matrix

$ echo "confupdate acqlin_loRM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo
$ echo "runstart acqlin_loRM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Compute Fourier-based Control Matrix

$ echo "confupdate compfCM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo
$ echo "runstart compfCM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

Extract WFS modes

$ echo "confupdate compfCM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo
$ echo "runstart compfCM-2" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo

AUTOMATIC SCRIPT

All above commands can be run by feeding instructions to the scheduler.

#!/bin/bash

function sendFPScmd {
echo "SENDING: $1"
echo "$1" >> ${MILK_SHM_DIR}/cacaoloop01_fpsCTRL.fifo
}



# Fill up execution queue 2
sendFPScmd "setqindex 2"
# put execution queue on hold (priority = 0)
sendFPScmd "setqprio 0"
sendFPScmd "confwupdate acquWFS-2"
sendFPScmd "runstart acquWFS-2"


# Fill up execution queue 0
sendFPScmd "setqindex 0"
# run tasks with priority = 1 (highest priority first)
sendFPScmd "setqprio 1"

sendFPScmd "runstart DMcomb-01"

sendFPScmd "setval streamDelay-01.dtus 10000"
sendFPScmd "confwupdate streamDelay-01"

sendFPScmd "runstart streamDelay-01"

sendFPScmd "confwupdate simmvmgpu-2"
sendFPScmd "runstart simmvmgpu-2"

# launch queue 2
sendFPScmd "queueprio 2 1"

sendFPScmd "confwupdate mlat-2"



sendFPScmd "waitonrunON"
# wait until RUN process complete to proceed to next one
# marks start of sequential operation

sendFPScmd "runstart mlat-2"
sendFPScmd "waitonrunOFF"



sendFPScmd "waitonrunON"

# take zonal response matrix
sendFPScmd "confwupdate acqlin_zRM-2"
sendFPScmd "runstart acqlin_zRM-2"

# take low-order modal RM
sendFPScmd "confwupdate acqlin_loRM-2"
sendFPScmd "runstart acqlin_loRM-2"

# compute control matrix
sendFPScmd "setval compfCM-2.upAlign ON"
sendFPScmd "setval compfCM-2.upRMfiles ON"
sendFPScmd "confwupdate compfCM-2"
sendFPScmd "runstart compfCM-2"

sendFPScmd "waitonrunOFF"

# adopt control matrix
cp conf-fCM-staged/shmim.contrM.fname.txt conf/shmim.aol2_contrM.fname.txt
sendFPScmd "confwupdate loopRUN-2"

compute and control for adaptive optics (cacao) - https://github.com/cacao-org/cacao

Home

Installation, System Setup and Performance

User Guide

cacao by examples

Programming with milk and cacao

Technical notes

Clone this wiki locally