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.5.0';
0065 install = struct( ...
0066     'name', { ...
0067         'matpower', ...
0068         'most', ...
0069         'mp-opt-model', ...
0070         'mips', ...
0071         'mptest', ...
0072         'maxloadlim', ...
0073         'misc', ...
0074         'reduction', ...
0075         'sdp_pf', ...
0076         'se', ...
0077         'smartmarket', ...
0078         'state_estimator', ...
0079         'syngrid' }, ...
0080     'dirs', { ...
0081         {{'lib'}, {'lib', 't'}, {'data'}}, ...
0082         {{'most', 'lib'}, {'most', 'lib', 't'}}, ...
0083         {{'mp-opt-model', 'lib'}, {'mp-opt-model', 'lib', 't'}}, ...
0084         {{'mips', 'lib'}, {'mips', 'lib', 't'}}, ...
0085         {{'mptest', 'lib'}, {'mptest', 'lib', 't'}}, ...
0086         {{'extras', 'maxloadlim'}, {'extras', 'maxloadlim', 'tests'}, ...
0087             {'extras', 'maxloadlim', 'examples'}}, ...
0088         {{'extras', 'misc'}}, ...
0089         {{'extras', 'reduction'}}, ...
0090         {{'extras', 'sdp_pf'}}, ...
0091         {{'extras', 'se'}}, ...
0092         {{'extras', 'smartmarket'}}, ...
0093         {{'extras', 'state_estimator'}}, ...
0094         {{'extras', 'syngrid', 'lib'}, {'extras', 'syngrid', 'lib', 't'}} }, ...
0095     'fcns', { ...
0096         {'mpver', 'test_matpower', 'case9'}, ...
0097         {'mostver', 'test_most'}, ...
0098         {'mpomver', 'test_mp_opt_model'}, ...
0099         {'mipsver', 'test_mips'}, ...
0100         {'mptestver', 'test_mptest'}, ...
0101         {'maxloadlim', 'test_mll_main', 'example_ieee9.m'}, ...
0102         {'checklimits'}, ...
0103         {'MPReduction'}, ...
0104         {'sdp_pf_ver'}, ...
0105         {'run_se'}, ...
0106         {'runmarket'}, ...
0107         {'runse'}, ...
0108         {'syngrid', 'test_syngrid'} } ...
0109 );
0110 ni = length(install);   %% number of components
0111 
0112 %% default arguments
0113 interactive = 0;
0114 if nargin < 4
0115     rm_oldpaths = 0;
0116     if nargin < 3
0117         verbose = 1;
0118         if nargin < 2
0119             save_it = 0;
0120             if nargin < 1
0121                 modify = [];
0122                 interactive = 1;
0123             end
0124         end
0125     end
0126 end
0127 
0128 %% get path to new MATPOWER installation root
0129 [root, n, e] = fileparts(which('install_matpower'));
0130 
0131 %% MATLAB or Octave
0132 if exist('OCTAVE_VERSION', 'builtin') == 5
0133     sw = 'Octave';
0134 else
0135     sw = 'MATLAB';
0136 end
0137 
0138 %% check for required version of MATLAB or Octave
0139 vstr = '';
0140 switch sw
0141     case 'Octave'
0142         v = ver('octave');
0143     case 'MATLAB'
0144         v = ver('matlab');
0145         if length(v) > 1
0146             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.');
0147             v = v(1);
0148         end
0149 end
0150 if ~isempty(v) && isfield(v, 'Version') && ~isempty(v.Version)
0151     vstr = v.Version;
0152     if vstr2num(vstr) < vstr2num(min_ver.(sw))
0153         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));
0154     end
0155 else
0156     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));
0157 end
0158 
0159 
0160 %% get installation options interactively, if necessary
0161 div_line = sprintf('\n-------------------------------------------------------------------\n\n');
0162 if interactive
0163     fprintf(div_line);
0164     fprintf('MATPOWER Installation Options:\n\n');
0165     fprintf('   1. Do NOT modify the %s path\n', sw);
0166     fprintf('          (just generate the required ADDPATH commands)\n');
0167     fprintf('   2. DO modify the %s path, but only temporarily\n', sw);
0168     fprintf('          (you will have to do it again next time you run %s)\n', sw);
0169     fprintf('   3. DO modify the %s path, and SAVE the updated path\n', sw);
0170     fprintf('          (so you will not have to do it again next time you run %s)\n\n', sw);
0171     s = 0;
0172     while ~isempty(s) && (s < 1 || s > 3 || rem(s, 1))
0173         s = str2num(input('Please enter your selection [1, 2, 3] (default = 1) : ', 's'));
0174     end
0175     if isempty(s)
0176         s = 1;              %% default to option 1
0177     end
0178     switch s
0179         case 1              %% don't modify
0180             modify = 0;
0181         case 2              %% modify, don't save
0182             modify = 1;
0183             save_it = 0;
0184         case 3              %% modify and save
0185             modify = 1;
0186             save_it = 1;
0187         otherwise
0188     end
0189 end
0190 
0191 %% find available new components
0192 available = zeros(ni, 1);
0193 for i = 1:ni
0194     if exist(fullfile(root, install(i).dirs{1}{:}), 'dir')
0195         available(i) = 1;
0196     end
0197     % fprintf('%d %s\n', available(i), fullfile(root, install(i).dirs{:}));
0198 end
0199 
0200 %% find paths for currently installed components
0201 oldpaths = {};
0202 for i = 1:ni
0203     if available(i)     %% only if we have a new replacement
0204         for k = 1:length(install(i).fcns)
0205             [p, n, e] = fileparts(which(install(i).fcns{k}));
0206             if ~isempty(p) && ~ismember(p, oldpaths)
0207                 oldpaths{end+1} = p;
0208             end
0209         end
0210     end
0211 end
0212 
0213 if ~isempty(oldpaths)
0214     if exist('mpver', 'file')
0215         v = mpver;
0216     else
0217         v = '';
0218     end
0219     str = sprintf('It appears you already have MATPOWER %s or some of its\n', v);
0220     str = sprintf('%scomponents installed in the following directories:\n\n', str);
0221     rm_path_str = '';
0222     for k = 1:length(oldpaths)
0223         rm_path_str = sprintf('%s    %s\n', rm_path_str, oldpaths{k});
0224     end
0225     if interactive
0226         fprintf(div_line);
0227         fprintf('%s%s\n', str, rm_path_str);
0228         fprintf('Unless you are sure you know what you are doing, we recommend\n');
0229         fprintf('removing these directories from your %s path before proceeding.\n\n', sw);
0230         s = '?';
0231         while ~isempty(s) && (s(1) ~= 'Y' && s(1) ~= 'N')
0232             s = upper(input('Would you like me to do it for you? [Y or N] (default = N) : ', 's'));
0233         end
0234         if isempty(s)
0235             s = 'N';                %% default to N
0236         end
0237         if s(1) == 'Y'
0238             rm_oldpaths = 1;
0239         end
0240     elseif ~rm_oldpaths
0241         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);
0242     end
0243 end
0244 
0245 %% remove old paths
0246 if rm_oldpaths
0247     rmpath(oldpaths{:});
0248     if verbose
0249         fprintf(div_line);
0250         fprintf('The following directories were removed from your %s path:\n\n%s\n', sw, rm_path_str);
0251         if ~modify
0252             fprintf('You will need to manually use SAVEPATH to make the changes permanent.\n');
0253             s = input('Hit any key to continue ...', 's');
0254         end
0255     end
0256 end
0257 
0258 %% generate paths to add
0259 newpaths = {};
0260 for i = 1:ni
0261     if available(i)     %% only available components
0262         for k = 1:length(install(i).dirs)
0263             p = fullfile(root, install(i).dirs{k}{:});
0264             if ~isempty(p) && ~ismember(p, newpaths)
0265                 newpaths{end+1} = p;
0266             end
0267         end
0268     end
0269 end
0270 
0271 %% build addpath string
0272 cmd = sprintf('addpath( ...\n');
0273 for k = 1:length(newpaths)
0274     cmd = sprintf('%s    ''%s'', ...\n', cmd, newpaths{k});
0275 end
0276 cmd = sprintf('%s    ''%s'' );\n', cmd, '-end');
0277 
0278 %% print addpath
0279 if verbose
0280     fprintf(div_line);
0281     if modify
0282         fprintf('Your %s path will be updated using the following command:\n\n%s', sw, cmd);
0283         if interactive
0284             s = input(sprintf('\nHit any key to continue ...'), 's');
0285         end
0286     else
0287         fprintf('Use the following command to add MATPOWER to your %s path:\n\n%s\n', sw, cmd);
0288     end
0289 end
0290 
0291 %% add the new paths
0292 if modify
0293     addpath(newpaths{:}, '-end');
0294     if verbose
0295         fprintf('Your %s path has been updated.\n', sw);
0296     end
0297 end
0298 
0299 %% prompt about saving the command to a file
0300 if interactive && ~modify
0301     s = '?';
0302     while ~isempty(s) && (s(1) ~= 'Y' && s(1) ~= 'N')
0303         s = upper(input('Would you like to save this command to a file? [Y or N] (default = N) : ', 's'));
0304     end
0305     if isempty(s)
0306         s = 'N';                %% default to N
0307     end
0308     if s(1) == 'Y'
0309         %% prompt for file name
0310         s = '?';
0311         while ~isempty(s) && s(1) == '?'
0312             s = input('Please enter the name of file? (default = ''startup.m'') : ', 's');
0313         end
0314         if isempty(s)
0315             s = 'startup.m';    %% default to 'startup.m'
0316         end
0317         save_it = s;
0318     else
0319         save_it = 0;
0320     end
0321 end
0322 
0323 %% save path
0324 success = 1;
0325 if save_it
0326     if modify                   %% modify the path directly
0327         savepath;                   %% save the updated path
0328         if verbose
0329             fprintf(div_line);
0330             fprintf('Your updated %s path has been saved using SAVEPATH.\n', sw);
0331         end
0332     else                        %% don't modify the path directly
0333         %% set up file name
0334         if ~ischar(save_it)
0335             save_it = 'startup.m';
0336         end
0337         [p, n, e] = fileparts(save_it);
0338         if isempty(e)
0339             e = '.m';
0340         end
0341         fn = fullfile(p, [n e]);
0342 
0343         %% write file
0344         if exist(fn, 'file')        %% file exists, print a warning
0345             if verbose
0346                 fprintf(div_line);
0347                 fprintf('The file ''%s'' was not written. A file with that name already exists.', fn);
0348             else
0349                 error('install_matpower: file ''%s'' not written, a file with that name already exists', fn);
0350             end
0351         else                        %% create the file
0352             fid = fopen(fn, 'a');
0353             if fid == -1
0354                 success = 0;
0355             else
0356                 fprintf(fid, '%%%s\n\n', upper(n));
0357                 fprintf(fid, '%%%% add MATPOWER paths\n');
0358                 fprintf(fid, '%s', cmd);
0359                 fclose(fid);
0360             end
0361             if verbose
0362                 fprintf(div_line);
0363                 fprintf('The file ''%s'' containing the commands to\nadd MATPOWER to your %s path has been created.\n', fn, sw);
0364             end
0365         end
0366     end
0367 end
0368 
0369 if verbose
0370     fprintf(div_line);
0371     if modify
0372         fprintf('Now that you have added the required directories to your %s path\n', sw);
0373         fprintf('MATPOWER is installed and ready to use.\n\n');
0374     else
0375         fprintf('Once you have added the required directories to your %s path\n', sw);
0376         fprintf('MATPOWER will be installed and ready to use.\n\n');
0377     end
0378     fprintf('You may want to begin by typing: mpver\n');
0379     fprintf('to see the list of installed MATPOWER related software versions.\n\n');
0380     fprintf('Or to run the MATPOWER test suite to ensure everything is\n');
0381     fprintf('working correctly, type: test_matpower\n\n');
0382 
0383     if interactive && modify
0384         s = '?';
0385         while ~isempty(s) && (s(1) ~= 'Y' && s(1) ~= 'N')
0386             s = upper(input('Would you like to run the MATPOWER tests now? [Y or N] (default = N) : ', 's'));
0387         end
0388         if isempty(s)
0389             s = 'N';                %% default to N
0390         end
0391         if s(1) == 'Y'
0392             test_matpower;
0393         end
0394     end
0395 end
0396 
0397 if nargout
0398     succ = success;
0399 end
0400 
0401 function num = vstr2num(vstr)
0402 % Converts version string to numerical value suitable for < or > comparisons
0403 % E.g. '3.11.4' -->  3.011004
0404 pat = '\.?(\d+)';
0405 [s,e,tE,m,t] = regexp(vstr, pat);
0406 b = 1;
0407 num = 0;
0408 for k = 1:length(t)
0409     num = num + b * str2num(t{k}{1});
0410     b = b / 1000;
0411 end
install_matpower

PURPOSE

SYNOPSIS

DESCRIPTION

CROSS-REFERENCE INFORMATION

SUBFUNCTIONS

SOURCE CODE
