int2ext

INT2EXT   Converts internal to external bus numbering.

   This function has two forms, (1) the old form that operates on
   and returns individual matrices and (2) the new form that operates
   on and returns an entire MATPOWER case struct.

   1.  [BUS, GEN, BRANCH, AREAS] = INT2EXT(I2E, BUS, GEN, BRANCH, AREAS)
       [BUS, GEN, BRANCH] = INT2EXT(I2E, BUS, GEN, BRANCH)

   Converts from the consecutive internal bus numbers back to the originals
   using the mapping provided by the I2E vector returned from EXT2INT,
   where EXTERNAL_BUS_NUMBER = I2E(INTERNAL_BUS_NUMBER).
   AREAS is completely ignored and is only included here for backward
   compatibility of the API.

   Examples:
       [bus, gen, branch, areas] = int2ext(i2e, bus, gen, branch, areas);
       [bus, gen, branch] = int2ext(i2e, bus, gen, branch);

   2.  MPC = INT2EXT(MPC)

   If the input is a single MATPOWER case struct, then it restores all
   buses, generators and branches that were removed because of being
   isolated or off-line, and reverts to the original generator ordering
   and original bus numbering. This requires that the 'order' field
   created by EXT2INT be in place.

   Example:
       mpc = int2ext(mpc);

   See also EXT2INT, I2E_FIELD, I2E_DATA.

