Home > src > genericConstraint.m

# genericConstraint

## PURPOSE

- parent class for constraints

## SYNOPSIS

This is a script file.

## DESCRIPTION

     - parent class for constraints

     copyright 2009-2012 Blair Armstrong, Christine Watson, David Plaut

        This file is part of SOS

        SOS is free software: you can redistribute it and/or modify
        it for academic and non-commercial purposes
        under the terms of the GNU General Public License as published by
        the Free Software Foundation, either version 3 of the License, or
        (at your option) any later version.  For commercial or for-profit
        uses, please contact the authors (sos@cnbc.cmu.edu).

        SOS 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 General Public License for more details.

## CROSS-REFERENCE INFORMATION

This function calls:

- genericConstraint - parent class for constraints
- hardBoundConstraint - hard bound constraint object
- softDistanceConstraint - parent class for soft distance constraints
- softEntropyConstraint - soft entropy constraint object
- softMatchCorrelConstraint - soft correlation matching constraint object
- softMetaConstraint - parent class for soft meta-constraints

This function is called by:

- genericConstraint - parent class for constraints
- hardBoundConstraint - hard bound constraint object
- hardConstraint - parent class for hard constraints
- softConstraint - parent class for soft constraints
- softDistanceConstraint - parent class for soft distance constraints
- softEntropyConstraint - soft entropy constraint object
- softMatchCorrelConstraint - soft correlation matching constraint object
- softMetaConstraint - parent class for soft meta-constraints

## SUBFUNCTIONS

- function cost = acceptSwap(obj)
- function cost = rejectSwap(obj)
- function obj = createConstraint(varargin)

