Match

The match command provides a unified interface to several optimizer. It can be used to match optics parameters (its main purpose), to fit data sets with parametric functions in the least-squares sense, or to find local or global minima of non-linear problems. Most local methods support bounds, equalities and inequalities constraints. The least-squares methods are custom variant of the Newton-Raphson and the Gauss-Newton algorithms implemented by the LSopt module. The local and global non-linear methods are relying on the NLopt module, which interfaces the embedded NLopt library that implements a dozen of well-known algorithms.

Command synopsis

The match command format is summarized in Listing 5. including the default setup of the attributes.

Listing 5 Synopsis of the match command with default setup.

status, fmin, ncall = match {
        command         = function or nil,
        variables       = { variables-attributes,
                                { variable-attributes },
                                ..., more variable definitions, ...
                                { variable-attributes } },
        equalities      = { constraints-attributes,
                                { constraint-attributes },
                                ..., more equality definitions, ...
                                { constraint-attributes } },
        inequalities    = { constraints-attributes,
                                { constraint-attributes },
                                ..., more inequality definitions,...
                                { constraint-attributes } },
        weights         = { weights-list },
        objective       = {  objective-attributes },
        maxcall=nil,    -- call limit
        maxtime=nil,    -- time limit
        info=nil,       -- information level (output on terminal)
        debug=nil,      -- debug information level (output on terminal)
        usrdef=nil,     -- user defined data attached to the environment
}

The match command supports the following attributes:

command

A callable (e) that will be invoked during the optimization process at each iteration. (default: nil).

Example: command := twiss { twiss-attributes }.

variables

An mappable of single variable specification that can be combined with a set of specifications for all variables. (no default, required).

Example: variables = {{ var="seq.knobs.mq_k1" }}.

equalities

An mappable of single equality specification that can be combined with a set of specifications for all equalities. (default: {}).

Example: equalities = {{ expr=\t -> t.q1-64.295, name='q1' }}.

inequalities

An mappable of single inequality specification that can be combined with a set of specifications for all inequalities. (default: {}).

Example: inequalities = {{ expr=\t -> t.mq4.beta11-50 }}.

weights

A mappable of weights specification that can be used in the kind attribute of the constraints specifications. (default: {}).

Example: weights = { px=10 }.

objective

A mappable of specifications for the objective to minimize. (default: {}).

Example: objective = { method="LD_LMDIF", fmin=1e-10 }.

maxcall

A number specifying the maximum allowed calls of the command function or the objective function. (default: nil).

Example: maxcall = 100.

maxtime

A number specifying the maximum allowed time in seconds. (default: nil).

Example: maxtime = 60.

info

A number specifying the information level to control the verbosity of the output on the console. (default: nil).

Example: info = 3.

debug

A number specifying the debug level to perform extra assertions and to control the verbosity of the output on the console. (default: nil).

Example: debug = 2.

usrdef

Any user defined data that will be attached to the matching environment, which is passed as extra argument to all user defined functions in the match command. (default: nil).

Example: usrdef = { var=vector(15) }.

The match command returns the following values in this order:

status: A string corresponding to the status of the command or the stopping reason of the method. See Table 2 for the list of supported status.
fmin: A number corresponding to the best minimum reached during the optimization.
ncall: The number of calls of the command function or the objective function.

Table 2 List of `status` (*string*) returned by the `match` command.
`status`	Meaning
SUCCESS	Generic success (NLopt only, unlikely).
FMIN	`fmin` criteria is fulfilled by the objective function.
FTOL	`tol` or `rtol` criteria are fulfilled by the objective function.
XTOL	`tol` or `rtol` criteria are fulfilled by the variables step.
MAXCALL	`maxcall` criteria is reached.
MAXTIME	`maxtime` criteria is reached.
ROUNDOFF	Round off limited iteration progress, results may still be useful.
STOPPED	Termination forced by user, i.e. `{env.stop = true}`.
Errors
FAILURE	Generic failure (NLopt only, unlikely).
INVALID_ARGS	Invalid argument (NLopt only, unlikely).
OUT_OF_MEMORY	Ran out of memory (NLopt only, unlikely).

Environment

The match command creates a matching environment, which is passed as argument to user’s functions invoked during an iteration. It contains some useful attributes that can be read or changed during the optimization process (with care):

ncall: The current number of calls of the command and/or the objective functions.
dtime: A number reporting the current elapsed time.
stop: A logical stopping the match command immediately if set to true.
info: The current information level \(\geq 0\).
debug: The current debugging level \(\geq 0\).
usrdef: The usrdef attribute of the match command or nil.
command: The command attribute of the match command or nil.
variables: The variables attribute of the match command.
equalities: The equalities attribute of the match command or {}.
inequalities: The inequalities attribute of the match command or {}.
weights: The weights attribute of the match command or {}.

Command

The attribute command (default: nil) must be a callable (e) that will be invoked with the matching environment as first argument during the optimization, right after the update of the variables to their new values, and before the evaluation of the constraints and the objective function. (default: nil).

command = function or nil

The value returned by command is passed as the first argument to all constraints. If this return value is nil, the match command considers the current iteration as invalid. Depending on the selected method, the optimizer can start a new iteration or stop.

A typical command definition for matching optics is a function that calls a twiss command [1] :

command := mchklost( twiss { twiss-attributes } )

where the function mchklost surrounding the twiss command checks if the returned mtable (i.e. the twiss table) has lost particles and returns nilinstead:

mchklost = \mt -> mt.lost == 0 and mt or nil

The function mchklost [2] is useful to avoid that all constraints do the check individually.

Variables

The attribute variables (no default, required) defines the variables that the command match will update while trying to minimize the objective function.

variables = { variables-attributes,
  { variable-attributes  },
  ... ,more variable definitions, ...
  { variable-attributes  } }

The variable-attributes is a set of attributes that specify a single variable:

var

A string specifying the identifier (and indirection) needed to reach the variable from the user’s scope where the match command is defined. (default: nil).

Example: var = "lhcb1.mq_12l4_b1.k1".

name

A string specifying the name of the variable to display when the info level is positive. (default: var).

Example: name = "MQ.12L4.B1->k1".

min

A number specifying the lower bound for the variable. (default: -inf ).

Example: min = -4.

max

A number specifying the upper bound for the variable. (default: +inf ).

Example: max = 10.

sign

A logical enforcing the sign of the variable by moving min or max to zero depending on the sign of its initial value. (default: false).

Example: sign = true.

slope

A number enforcing (LSopt methods only) with its sign the variation direction of the variable, i.e. positive will only increase and negative will only decrease. (default: 0 ).

Example: slope = -1.

step

A small positive number used to approximate the derivatives using the Derivatives method. If the value is not provided, the command will use some heuristic. (default: nil).

Example: step = 1e-6.

tol

A number specifying the tolerance on the variable step. If an update is smaller than tol, the command will return the status "XTOL". (default: 0).

Example: tol = 1e-8.

get

A callable (e) returning the variable value as a number, optionally using the matching environment passed as first argument. This attribute is required if the variable is local or an upvalue to avoid a significant slowdown of the code. (default: nil).

Example: get := lhcb1.mq_12l4_b1.k1.

set

A callable (v, e) updating the variable value with the number passed as first argument, optionally using the matching environment passed as second argument.This attribute is required if the variable is local or an upvalue to avoid a significant slowdown of the code. (default: nil).

Example: set = \v,e => lhcb1.mqxa_1l5.k1 = v*e.usrdef.xon end.

The variables-attributes is a set of attributes that specify all variables together, but with a lower precedence than the single variable specification of the same name unless otherwise specified:

min