Description of install

0001 function succ = install_matpower(modify, save_it, verbose, rm_oldpaths)
0002 %INSTALL_MATPOWER  Assist the user in setting their path.
0003 %   INSTALL_MATPOWER
0004 %   INSTALL_MATPOWER(MODIFY)
0005 %   INSTALL_MATPOWER(MODIFY, SAVE_IT)
0006 %   INSTALL_MATPOWER(MODIFY, SAVE_IT, VERBOSE)
0007 %   INSTALL_MATPOWER(MODIFY, SAVE_IT, VERBOSE, RM_OLDPATHS)
0008 %   SUCCESS = INSTALL_MATPOWER(...)
0009 %
0010 %   Assists the user in setting up the proper MATLAB/Octave path to
0011 %   be able to use MATPOWER and run its tests. With no input arguments
0012 %   it prompts interactively to determine how to handle the paths.
0013 %
0014 %   Inputs (all are optional):
0015 %       MODIFY : select how to set path
0016 %           0 (default) - generate relevant ADDPATH() commands, but
0017 %               don't execute them
0018 %           1 - modify the path directly executing the relevant
0019 %               ADDPATH() commands
0020 %       SAVE_IT : indicates whether or not to save the results
0021 %           0 or [] (default) - don't save any results
0022 %           if MODIFY is 0
0023 %               SAVE_IT = <string> : the relevant ADDPATH() commands
0024 %                   are saved to a file whose name is provided in SAVE_IT
0025 %               SAVE_IT = <other true value> : the relevant ADDPATH() commands
0026 %                   are saved to a file named 'startup.m' in the current
0027 %                   directory
0028 %               otherwise : the commands are displayed, but not saved
0029 %           if MODIFY is 1
0030 %               SAVE_IT = <any true value> : the path will be modified
0031 %                   and saved with SAVEPATH
0032 %               otherwise : the path will be modified but not saved
0033 %       VERBOSE : prints the relevant ADDPATH commands if true (default),
0034 %               silent otherwise
0035 %       RM_OLDPATHS : remove existing installation
0036 %           0 (default) - do NOT remove existing MATPOWER from path
0037 %           1 - remove existing MATPOWER paths first
0038 %
0039 %   Outputs (all are optional):
0040 %       SUCCESS : 1 if all commands succeeded, 0 otherwise
0041 %
0042 %   Examples:
0043 %       install_matpower;           %% print the required ADDPATH() commands
0044 %       install_matpower(0, 1);     %% save the commands to startup.m
0045 %       install_matpower(1, 1);     %% modify my path and save
0046 %       install_matpower(1, 0, 0);  %% modify my path temporarily and silently
0047 %       install_matpower(0, 'matpower6');   %% save the commands to matpower6.m
0048 %       install_matpower(0, 0, 1, 1);   %% uninstall MATPOWER from path
0049 %                                   %% (must call SAVEPATH separately
0050 %                                   %%  to make permanent)
0051 %
0052 %   See also ADDPATH, SAVEPATH.
0053 
0054 %   MATPOWER
0055 %   Copyright (c) 2017, Power Systems Engineering Research Center (PSERC)
0056 %   by Ray Zimmerman, PSERC Cornell
0057 %
0058 %   This file is part of MATPOWER.
0059 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0060 %   See https://matpower.org for more info.
0061 
0062 %% installation data for each component
0063 min_ver.Octave = '4.0.0';
0064 min_ver.MATLAB = '7.3.0';
0065 install = struct( ...
0066     'name', { ...
0067         'matpower', ...
0068         'mips', ...
0069         'most', ...
0070         'mptest', ...
0071         'maxloadlim', ...
0072         'misc', ...
0073         'reduction', ...
0074         'sdp_pf', ...
0075         'se', ...
0076         'smartmarket', ...
0077         'state_estimator', ...
0078         'syngrid' }, ...
0079     'dirs', { ...
0080         {{'lib'}, {'lib', 't'}, {'data'}}, ...
0081         {{'mips', 'lib'}, {'mips', 'lib', 't'}}, ...
0082         {{'most', 'lib'}, {'most', 'lib', 't'}}, ...
0083         {{'mptest', 'lib'}, {'mptest', 'lib', 't'}}, ...
0084         {{'extras', 'maxloadlim'}, {'extras', 'maxloadlim', 'tests'}, ...
0085             {'extras', 'maxloadlim', 'examples'}}, ...
0086         {{'extras', 'misc'}}, ...
0087         {{'extras', 'reduction'}}, ...
0088         {{'extras', 'sdp_pf'}}, ...
0089         {{'extras', 'se'}}, ...
0090         {{'extras', 'smartmarket'}}, ...
0091         {{'extras', 'state_estimator'}}, ...
0092         {{'extras', 'syngrid', 'lib'}, {'extras', 'syngrid', 'lib', 't'}} }, ...
0093     'fcns', { ...
0094         {'mpver', 'test_matpower', 'case9'}, ...
0095         {'mipsver', 'test_mips'}, ...
0096         {'mostver', 'test_most'}, ...
0097         {'t_begin', 'test_mptest'}, ...
0098         {'maxloadlim', 'test_mll_main', 'example_ieee9.m'}, ...
0099         {'checklimits'}, ...
0100         {'MPReduction'}, ...
0101         {'sdp_pf_ver'}, ...
0102         {'run_se'}, ...
0103         {'runmarket'}, ...
0104         {'runse'}, ...
0105         {'syngrid', 'test_syngrid'} } ...
0106 );
0107 ni = length(install);   %% number of components
0108 
0109 %% default arguments
0110 interactive = 0;
0111 if nargin < 4
0112     rm_oldpaths = 0;
0113     if nargin < 3
0114         verbose = 1;
0115         if nargin < 2
0116             save_it = 0;
0117             if nargin < 1
0118                 modify = [];
0119                 interactive = 1;
0120             end
0121         end
0122     end
0123 end
0124 
0125 %% get path to new MATPOWER installation root
0126 [root, n, e] = fileparts(which('install_matpower'));
0127 
0128 %% MATLAB or Octave
0129 if exist('OCTAVE_VERSION', 'builtin') == 5
0130     sw = 'Octave';
0131 else
0132     sw = 'MATLAB';
0133 end
0134 
0135 %% check for required version of MATLAB or Octave
0136 vstr = '';
0137 switch sw
0138     case 'Octave'
0139         v = ver('octave');
0140     case 'MATLAB'
0141         v = ver('matlab');
0142         if length(v) > 1
0143             warning('The built-in VER command is behaving strangely, probably as a result of installing a 3rd party toolbox in a directory named ''matlab'' on your path. Check each element of the output of ver(''matlab'') to find the offending toolbox, then move the toolbox to a more appropriately named directory.');
0144             v = v(1);
0145         end
0146 end
0147 if ~isempty(v) && isfield(v, 'Version') && ~isempty(v.Version)
0148     vstr = v.Version;
0149     if vstr2num(vstr) < vstr2num(min_ver.(sw))
0150         error('\n\n%s\n  MATPOWER requires %s %s or later.\n      You are using %s %s.\n%s\n\n', repmat('!',1,45), sw, min_ver.(sw), sw, vstr, repmat('!',1,45));
0151     end
0152 else
0153     warning('\n\n%s\n  Unable to determine your %s version. This indicates\n  a likely problem with your %s installation.\n%s\n', repmat('!',1,60), sw, sw, repmat('!',1,60));
0154 end
0155 
0156 
0157 %% get installation options interactively, if necessary
0158 div_line = sprintf('\n-------------------------------------------------------------------\n\n');
0159 if interactive
0160     fprintf(div_line);
0161     fprintf('MATPOWER Installation Options:\n\n');
0162     fprintf('   1. Do NOT modify the %s path\n', sw);
0163     fprintf('          (just generate the required ADDPATH commands)\n');
0164     fprintf('   2. DO modify the %s path, but only temporarily\n', sw);
0165     fprintf('          (you will have to do it again next time you run %s)\n', sw);
0166     fprintf('   3. DO modify the %s path, and SAVE the updated path\n', sw);
0167     fprintf('          (so you will not have to do it again next time you run %s)\n\n', sw);
0168     s = 0;
0169     while ~isempty(s) && (s < 1 || s > 3 || rem(s, 1))
0170         s = str2num(input('Please enter your selection [1, 2, 3] (default = 1) : ', 's'));
0171     end
0172     if isempty(s)
0173         s = 1;              %% default to option 1
0174     end
0175     switch s
0176         case 1              %% don't modify
0177             modify = 0;
0178         case 2              %% modify, don't save
0179             modify = 1;
0180             save_it = 0;
0181         case 3              %% modify and save
0182             modify = 1;
0183             save_it = 1;
0184         otherwise
0185     end
0186 end
0187 
0188 %% find available new components
0189 available = zeros(ni, 1);
0190 for i = 1:ni
0191     if exist(fullfile(root, install(i).dirs{1}{:}), 'dir')
0192         available(i) = 1;
0193     end
0194     % fprintf('%d %s\n', available(i), fullfile(root, install(i).dirs{:}));
0195 end
0196 
0197 %% find paths for currently installed components
0198 oldpaths = {};
0199 for i = 1:ni
0200     if available(i)     %% only if we have a new replacement
0201         for k = 1:length(install(i).fcns)
0202             [p, n, e] = fileparts(which(install(i).fcns{k}));
0203             if ~isempty(p) && ~ismember(p, oldpaths)
0204                 oldpaths{end+1} = p;
0205             end
0206         end
0207     end
0208 end
0209 
0210 if ~isempty(oldpaths)
0211     if exist('mpver', 'file')
0212         v = mpver;
0213     else
0214         v = '';
0215     end
0216     str = sprintf('It appears you already have MATPOWER %s or some of its\n', v);
0217     str = sprintf('%scomponents installed in the following directories:\n\n', str);
0218     rm_path_str = '';
0219     for k = 1:length(oldpaths)
0220         rm_path_str = sprintf('%s    %s\n', rm_path_str, oldpaths{k});
0221     end
0222     if interactive
0223         fprintf(div_line);
0224         fprintf('%s%s\n', str, rm_path_str);
0225         fprintf('Unless you are sure you know what you are doing, we recommend\n');
0226         fprintf('removing these directories from your %s path before proceeding.\n\n', sw);
0227         s = '?';
0228         while ~isempty(s) && (s(1) ~= 'Y' && s(1) ~= 'N')
0229             s = upper(input('Would you like me to do it for you? [Y or N] (default = N) : ', 's'));
0230         end
0231         if isempty(s)
0232             s = 'N';                %% default to N
0233         end
0234         if s(1) == 'Y'
0235             rm_oldpaths = 1;
0236         end
0237     elseif ~rm_oldpaths
0238         error('install_matpower: %s%s\nPlease remove the old installation first, or re-run\nINSTALL_MATPOWER in interactive mode (no arguments).', str, rm_path_str);
0239     end
0240 end
0241 
0242 %% remove old paths
0243 if rm_oldpaths
0244     rmpath(oldpaths{:});
0245     if verbose
0246         fprintf(div_line);
0247         fprintf('The following directories were removed from your %s path:\n\n%s\n', sw, rm_path_str);
0248         if ~modify
0249             fprintf('You will need to manually use SAVEPATH to make the changes permanent.\n');
0250             s = input('Hit any key to continue ...', 's');
0251         end
0252     end
0253 end
0254 
0255 %% generate paths to add
0256 newpaths = {};
0257 for i = 1:ni
0258     if available(i)     %% only available components
0259         for k = 1:length(install(i).dirs)
0260             p = fullfile(root, install(i).dirs{k}{:});
0261             if ~isempty(p) && ~ismember(p, newpaths)
0262                 newpaths{end+1} = p;
0263             end
0264         end
0265     end
0266 end
0267 
0268 %% build addpath string
0269 cmd = sprintf('addpath( ...\n');
0270 for k = 1:length(newpaths)
0271     cmd = sprintf('%s    ''%s'', ...\n', cmd, newpaths{k});
0272 end
0273 cmd = sprintf('%s    ''%s'' );\n', cmd, '-end');
0274 
0275 %% print addpath
0276 if verbose
0277     fprintf(div_line);
0278     if modify
0279         fprintf('Your %s path will be updated using the following command:\n\n%s', sw, cmd);
0280         if interactive
0281             s = input(sprintf('\nHit any key to continue ...'), 's');
0282         end
0283     else
0284         fprintf('Use the following command to add MATPOWER to your %s path:\n\n%s\n', sw, cmd);
0285     end
0286 end
0287 
0288 %% add the new paths
0289 if modify
0290     addpath(newpaths{:}, '-end');
0291     if verbose
0292         fprintf('Your %s path has been updated.\n', sw);
0293     end
0294 end
0295 
0296 %% prompt about saving the command to a file
0297 if interactive && ~modify
0298     s = '?';
0299     while ~isempty(s) && (s(1) ~= 'Y' && s(1) ~= 'N')
0300         s = upper(input('Would you like to save this command to a file? [Y or N] (default = N) : ', 's'));
0301     end
0302     if isempty(s)
0303         s = 'N';                %% default to N
0304     end
0305     if s(1) == 'Y'
0306         %% prompt for file name
0307         s = '?';
0308         while ~isempty(s) && s(1) == '?'
0309             s = input('Please enter the name of file? (default = ''startup.m'') : ', 's');
0310         end
0311         if isempty(s)
0312             s = 'startup.m';    %% default to 'startup.m'
0313         end
0314         save_it = s;
0315     else
0316         save_it = 0;
0317     end
0318 end
0319 
0320 %% save path
0321 success = 1;
0322 if save_it
0323     if modify                   %% modify the path directly
0324         savepath;                   %% save the updated path
0325         if verbose
0326             fprintf(div_line);
0327             fprintf('Your updated %s path has been saved using SAVEPATH.\n', sw);
0328         end
0329     else                        %% don't modify the path directly
0330         %% set up file name
0331         if ~ischar(save_it)
0332             save_it = 'startup.m';
0333         end
0334         [p, n, e] = fileparts(save_it);
0335         if isempty(e)
0336             e = '.m';
0337         end
0338         fn = fullfile(p, [n e]);
0339 
0340         %% write file
0341         if exist(fn, 'file')        %% file exists, print a warning
0342             if verbose
0343                 fprintf(div_line);
0344                 fprintf('The file ''%s'' was not written. A file with that name already exists.', fn);
0345             else
0346                 error('install_matpower: file ''%s'' not written, a file with that name already exists', fn);
0347             end
0348         else                        %% create the file
0349             fid = fopen(fn, 'a');
0350             if fid == -1
0351                 success = 0;
0352             else
0353                 fprintf(fid, '%%%s\n\n', upper(n));
0354                 fprintf(fid, '%%%% add MATPOWER paths\n');
0355                 fprintf(fid, '%s', cmd);
0356                 fclose(fid);
0357             end
0358             if verbose
0359                 fprintf(div_line);
0360                 fprintf('The file ''%s'' containing the commands to\nadd MATPOWER to your %s path has been created.\n', fn, sw);
0361             end
0362         end
0363     end
0364 end
0365 
0366 if verbose
0367     fprintf(div_line);
0368     if modify
0369         fprintf('Now that you have added the required directories to your %s path\n', sw);
0370         fprintf('MATPOWER is installed and ready to use.\n\n');
0371     else
0372         fprintf('Once you have added the required directories to your %s path\n', sw);
0373         fprintf('MATPOWER will be installed and ready to use.\n\n');
0374     end
0375     fprintf('You may want to begin by typing: mpver\n');
0376     fprintf('to see the list of installed MATPOWER related software versions.\n\n');
0377     fprintf('Or to run the MATPOWER test suite to ensure everything is\n');
0378     fprintf('working correctly, type: test_matpower\n\n');
0379 
0380     if interactive && modify
0381         s = '?';
0382         while ~isempty(s) && (s(1) ~= 'Y' && s(1) ~= 'N')
0383             s = upper(input('Would you like to run the MATPOWER tests now? [Y or N] (default = N) : ', 's'));
0384         end
0385         if isempty(s)
0386             s = 'N';                %% default to N
0387         end
0388         if s(1) == 'Y'
0389             test_matpower;
0390         end
0391     end
0392 end
0393 
0394 if nargout
0395     succ = success;
0396 end
0397 
0398 function num = vstr2num(vstr)
0399 % Converts version string to numerical value suitable for < or > comparisons
0400 % E.g. '3.11.4' -->  3.011004
0401 pat = '\.?(\d+)';
0402 [s,e,tE,m,t] = regexp(vstr, pat);
0403 b = 1;
0404 num = 0;
0405 for k = 1:length(t)
0406     num = num + b * str2num(t{k}{1});
0407     b = b / 1000;
0408 end
install_matpower

PURPOSE

SYNOPSIS

DESCRIPTION

CROSS-REFERENCE INFORMATION

SUBFUNCTIONS

SOURCE CODE
