cacao Documentation

Table of Contents

• 1. What is cacao ?
• 2. Installing cacao and running command line interface
• 3. Fundamentals
  • 3.1. Processes and Streams
  • 3.2. Building an AO control loop
  • 3.3. Key tools
• 4. Configuring and running cacao
  • 4.1. Step-by-step instructions
• 5. Programming with cacao
  • 5.1. Source Code
  • 5.2. Programming guide
• Appendix A. Modules
  • A.1. milk modules
  • A.2. cacao-specific modules

Note

This file: ./pages.dox

---

1. What is cacao ?

The compute and control for adaptive optics (cacao) package is a collection of tools for adaptive optics real-time control.

---

2. Installing cacao and running command line interface

• Installation : Downloading and Installing cacao
• Command Line Interface : Using cacao's command line interface (CLI)
  • CLI Overview
  • Readline Input Keys
  • Command Line Interface Syntax

---

3. Fundamentals

3.1. Processes and Streams

cacao relies on a collection of processes to run an AO loop, rather than a single large function. This provides a modular and flexible solution, able to run simple AO control loop as well as very complex setups.

Synchronization and communication between processes is achieved by the data stream structure used throughout cacao. Mechanisms to synchronize processes and track interactions between data and processes (such as: which process is writing a specific stream) are embedded within the data structure. For more details, see module ImageStreamIO.c.

3.2. Building an AO control loop

Under cacao's framework, the AO control loop is assembled from streams and processes. Each process typically reads (= listens) to a stream. Once the stream is updated, the process will start computations and will usually update other stream(s). Long chains of processes can thus be built, with multiple branches (several processes can listen to the same stream).

More of cacao's processes are running a loop.

3.3. Key tools

To manage processes and streams, cacao offers a few useful tools, allowing users to quickly inspect complex AO loops. They are included in the directory src/CommandLineInterface/scripts, which is included in the path, per installation instructions. cacao users will make frequent use of these tools.

• milk-procCTRL, the process controller. See Process Info Structure (processinfo) for details.
• milk-streamCTRL, the stream controller. See streamCTRL.c for details.
• milk-fpsCTRL, the function parameter structure controller. See Function Parameter Structure (FPS) for details.
• milk-shmimmon, the shared memory image monitor, is used to inspect individual streams

---

4. Configuring and running cacao

4.1. Step-by-step instructions

• STEP-BY-STEP EXAMPLE

Users guide:

• cacao Initial Setup
• cacao Software Overview
• cacao Hardware Simulation
• cacao Control: Setup and Overview
• Setting up hardware interfaces
• Calibration
• Building control matrix
• Running the loop: setting mode (CPU/GPU)
• Auxilliary processes
• Offsetting
• Predictive control

Appendices:

• APPENDIX A: SHARED MEMORY STREAMS
• CONF DIRECTORY CONTENT
• MANAGING MULTIPLE PROCESSES

---

---

5. Programming with cacao

5.1. Source Code

cacao is hosted on github, and consists of multiple modules.

cacao is coded in C, compiles with gcc under cmake. cacao is built on top of the milk package. The cacao package includes milk (milk modules), and adds AO-specific modules (cacao modules).

Important changes to the package are listed in the CommandLineInterface Change Log.

5.2. Programming guide

• Working with git
• Coding Standards
  • Module Files
  • Documenting Code
  • Template Souce Code
  • Process Info Structure (processinfo)
  • Function Parameter Structure (FPS)
  • page_exampleBASHscript
• Loading, Creating Additional Modules

---

Appendix A. Modules

cacao uses milk modules for its command line, memory management, image I/O and standard image computations.

A.1. milk modules

cacao builds on the milk package and framework. Command line interface, memory management and general purpose image processing functions are provided by the milk modules.

Module	Description	Souce Code Reference
CommandLineInterface	Command interpreter	CLIcore.h
ImageStreamIO	Image format and low-level routines	ImageStreamIO.h
00CORE	Core functions	00CORE.h
COREMOD_memory	Memory management, image creation	COREMOD_memory.h
COREMOD_iofits	Read and write FITS files	COREMOD_iofits.h
COREMOD_tools	Misc frequently used functions	COREMOD_tools.h
COREMOD_arith	Arithmetic operations on images	COREMOD_arith.h
info	Image information	info.h
image_basic	Frequently used image functions	image_basic.h
image_filter	Image filtering, convolution	image_filter.h
image_format	Read/write images in several formats	image_format.h
image_gen	Generate useful images	image_gen.h
img_reduce	Combine raw images into single image	img_reduce.h
fft	Wrapper to FFTW and other functions	fft.h
statistic	Statistical tools and analysis	statistic.h
kdtree	k-d tree	kdtree.h
linARfilterPred	Linear predictive filtering	linARfilterPred.h
linopt_imtools.h	Linear optimization tools	linopt_imtools.h
psf	Point Spread Function analysis	psf.h
ZernikePolyn	Zernike Polynomials	ZernikePolyn.h
cudacomp	Cuda wrapper	cudacomp.h

A.2. cacao-specific modules

Module	Description	Souce Code Reference
AOloopControl	Top-level module for AO control	AOloopControl.h
AOloopControl_IOtools	Input-Output tools	AOloopControl_IOtools.h
AOloopControl_acquireCalib	Acquire AO calibration	AOloopControl_acquireCalib.h
page_AOloopControl_computeCalib	Compute AO calibration	AOloopControl_computeCalib.h
AOloopControl_perfTest	AO performance analysis	AOloopControl_perfTest.h
AOloopControl_compTools	AO computation tools	AOloopControl_compTools.h
AOloopControl_PredictiveControl	Predictive Control	AOloopControl_PredictiveControl.h
AOloopControl_DM	Deformable mirror control	AOloopControl_DM.h
FPAOloopControl	Focal plane AO control	FPAOloopControl.h

---