This article provides a brief explanation on how to use the OPEV() and OPEW() functions in a ZPL macro to obtain a value that would otherwise be given by a merit function operand.

Authored By Sanjay Gangadhara

Introduction

ZPL macros provide a powerful tool for performing analysis on your system. In many cases, the macro may need input information that would normally be obtained from one of the merit function operands - even an operand that you're not currently using. So how does one obtain the data that would be provided by one of these operands inside of a macro? One way is to use the OPEV() and OPEW() functions.

When an operand's code is passed to these funcitons, OPEV() and OPEW() return the data that would be provided by an optimization operand without having to add the operand to the merit function. The desired code may be obtained using the OCOD() function.

This article will provide examples of using each of these functions. 

OPEV() example

Imagine that we wanted to determine the centroid locations for a spot inside of a ZPL macro. The merit function operands we would use to get this data are CENX and CENY. The inputs to each operand are the Surface Number, the Wave Number, the Field Number, a “Use Polarization?” flag and the Sampling grid size, as indicated in the help file:

The Optimize Tab (sequential ui mode)...Automatic Optimization Group...Merit Function Editor (automatic optimization group)...Optimization Operands (Alphabetically)

Although this is not required for using the OPEV() function, we can confirm the order in which the data are provided to the operands by looking at the operands in the merit function editor:

To obtain data from each of these operands in a macro – without placing the operands in the merit function editor – we would use the following syntax:

C1 = OCOD("CENX")  # Obtain the code associated with the

#   CENX operand

C2 = OCOD("CENY")  # Obtain the code associated with the

#   CENY operand

Surf_num = 7       # Surface number at which we require

#   the data

Wave_num = 2       # Wavelength number at which we require

#   the data

Field_num = 1      # Field number at which we require

#   the data

Pol_flag = 0       # if 0, polarization is ignored; 

#   if 1, polarization is accounted for

Samp_val = 5       # Sampling grid used by calculation


! Obtain centroid values using OPEV

V1 = OPEV(C1, Surf_num, Wave_num, Field_num, Pol_flag, Samp_val, 0)

V2 = OPEV(C2, Surf_num, Wave_num, Field_num, Pol_flag, Samp_val, 0)

The first two lines of the macro are used to obtain the codes associated with the CENX and CENY operands. The next set of lines are used to define the input values for those parameters that need to be passed to the operand (this step is not strictly necessary – you could just enter the numeric values directly into the OPEV() function call – but is done for completeness of the illustration). Then we obtain the desired values using two calls to the OPEV() function – one for CENX (code given by C1) and one for CENY (code given by C2).

We can see that OPEV() always requires 6 numeric inputs after the code value, even though most optimization operands do not require 6 inputs; for example, CENX and CENY only need 5 inputs. In cases where the number of inputs to the operand is less than 6, we simply set the value for any “unused” inputs to zero (e.g. input #6 to OPEV is set to zero in the above macro).

It is important to note that the order in which the input is specified to OPEV() directly corresponds the column number of the input in the merit function editor. For example, with the merit function operand DXDY, the first column is blank:

To replicate the inputs provided in the above merit function inside of a call to OPEV(), the first input value would therefore be set to zero, as this is an “unused” input:

C = OCOD("DXDY")

V = OPEV(C, 0, 2, 0, 1, 0, 1)

OPEW() example

There are a handful of merit function operands for which 6 inputs is not sufficient – one example is DENC, which requires 8 inputs:

Again, the order of the inputs is determined by viewing this operand in the merit function editor:

In this case, OPEV() will not work, but instead the OPEW() function should be used:

C = OCOD("DENC")  # Obtain the code associated with the

#   DENC operand

Samp_val = 3      # Pupil sampling (1 = 32x32, 2 = 64x64,

#   etc.)

Wave_num = 2      # Wavelength number at which we require

#   the data

Field_num = 1     # Field number at which we require

#   the data

Frac_val = 0.99   # Fraction of encircled energy that we

#   want distance to

Type = 1          # 1 = encircled, 2 = x, 3 = y, 

#   4 = ensquared

Refp = 1          # Reference point/algorithm (see help files)

I_Samp = 0        # Huygens image sampling (for Huygens

#   algorithm)

I_Delta = 0       # Huygens image delta (for Huygens

#   algorithm)

! Obtain distance to desired encircled energy point

! using OPEW

V = OPEW(C, Samp_val, Wave_num, Field_num, Frac_val, Type, Refp, I_Samp, I_Delta)

Again, if there are any “unused” inputs for the operand, these input values passed to OPEW() should be zero.

KA-01482