Importing AO Configuration Data

This section explains how to import data generated by the AO configuration tools into a LightLike simulation.  Generally, the data to be imported is a subset of the items saved in the final .mat filegenerated in the AO configuration process.  The AO setup data is passed via the Runset Editor and the System Editor to the parameters of LightLike modules, most importantly DeformableMirror andHartmannWfsDft.  The user can "elevate" module parameters as necessary and convenient for specifying the actual config-file data.  The following picture is a snapshot from LightLike's System Editor, showing the inputs (light blue), outputs (dark blue), and parameters (gray) of the DeformableMirror and HartmannWfsDft  library systems.  The key items for present purposes are highlighted by red sidebars:  the parameter dmModel in DeformableMirror (see gray middle column), and the system parameters xSubap, ySubap, and subapWidth in HartmannWfsDft.  Data values created by the AO configuration tools must be inserted via setting expressions into the value fields (see gray third column) for these parameters, or else the parameters can be elevated for later setting.  For general background information on elevating parameters and assigning setting expressions, see the LightLike User Guide;  the present section explains some specializedparameter-setting syntax that is peculiar to AO configuration information

The AO configuration quantities that must be passed in are a collection of scalars, vectors and matrices stored in the final .mat file created during the AO configuration process.  Perhaps the user is already acquainted with some LightLike procedures for reading vectors, arrays and grids from .matfiles into system parameters, as explained in the LightLike User Guide (see mliLoad and related functions).  Although the AO configuration quantities are simply more vectors and matrices, the LightLike editor interface uses additional specialized syntax and functions to read in the AO vectors and matrices.

(Parenthetically, we give a brief excuse for the convoluted syntax that follows.  The procedure was originally developed because the AO configuration information can require much storage, and the use of C++ pointers ("*" variables) and references ("&" variables) avoids making copies of information such as OPD influence functions and reconstructor matrices.)

We now give the prescription for using the specialized syntax in the setting expressions.  Let us first consider the DeformableMirror system, and the dmModel parameter, whose data type (see grey first column) is DMModel&.

Step 1:

(a)  In the LightLike Runset Editor, create a run variable of Type TasatDMModel*  (NOTE thetrailing * in the Type name).

See the Runset Editor snippet below for an example.

(b)  Assign the run variable Name: this is tdm  in the example below, although the Name can be arbitrarily specified.

(c)  In the Value field, enter the so-called constructor function, TasatDMModel(...).  See below for the meaning of its arguments.

Step 2:

(a)  In the LightLike System Editor, elevate the parameter of Type DMModel&  from the DeformableMirror subsystem, so that it appears as a System Parameter in the Run Set Editor (as seen in the above picture).

(b)  Assign the Value *tdm  (NOTE the leading *), where tdm  is whatever Name was assigned to the run variable in Step 1b.  

(Step 2 can carried out before Step 1 in the model building)

The TasatDMModel(...) constructor function must have one of the following argument forms (items in bold type should be entered verbatim, items in italics are substituted with more specific information, and items in braces ({ }) are optional) :

•TasatDMModel(filename, TDMALL)

•TasatDMModel(filename, TDMALL, apscaling)

•TasatDMModel(filename, TDMALL, apscaling, reconname)

where

filename    is the name of the final .mat file created by the AO configuration  process.  This file must contain all the required geometry, OPD influence, and reconstructor data.  The filename is a character variable that must be placed inside double quotes.  In the filename spec, relative paths and the usual dot notations "./" and "../" are allowed.  Note that forward slashes must be used as directory delimitors.

TDMALL    is a flag which allows for additional flexibility not documented here.

The user should simply enter TDMALL exactly as written here.

apscaling    is a scale factor to be applied to the size of the DM aperture as defined in the input file.  Using the AO configuration tools, a configuration must be constructed for a particular aperture size.  However, the same geometry may be useful on systems having a different aperture size.  Setting apscaling to a value other than one causes the AO geometry defined in filename to be scaled by the specified factor. For example, suppose we devise an AO geometry using a 1.0 meter aperture. Later we can specify apscaling=0.75 to use the same influence function and reconstructor on a 0.75 meter system. When not specified, 1.0 is assumed.

CAUTION:  When using apscaling ~= 1, one must careful about other setting expressions where one also extracts information from filename.  One must extract the information in such a way that LightLike knows it is supposed to modify the value found in the file by the apscaling factor. In particular, this comment applies to the setting expressions in the HartmannWfsDft component for the parameters Dsub, xsub, and ysub.  When apscaling=1, one might extract these parameters using an mliLoad(...) call (see the LightLike User Guide), but LightLike only knows to apply the apscalingfactor if the quantities are extracted using a "method" of DMModel.  The available "methods" are defined in the following subsection.

reconname    Variable name of the desired reconstructor matrix contained in filename.  Recall that files created by the AO configuration process can contain more than one reconstructor matrix.  Ifreconname is not specified, the name is assumed to be "recon".

"Methods" of DMModel

In the case of the dmModel parameter in DeformableMirror, all available AO configuration information was passed in using the composite parameter called dmModel.  On the other hand, the interface of HartmannWfsDft is arranged differently, and requires several specific items to be explicitly extracted from the AO configuration .mat file.  The required items are:

(a)  the locations of the centers of the subapertures (system parameters xSubap and ySubap, which were designated elsewhere in the present AO Guide as xsub and ysub)

(b)  the subaperture width subapWidth.

There are two ways of extracting specific variables from the mass of AO configuration data, as needed by HartmannWfsDft  (or potentially other LightLike components):

(1)  Read required variables (e.g., xsub and ysub vectors) from the .mat file by using LightLike's file read functions, as explained in the LightLike User Guide (see the discussion of mliLoad(...) and related functions).

(2)  Use "methods" associated with the "object" or "class" dmModel.  This requires that a dmModel object, of data Type DMModel&, exist at the same system hierarchy level where we desire to use the "method".  If this requirement is met, then xSubap, ySubap and subapWidth could be defined by the following setting expressions (which have been entered into the earlier System Editor screenshot of the HartmannWfsDft module):

  xSubap  <---  dmModel.xMeasurementLocations()

  ySubap  <---  dmModel.yMeasurementLocations()

  subapWidth  <---  dmModel.xMeasurementWidth()

Notice that yet another "method" of dmModel was used to assign values to the parameters pos0,vel0, acc0  in DeformableMirror (see the earlier screen snapshot).

The following is a list of dmModel "methods" that users should find helpful:

Remaining parameter specifications

HartmannWfsDft In particular has numerous parameters in addition to the ones discussed above.  These additional parameters must be set independently;  i.e., their setting expressions cannot be read from information contained in the *.mat file generated by the AO configuration process.  The general LightLike User Guide contains further information on WFS modeling, parameter definitions and setup.

Miscellaneous usage tips

LightLike allows for multiple adaptive optics geometries to be used within a single simulation run.  This can be done by defining two run variables of type TasatDMModel*,  named for example tdm1and tdm2, and correspondingly flowing up two variables of type DMModel&, named for exampledmModel1 and dmModel2.  This would allow, e.g., two deformable mirrors to be used in a system, with completely different geometries and reconstructor information.  (Previously, we have mentioned the possibility of running more than one AO system in a single simulation, with the same geometry but different reconstructors.  That case does not require multiple run variables of type TasatDMModel*.)