0001 function [bus, gen, branch, areas] = int2ext(i2e, bus, gen, branch, areas)
0002 %INT2EXT   Converts internal to external bus numbering.
0003 %
0004 %   This function has two forms, (1) the old form that operates on
0005 %   and returns individual matrices and (2) the new form that operates
0006 %   on and returns an entire MATPOWER case struct.
0007 %
0008 %   1.  [BUS, GEN, BRANCH, AREAS] = INT2EXT(I2E, BUS, GEN, BRANCH, AREAS)
0009 %       [BUS, GEN, BRANCH] = INT2EXT(I2E, BUS, GEN, BRANCH)
0010 %
0011 %   Converts from the consecutive internal bus numbers back to the originals
0012 %   using the mapping provided by the I2E vector returned from EXT2INT,
0013 %   where EXTERNAL_BUS_NUMBER = I2E(INTERNAL_BUS_NUMBER).
0014 %   AREAS is completely ignored and is only included here for backward
0015 %   compatibility of the API.
0016 %
0017 %   Examples:
0018 %       [bus, gen, branch, areas] = int2ext(i2e, bus, gen, branch, areas);
0019 %       [bus, gen, branch] = int2ext(i2e, bus, gen, branch);
0020 %
0021 %   2.  MPC = INT2EXT(MPC)
0022 %
0023 %   If the input is a single MATPOWER case struct, then it restores all
0024 %   buses, generators and branches that were removed because of being
0025 %   isolated or off-line, and reverts to the original generator ordering
0026 %   and original bus numbering. This requires that the 'order' field
0027 %   created by EXT2INT be in place.
0028 %
0029 %   Example:
0030 %       mpc = int2ext(mpc);
0031 %
0032 %   See also EXT2INT, I2E_FIELD, I2E_DATA.
0033 
0034 %   MATPOWER
0035 %   Copyright (c) 1996-2016, Power Systems Engineering Research Center (PSERC)
0036 %   by Ray Zimmerman, PSERC Cornell
0037 %
0038 %   This file is part of MATPOWER.
0039 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0040 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0041 
0042 if isstruct(i2e)
0043     mpc = i2e;
0044     if nargin == 1
0045         if ~isfield(mpc, 'order')
0046             error('int2ext: mpc does not have the ''order'' field required for conversion back to external numbering.');
0047         end
0048         o = mpc.order;
0049 
0050         if o.state == 'i'
0051             %% define names for columns to data matrices
0052             [PQ, PV, REF, NONE, BUS_I] = idx_bus;
0053             GEN_BUS = idx_gen;
0054             [F_BUS, T_BUS] = idx_brch;
0055 
0056             %% execute userfcn callbacks for 'int2ext' stage
0057             if isfield(mpc, 'userfcn')
0058                 mpc = run_userfcn(mpc.userfcn, 'int2ext', mpc);
0059             end
0060             
0061             %% convert back "extra" fields
0062             if isfield(mpc, 'gencost')
0063                 ordering = {'gen'};         %% Pg cost only
0064                 if size(mpc.gencost, 1) == 2*size(mpc.gen, 1)
0065                     ordering{2} = 'gen';    %% include Qg cost
0066                 end
0067                 mpc = i2e_field(mpc, 'gencost', ordering);
0068             end
0069             %% assume A and N are "read-only"
0070             %% (otherwise need to convert back, using i2e_field() which
0071             %% requires knowing if they are sized for AC or DC)
0072             if isfield(mpc, 'A')
0073                 o.int.A = mpc.A;
0074                 mpc.A = o.ext.A;
0075             end
0076             if isfield(mpc, 'N')
0077                 o.int.N = mpc.N;
0078                 mpc.N = o.ext.N;
0079             end
0080 
0081             %% save data matrices with internal ordering & restore originals
0082             o.int.bus    = mpc.bus;
0083             o.int.branch = mpc.branch;
0084             o.int.gen    = mpc.gen;
0085             mpc.bus     = o.ext.bus;
0086             mpc.branch  = o.ext.branch;
0087             mpc.gen     = o.ext.gen;
0088 
0089             %% zero pad data matrices on right if necessary
0090             nci = size(o.int.bus, 2);
0091             [nr, nc] = size(mpc.bus);
0092             if nc < nci
0093                 mpc.bus = [mpc.bus zeros(nr, nci-nc)];
0094             end
0095             nci = size(o.int.branch, 2);
0096             [nr, nc] = size(mpc.branch);
0097             if nc < nci
0098                 mpc.branch = [mpc.branch zeros(nr, nci-nc)];
0099             end
0100             nci = size(o.int.gen, 2);
0101             [nr, nc] = size(mpc.gen);
0102             if nc < nci
0103                 mpc.gen = [mpc.gen zeros(nr, nci-nc)];
0104             end
0105 
0106             %% update data (in bus, branch, and gen only)
0107             mpc.bus(o.bus.status.on, :)       = o.int.bus;
0108             mpc.branch(o.branch.status.on, :) = o.int.branch;
0109             mpc.gen(o.gen.status.on, :)       = o.int.gen(o.gen.i2e, :);
0110 
0111             %% revert to original bus numbers
0112             mpc.bus(o.bus.status.on, BUS_I) = ...
0113                     o.bus.i2e( mpc.bus(o.bus.status.on, BUS_I) );
0114             mpc.branch(o.branch.status.on, F_BUS) = ...
0115                     o.bus.i2e( mpc.branch(o.branch.status.on, F_BUS) );
0116             mpc.branch(o.branch.status.on, T_BUS) = ...
0117                     o.bus.i2e( mpc.branch(o.branch.status.on, T_BUS) );
0118             mpc.gen(o.gen.status.on, GEN_BUS) = ...
0119                     o.bus.i2e( mpc.gen(o.gen.status.on, GEN_BUS) );
0120 
0121             if isfield(o, 'ext')
0122                 o = rmfield(o, 'ext');
0123             end
0124             o.state = 'e';
0125             mpc.order = o;
0126         else
0127             error('int2ext: mpc claims it is already using external numbering.');
0128         end
0129 
0130         bus = mpc;
0131     else                    %% convert extra data
0132         if ischar(bus) || iscell(bus)   %% field
0133             warning('Calls of the form MPC = INT2EXT(MPC, ''FIELD_NAME'', ...) have been deprecated. Please replace INT2EXT with I2E_FIELD.');
0134             if nargin > 3
0135                 dim = branch;
0136             else
0137                 dim = 1;
0138             end
0139             bus = i2e_field(mpc, bus, gen, dim);
0140         else                            %% value
0141             warning('Calls of the form VAL = INT2EXT(MPC, VAL, ...) have been deprecated. Please replace INT2EXT with I2E_DATA.');
0142             if nargin > 4
0143                 dim = areas;
0144             else
0145                 dim = 1;
0146             end
0147             bus = i2e_data(mpc, bus, gen, branch, dim);
0148         end
0149     end
0150 else            %% old form
0151     %% define names for columns to data matrices
0152     [PQ, PV, REF, NONE, BUS_I] = idx_bus;
0153     [GEN_BUS] = idx_gen;
0154     [F_BUS, T_BUS] = idx_brch;
0155 
0156     bus(:, BUS_I)               = i2e( bus(:, BUS_I)            );
0157     gen(:, GEN_BUS)             = i2e( gen(:, GEN_BUS)          );
0158     branch(:, F_BUS)            = i2e( branch(:, F_BUS)         );
0159     branch(:, T_BUS)            = i2e( branch(:, T_BUS)         );
0160 end