Description of slenforce

Home > sltoolbox > core > slenforce.m

slenforce

PURPOSE

SLENFORCE Enforce some property on the array A

SYNOPSIS

function Ae = slenforce(A, varargin)

DESCRIPTION

SLENFORCE Enforce some property on the array A

 $ Syntax $
   - Ae = slenforce(A, <property>)
   - Ae = slenforce(A, <property1>, <property2>, ...)
   - Ae = slenforce(A, {<property1>, <property2>, ...})

 $ Description $
   - Ae = slenforce(A, <property>) enforces the property to the matrix A.

   - Ae = slenforce(A, <property1>, <property2>, ...) enforces a set of 
     properties to the matrix A. It is equivalent to 
     Ae = slenforce(A, {<property1>, <property2>, ...}), where the
     properties are grouped in a cell form.

   - The properties are listed in following table
     \*
     \t  Table 1.  The properties that can be enforced              \\
     \h    name         &     description                           \\
          'real'        &     All values are real                   \\
          'positive'    &     All values are positive               \\
          'negative'    &     All values are negative               \\
          'nonpos'      &     All values are non-positive           \\
          'nonneg'      &     All values are non-negative           \\
          'symmetric'   &     Matrices are symmetric                \\
     \*

 $ Remarks $
   # A can be numeric array of any dimensions. For arrays with dimensions
     higher than 2D, 'symmetric' property is enforced to each page.
   # slenforce(A, 'positive') is equivalent to slconfine(A, eps, inf); 
     slenforce(A, 'negative') is equivalent to slconfine(A, -inf, -eps);
     slenforce(A, 'nonpos') is equivalent to slconfine(A, -inf, 0);
     slenforce(A, 'nonneg') is equivalent to slconfine(A, 0, inf);

 $ History $
   - Created by Dahua Lin on Nov 18th, 2005

CROSS-REFERENCE INFORMATION

This function calls:

• slconfine SLCONFINE Confines the values in a range
• raise_lackinput RAISE_LACKINPUT Raises an error indicating lack of input argument

This function is called by:

• slnormalize SLNORMALIZE Normalize the sub-arrays

SOURCE CODE

0001 function Ae = slenforce(A, varargin)
0002 %SLENFORCE Enforce some property on the array A
0003 %
0004 % $ Syntax $
0005 %   - Ae = slenforce(A, <property>)
0006 %   - Ae = slenforce(A, <property1>, <property2>, ...)
0007 %   - Ae = slenforce(A, {<property1>, <property2>, ...})
0008 %
0009 % $ Description $
0010 %   - Ae = slenforce(A, <property>) enforces the property to the matrix A.
0011 %
0012 %   - Ae = slenforce(A, <property1>, <property2>, ...) enforces a set of
0013 %     properties to the matrix A. It is equivalent to
0014 %     Ae = slenforce(A, {<property1>, <property2>, ...}), where the
0015 %     properties are grouped in a cell form.
0016 %
0017 %   - The properties are listed in following table
0018 %     \*
0019 %     \t  Table 1.  The properties that can be enforced              \\
0020 %     \h    name         &     description                           \\
0021 %          'real'        &     All values are real                   \\
0022 %          'positive'    &     All values are positive               \\
0023 %          'negative'    &     All values are negative               \\
0024 %          'nonpos'      &     All values are non-positive           \\
0025 %          'nonneg'      &     All values are non-negative           \\
0026 %          'symmetric'   &     Matrices are symmetric                \\
0027 %     \*
0028 %
0029 % $ Remarks $
0030 %   # A can be numeric array of any dimensions. For arrays with dimensions
0031 %     higher than 2D, 'symmetric' property is enforced to each page.
0032 %   # slenforce(A, 'positive') is equivalent to slconfine(A, eps, inf);
0033 %     slenforce(A, 'negative') is equivalent to slconfine(A, -inf, -eps);
0034 %     slenforce(A, 'nonpos') is equivalent to slconfine(A, -inf, 0);
0035 %     slenforce(A, 'nonneg') is equivalent to slconfine(A, 0, inf);
0036 %
0037 % $ History $
0038 %   - Created by Dahua Lin on Nov 18th, 2005
0039 %
0040 
0041 %% parse and verify input arguments
0042 if nargin < 2
0043     raise_lackinput('slenforce', 2);
0044 end
0045 if ischar(varargin{1})
0046     P = varargin;
0047 elseif iscell(varargin{1})
0048     P = varargin{1};
0049 else
0050     error('sltoolbox:invalidarg', ...
0051         'The properties should be in strings or cell array of strings');
0052 end
0053 np = numel(P);
0054 for i = 1 : np
0055     if ~ischar(P{i})
0056         error('sltoolbox:nonstring', ...
0057             'Some property names are not given in form of string');
0058     end
0059 end
0060 
0061 %% enforce
0062 Ae = A;
0063 for i = 1 : np
0064     
0065     switch P{i}
0066         case 'real'
0067             if ~isreal(Ae)
0068                 Ae = real(Ae);
0069             end
0070             
0071         case 'positive'
0072             Ae = slconfine(Ae, eps, []);
0073             
0074         case 'negative'
0075             Ae = slconfine(Ae, [], -eps);
0076             
0077         case 'nonpos'
0078             Ae = slconfine(Ae, [], 0);
0079             
0080         case 'nonneg'
0081             Ae = slconfine(Ae, 0, []);
0082             
0083         case 'symmetric'
0084             Ae = (Ae + Ae') / 2;
0085             
0086         otherwise
0087             error('sltoolbox:invalidop', ...
0088                 'Unsupported property for slenforce: %s', P{i});
0089     end
0090     
0091 end
0092 
0093 
0094 
0095     
0096

---

Generated on Wed 20-Sep-2006 12:43:11 by m2html © 2003