% H2SYN_LMI_OPTIONS
% Produces a struct containing options for h2syn_lmi and similar functions.
%
% SPDX-FileCopyrightText: 2023 Deutsches Elektronen-Synchrotron DESY, MSK, LbSync <lbsync-expert@desy.de>
% SPDX-License-Identifier: GPL-3.0-or-later
%
% Author: Maximilian Schütte <maximilian.schuette@desy.de>

function h2syn_lmi_opts = h2syn_lmi_options(options)
    arguments
        % Force definitness constraints to satisfy this margin.
        options.tolerance (1, 1) double {mustBeNonnegative} = 1e-9

        % Enforce synthesized controller to be strictly proper.
        options.enforce_strictly_proper (1, 1) logical = false

        % Enfroce closed-loop poles to have absolute value no larger than the specified number. *Adds conservatism*
        options.maximum_frequency (1, 1) double {mustBeNonnegative} = inf

        % Enforce closed-loop poles to have a damping ratio larger than the specified number. *Adds conservatism.*
        options.minimum_damping (1, 1) double {mustBeInRange(options.minimum_damping, 0, 1, 'exclude-upper')} = 0

        % Enforce closed-loop poles to have absolute real part greater than the specified number. *Adds conservatism.*
        options.minimum_decay (1, 1) double {mustBeNonnegative} = 0

        % Enforce closed-loop poles to have absolute real part smaller than the specified number. *Adds conservatism.*
        options.maximum_decay (1, 1) double {mustBeNonnegative} = inf

        % Eliminate as many linearization variables as possible, may increase performance on large problems, but also
        % deteriorate numerical properties of the problem.
        options.eliminate_variables (1, 1) logical = true

        % Factor by which to relax the determined optimal h2 performance bound.
        options.relaxation_factor (1, 1) double {mustBeGreaterThanOrEqual(options.relaxation_factor, 1)} = 1

        % Factor by which to relax the determined minimal norm on the linearization
        % variables.
        options.regularization_factor (1, 1) double {mustBeGreaterThanOrEqual(options.regularization_factor, 1)} = 1

        % Factor by which to weigh the norm over all optimization variables against
        % the h2 performance bound in the cost to be optimized.
        options.norm_cost_factor (1, 1) double {mustBeNonnegative} = 0

        % Hard bound to be imposed on the Lypaunov matrix variable.
        options.norm_bound (1, 1) double {mustBePositive} = inf

        % Hard absolute bound to be imposed on each optimization variable.
        options.variable_bound (1, 1) double {mustBePositive} = inf

        % Add constraint that the optimal h2 performance bound should be smaller than this value.
        options.hard_bound (1, 1) double {mustBePositive} = inf

        % Optionally disable minimization of gamma, requires hard_bound to be set.
        options.minimize_gamma (1, 1) logical = true

        % Scale system for possibly better numerics using minimization of
        % riccati equation sensitivity as in h2syn.
        options.scale (1, 1) logical = false

        % YALMIP options.
        options.sdp_options (1, 1) struct = sdpsettings()
    end

    h2syn_lmi_opts = options;
end
