running cacao example arch00

1. Running a cacao loop: example

THIS PAGE IS NOT UP-TO-DATE.

---

Conventions, useful tools

Let us first define the following terms:

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

<AOloopdirectory>  
	example value: "linsimtest1"
    Created by cacao-setup within workdirectory
    Directory name is user-specified by ENV CACAO_WORKDIR
    
<loopname>
    example: "linsimtest1"
    User-defined AO 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 :

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

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

PART 1: Seting up the linear simulator

Getting started

Create a work directory. For example:

$ mkdir AOloop-cacao
$ cd AOloop-cacao

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/respM.fits
$ cp <refWFSfile> ./simLHS/wfsref.fits

You can find example respM and wfsref files in the cacao data google drive folder. You will need to rename the files to the respM.fits and wfsref.fits names listed above.

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 five main steps to cacao-setup:

• STEP 1: Set environment variables
• STEP 2: Set function parameter values
• STEP 3: Run 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 <loopname>

Each cacao instance has a unique name. In this example we will be using linsim

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.linsim.bash :

# cacao environment variables for setup
# source this file to take into effect

export CACAO_DMSPATIAL="1"  # 1 if DM actuators are on a coordinate grid

export CACAO_DMxsize="50"
export CACAO_DMysize="50"
export CACAO_WORKDIR="linsimtest1"
export CACAO_DMINDEX="01"
export CACAO_LOOPNUMBER="2"
export CACAO_WFSSTREAM="aol2_linsimWFS"


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

# DM combination 
export CACAO_FPSPROC_DMCOMB="ON"

# delay stream: emulates time lag in hardware
export CACAO_FPSPROC_STREAMDELAY="ON"

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

# Measure latency
export CACAO_FPSPROC_MLAT="ON"

# Acquire linear RM
export CACAO_FPSPROC_ACQLINRM="ON"

To check that all variables are set :

$ cacao-setup -t <loopname>

We should see "Settings OK".

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.linsim.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.

Note: A blank file is created by default by cacao-setup.

Step 3: Run setup

Lets confirm we are ready to go :

$ cacao-setup -p

You should see "Settings OK".

To run the setup:

$ cacao-setup

The setup command starts a fpsCTRL instance, as well as a process configuration instance for each of the FPS processes enabled. The easiest way to inspect these processes is to run fpsCTRL:

$ fpsCTRL

Note: Type "x" to exit fpsCTRL

To list tmux sessions :

$ tmux ls

The following tmux sessions should appear:

name	Description
cacao-linsim	General purpose session for cacao loop
linsim_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 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}/linsim_fpsCTRL.fifo

Alternatively, we can use the fpsCTRL TUI:

tmux a -t linsim_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}/linsim_fpsCTRL.fifo 

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

echo "runstart streamDelay-01" >> ${MILK_SHM_DIR}/linsim_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}/linsim_fpsCTRL.fifo

and then start the run-process:

echo "runstart simmvmgpu-2" >> ${MILK_SHM_DIR}/linsim_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}/linsim_fpsCTRL.fifo

Then, start the run-process:

echo "runstart mlat-2" >> ${MILK_SHM_DIR}/linsim_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