## SOURCE CODE

    0001 % - parent class for constraints
    0002 %
    0003 % copyright 2009-2012 Blair Armstrong, Christine Watson, David Plaut
    0004 %
    0005 %    This file is part of SOS
    0006 %
    0007 %    SOS is free software: you can redistribute it and/or modify
    0008 %    it for academic and non-commercial purposes
    0009 %    under the terms of the GNU General Public License as published by
    0010 %    the Free Software Foundation, either version 3 of the License, or
    0011 %    (at your option) any later version.  For commercial or for-profit
    0012 %    uses, please contact the authors (sos@cnbc.cmu.edu).
    0013 %
    0014 %    SOS is distributed in the hope that it will be useful,
    0015 %    but WITHOUT ANY WARRANTY; without even the implied warranty of
    0016 %    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    0017 %    GNU General Public License for more details.
    0018
    0019 %    You should have received a copy of the GNU General Public License
    0020 %    along with SOS (see COPYING.txt).
    0021 %    If not, see <http://www.gnu.org/licenses/>.
    0022
    0023
    0024 classdef genericConstraint < handle
    0025     % Class defines general functionality of constraint objects
    0026     %
    0027     %PROPERTIES
    0028     %     sosObj  % SOS object constraint is associated with
    0029     %     name % string name to associate with the object
    0030     %     label % label to associate with the object (e.g., containing additional information than in the name)
    0031     %     constraintType %label indicating type of constraint (hard/soft/meta)
    0032     %     fnc % name of function used to compute constraint
    0033     %     cost % current cost of constraint
    0034     %     swCost % cost if a swap was executed
    0035     %
    0036     %METHODS (Abstract)
    0037     %   cost = initCost() - object must be able to initially calculate cost
    0038     %   swCost = swapCost() - object must be able to calculate the cost of doing a swap
    0039     %
    0040     %METHODS
    0041     %   obj = acceptSwap() - Makes the swap cost the current cost
    0042     %   cost = rejectSwap(obj) %rejects the swap, resets swCost
    0043     %
    0044     %METHODS (Static)
    0045     %   obj = createConstraint(varargin) - creates an appropriate constraint given varagin
    0046
    0047
    0048     %%PROPERTIES
    0049     properties
    0050         sosObj  % SOS object constraint is associated with
    0051         name % string name to associate with the object
    0052         label % label to associate with the object (e.g., containing additional information than in the name)
    0053         constraintType %label indicating type of constraint (hard/soft/meta)
    0054         fnc % name of function used to compute constraint
    0055         cost % current cost of constraint
    0056         swCost % cost if a swap was executed
    0057     end
    0058
    0059     methods (Abstract)
    0060         cost = initCost(obj);
    0061         swCost = swapCost(obj);
    0062     end
    0063
    0064
    0065     methods
    0066
    0067         %% acceptSwap() METHOD
    0068         function cost = acceptSwap(obj)
    0069             %Makes the swap cost the current cost
    0070             %
    0071             %Child objects of genericConstraint may need to do additional
    0072             %computations in their own acceptSwap function
    0073
    0074             %Only swap if swCost is NaN, which should only be true if a
    0075             %given swap implicates this cost function
    0076             if(isnan(obj.swCost) == false)
    0077                 obj.cost = obj.swCost;
    0078                 obj.swCost = NaN;
    0079
    0080             end
    0081
    0082             cost = obj.cost;
    0083         end
    0084
    0085         %% rejectSwap() METHOD
    0086         function cost = rejectSwap(obj)
    0087             %rejects the swap, resets swCost
    0088             obj.swCost = NaN;
    0089             cost = obj.cost;
    0090         end
    0091     end
    0092
    0093
    0094     methods (Static)
    0095
    0096         %% obj = createConstraint(varargin)
    0097         function obj = createConstraint(varargin)
    0098             % creates an appropriate constraint given varagin
    0099             %
    0100             % Note: Parameters must pass both this function's minimal
    0101             % checking AND the checking required by the specific object to
    0102             % be created
    0103             %
    0104             %PARAMETERS:
    0105             %Required:
    0106             %   'sosObj'/sos object - the SOS object the constraint will be linked to, and which contains the samples the constraint operates on.
    0107             %   'constraintType'/<str name of constraint as required by desired constraint> - see desired obj's constructor for options
    0108             %   'fnc'/<str name of fnc as required by desired constraint> - see desired obj's constructor for options
    0109             %
    0110             %Optional:
    0111             %   <all required parameters for specific constraint>
    0112             %
    0113             %RETURNS:
    0114             %   Constraint object
    0115
    0116
    0117
    0118             %check the universal requirements of the method
    0119             p = inputParser;
    0120             p.KeepUnmatched = true;
    0121
    0122             p.addParamValue('sosObj','null',...
    0123                 @(sosObj)strcmp(class(sosObj),'sos'));
    0124             p.addParamValue('constraintType', 'null', ...
    0125                 @(constraintType)ischar(constraintType));
    0126             p.addParamValue('fnc','null', ...
    0127                  @(fnc)ischar(fnc));
    0128
    0129             p.parse(varargin{:});
    0130
    0131
    0132             %minimum information needed to try to create a constraint
    0133             %exists, try to create constraint
    0134
    0135             if strcmp(p.Results.constraintType, 'hard')
    0136                 if(strcmp(p.Results.fnc,'floor') || strcmp(p.Results.fnc,'ceiling'))
    0137                     obj = hardBoundConstraint(varargin{:});
    0138                 else
    0139                     error(['Could not create a hard constraint with <fnc>: ', ...
    0140                         p.Results.fnc]);
    0141                 end
    0142             elseif strcmp(p.Results.constraintType, 'soft')
    0143                 if(strcmp(p.Results.fnc,'min') || ...
    0144                         strcmp(p.Results.fnc,'max') || ...
    0145                         strcmp(p.Results.fnc,'orderedMax') || ...
    0146                         strcmp(p.Results.fnc,'match1SampleVal'))
    0147
    0148                     obj = softDistanceConstraint(varargin{:});
    0149
    0150                 elseif(strcmp(p.Results.fnc,'minEnt') || ...
    0151                         strcmp(p.Results.fnc,'maxEnt'))
    0152                     obj = softEntropyConstraint(varargin{:});
    0153                 elseif(strcmp(p.Results.fnc,'matchCorrel'))
    0154                     obj = softMatchCorrelConstraint(varargin{:});
    0155                 else
    0156                     error(['Could not create a soft constraint with <fnc>: ', ...
    0157                         p.Results.fnc]);
    0158                 end
    0159
    0160             elseif strcmp(p.Results.constraintType, 'meta')
    0161                 if(strcmp(p.Results.fnc,'matchCost') || ...
    0162                         strcmp(p.Results.fnc,'matchCostNotMin') )
    0163                     obj = softMetaConstraint(varargin{:});
    0164                 else
    0165                     error(['Could not create a meta constraint with <fnc>: ', ...
    0166                         p.Results.fnc]);
    0167                 end
    0168             else
    0169                error('The type of the new constraint is not supported in genericConstraint.  Supported types are hard/soft/meta');
    0170             end
    0171
    0172         end %createConstraint
    0173     end
    0174
    0175
    0176 end
    0177