How to use the custom DM feature?

Custom DM

What is it ?

The custom DM option allows the user to provide COMPASS with some specific influence functions and positions of actuators. COMPASS will read the influence functions and resample them to its own geometry and sampling using splines.

The custom DM can be used to feature well-known, famous DMs such as the M4 of the ELT, the Boston 32x32 MEMS, or the ALPAO 64x64 magnetic DM for instance.

The “custom DM” feature of COMPASS allows you to adjust finely the magnification of the DM with respect to the pupil size, as the simulation of a real experiment would require.

Custom DM fits file

The custom DM fits file shall contain 3 extensions with data:

  • Extension n°1 (EXTNAME = 'I1_J1') : is the list of all the indexing values (ix, iy) where the first pixel of each minimap is placed in the original large frame. As this list correspond to some index values, it has to be integers. The shape shall be (2, ntotact).

  • Extension n°2 (EXTNAME = 'INFLU') : it is a cube of images of the influence functions (called minimaps). All of them naturally have the same array size because they must form a 3D data cube. All of them must have the same sampling. All of them must be produced as if they originated from a larger common frame from which they would have been extracted by using slicing conventions (i.e. minimap[0:n, 0:n, k] = largebigFrame[ix:ix+n, iy:iy+n]). The shape of the minimap cube must be (n, n, ntotact).

  • Extension n°3 (EXTNAME = 'XPOS_YPOS') is required by compass. This a list of floating-point values of shape (2, ntotact) that indicates where is the physical position of the actuator. This is really a user-defined value. Indeed, this value is not necessarily corresponding to the peak of the influence function, nor to the centre of the minimap. It is related to where the user considers that the “actuator centre” is. This set of data will populate the compass variable (xpos, ypos). If you do not know what to put in there, just set it to np.zeros((2, ntotact)).

COMPASS will read the extensions by identifying them thanks to their name (using the FITS keyword EXTNAME that has to be properly set) if the declared FITS version is 1.2 or sooner (see VERSIONkeyword below). COMPASS will read them according to their order (ix,iy first, then the cube of influence functions, then xpos,ypos) for older versions (1.1 and older).

Mandatory FITS header keywords

The user must define some parameters in the header of the fits file. Some of these parameters come with some unit: this will be the user’s own favourite unit: you are free to choose it. Example: you can choose meters [m], millimeters [mm], inches [in], or even no unit [] or else. We will note it [uu] for the sake of brevity, which stands for “user unit”.

  • VERSION : has to be set to 1.2
  • XCENTER, YCENTER : they are the coordinates of the centre of the global frame that compiles all the minimaps. The unit is array index, but this one can be a floating-point value as it is not intended to point towards some particular array cell, but to indicate a position.
  • PIXSIZE : size of the pixels of the maps, in your own favourite unit [uu] per pixel.

In each extension, the keyword EXTNAMEhas to be properly set

  • EXTNAME : has to be I1_J1, INFLU, and XPOS_YPOS, for the 3 extensions respectively.

Optional keywords

The optional keywords will allow you to map your DM onto the compass pupil. There are different cases depending on what you want to do. You may either want to set a particular pupil diameter, or impose a particular pitch.

  • PITCHM : size of the DM pitch in your own favourite unit [uu].
  • PUPM : size of what you consider to be the pupil diameter of your DM, in your own favourite unit [uu].

Notice that those keywords are optional, but it is advisable to set them anyway even if you don’t need them for your present application. Indeed, you may want to and care about the next user, who may have different needs from you. Having a custom DM fits file properly completed will allow the future users to operate any kind of manipulations.

Notice that you are also free to add your own keywords with own information, for user-related purposes. You may find some of the following keywords in some of the older DM files:

  • PITCHPX : size of the DM pitch, in pixels.
  • PUPPX : size of pupil diameter of your DM, in pixels.

Easy generation of custom DM FITS file

COMPASS has the perfect function for you. Open the file compass/shesha/shesha/util/dm_util.py and copy+use the function write_dm_custom_fits().

COMPASS parameter file

Now, some parameters shall be set in your compass parameter file to integrate your custom DM in your COMPASS simulation.

  • # nothing is set in compass: this is the default case. The DM will be stretched so that the value of the PUPM keyword matches the compass pupil (which you have defined using p_tel.set_diam())
  • p_dm.set_pitch(value) : this allows you to impose the pitch in the telescope pupil plane. Of course in that case you will be expected to have set the keyword PITCHM in the fits header.
  • p_dm.set_diam_dm(value) : you have set the PUPM keyword in your fits file to define what the pupil normally is, but you want now to indicate COMPASS that this value shall not be used because your DM is used in a special way. Or perhaps you have not set PUPM in the fits file. In any case you want to define, redefine, or override the PUPM value and use a new value instead. This new value must of course be set in the [uu] unit, the user-defined one that is used in the FITS file. This new value [uu] will be mapped onto the compass pupil (which you have defined using p_tel.set_diam()).
    • Example 1: the 4K Alpao DM is defined with a 93 mm nominal pupil (and this is written in the fits header as PUPM 93.0) but you want to use only the central 50 mm of it in your system, so you use p_dm.set_diam_dm(50.0). Then, the central 50.0 mm of it will automatically be mapped to the COMPASS pupil.
    • Example 2: the ELT DM has some influence functions defined but you have no idea what the pupil diameter is because there is no circular limit, no edge. The only thing you know is that the pixel scale PIXSIZE is correct because ESO has provided you with the influence functions expressed in M1 space. You just have to say that 40 meters must be mapped on 40 meters, i.e. p_dm.set_diam_dm(40.0).
  • p_dm.set_diam_dm_proj(value) : you have set the PUPM keyword in your fits file to define what the pupil normally is, and you want now to map this DM pupil on something with is not the default pupil diameter but something else
    • Example: the ALPAO 4K custom DM has a nominal pupil diameter of 93mm, you want to use it on a 4.2m telescope, but the DM surface is used on a larger surface, for instance on 5.89 m.

Known issues

  • Segmented mirrors : COMPASS will re-sample the influence functions according to the sampling grid that is used internally. If your influence functions contain some sharp edges or discontinuities (e.g. segmented mirror), then you may experience some trouble. The re-sampling may induce some kind of ringing close to discontinuities.
  • Shifting the DM : while many possibilities are given to re-scale the DM size, the custom DM cannot be translated laterally. The only way is to redefine its centre by modifying the keywords XCENTER and YCENTER in the FITS header.