Contents

MORLAB Demo: Option Constructor Function ml_morlabopts

This demo script contains the application of the option constructor function ml_morlabopts and some hints for proper usage.

%
% This program is free software: you can redistribute it and/or modify
% it under the terms of the GNU Affero General Public License as published
% by the Free Software Foundation, either version 3 of the License, or
% (at your option) any later version.
%
% This program is distributed in the hope that it will be useful,
% but WITHOUT ANY WARRANTY; without even the implied warranty of
% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
% GNU Affero General Public License for more details.
%
% You should have received a copy of the GNU Affero General Public License
% along with this program.  If not, see <http://www.gnu.org/licenses/>.
%
% Copyright (C) 2006-2019 Peter Benner, Steffen W. R. Werner
%

General Syntax

In principal, the function ml_morlabopts is the option constructor of the MORLAB toolbox and can be used for any MORLAB function or datafile. The function fulfills two aims:

  1. documentation of all possible optional parameters of MORLAB functions
  2. construction of empty option structs that can be filled by the user

The disctinction of both cases is made by the calling syntax, i.e., calling ml_morlabopts with no output argument leads to the documentation of the requested function, while asking for an output argument creates an empty version of the option struct of the requested function. Both cases are further explained below.

No Output Argument: Optional Parameter Documentation

As mentioned above, this way of using ml_morlabopts gives a documentation of the possible optional parameters. The general syntax is as follows

ml_morlabopts('name_of_a_MORLAB_function')

where name_of_a_MORLAB_function determines the requested function. As an example, we want the documentation of the optional parameters of the ml_ct_ss_bt function by using

ml_morlabopts('ml_ct_ss_bt');
       lyapdlopts: [ 1x1 struct | {ml_morlabopts('ml_lyapdl_sgn_fac')} ]
           Method: [ 'bfsr' | {'sr'} ]
            Order: [ positive integer | {min(10,length(Hsv)) + Nu} ]
 OrderComputation: [ 'order' | {'tolerance'} ]
    stabsignmopts: [ 1x1 struct | {ml_morlabopts('ml_signm')} ]
     stabsylvopts: [ 1x1 struct | {ml_morlabopts('ml_sylv_sgn')} ]
  StoreProjection: [ 1 | {0} ]
        Tolerance: [ nonnegative scalar | {1.0e-02} ]
        UnstabDim: [ integer | {-1} ]

 For more details see ml_ct_ss_bt.

This gives as screen output all optional parameters of the function, as well as descriptions of the admissible data types, e.g., the parameter StoreProjection is only allowed to be boolean and Tolerance can be a scalar value, which is nonnegative. The internal used default values are show in curly brackets {}. Note that the fields stabsignmopts and stabsylvopts have an additional call of ml_morlabopts as default value, which means that those fields are option structs of other functions that are used inside of the requested function.

In case a MORLAB function doesn't support option structs, the user will be informed by a sentence. For example calling

ml_morlabopts('ml_field_set_to_value')

won't show any parameters but that the hint that there is no option struct used by the requested function.

ml_morlabopts('ml_field_set_to_value');
 The requested function doesn't use an option struct!

 For more details see ml_field_set_to_value.

One Output Argument: Option Struct Construction

Requesting an output argmuent of ml_morlabopts will change the behavior of the function from documenting the optional parameters to creating empty versions of the appropriate option structs of a function.

We start with a simple example. To create an option struct of the function ml_lyap_sgn we used need to use

opts = ml_morlabopts('ml_lyap_sgn');

This will create the empty option struct with all the fields that can be used as optional parameters for the ml_lyap_sgn function. If we take a look inside the struct

disp(opts);
     AbsTol: []
       Info: []
    MaxIter: []
     RelTol: []

We see that all fields are empty. That will cause any MORLAB function to use default values that are determined during the function call. To use a different optional parameter value than the default one, just change the empty array to a suitable value. As example, we want to change the tolerance for the relative solution error of ml_lyap_sgn to 1.0e-10. Therefore, we set

opts.RelTol = 1.0e-10;

MORLAB supports the complete customization of all subroutines used inside the model reduction methods by nested option structs.

opts = ml_morlabopts('ml_ct_ss_bt');

creates the option struct for the standard balanced truncation function. If we take a closer look

disp(opts);
          lyapdlopts: [1x1 struct]
              Method: []
               Order: []
    OrderComputation: []
       stabsignmopts: [1x1 struct]
        stabsylvopts: [1x1 struct]
     StoreProjection: []
           Tolerance: []
           UnstabDim: []

we see that beside empty arrays the struct contains also 1x1 structs for fields, which end on opts. Those structs contain the optional parameters for subroutines used inside the function, e.g.,

disp(opts.lyapdlopts)
     AbsTol: []
    CompTol: []
       Info: []
    MaxIter: []
     RelTol: []

contains the optional parameters for the dual Lyapunov equation solver that is used inside the balanced truncation method.

For functions that doesn't support option structs, the result of ml_morlabopts will just be an empty struct, e.g.,

opts = ml_morlabopts('ml_field_set_to_value');

See Also

ml_morlabopts