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)
       MPC = INT2EXT(MPC, MPOPT)

   If the input is a single MATPOWER case struct, followed optionally
   by a MATOWER options 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.

   Examples:
       mpc = int2ext(mpc);
       mpc = int2ext(mpc, mpopt);

   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 %       MPC = INT2EXT(MPC, MPOPT)
0023 %
0024 %   If the input is a single MATPOWER case struct, followed optionally
0025 %   by a MATOWER options struct, then it restores all buses, generators
0026 %   and branches that were removed because of being isolated or off-line,
0027 %   and reverts to the original generator ordering and original bus
0028 %   numbering. This requires that the 'order' field created by EXT2INT be
0029 %   in place.
0030 %
0031 %   Examples:
0032 %       mpc = int2ext(mpc);
0033 %       mpc = int2ext(mpc, mpopt);
0034 %
0035 %   See also EXT2INT, I2E_FIELD, I2E_DATA.
0036 
0037 %   MATPOWER
0038 %   Copyright (c) 1996-2018, Power Systems Engineering Research Center (PSERC)
0039 %   by Ray Zimmerman, PSERC Cornell
0040 %
0041 %   This file is part of MATPOWER.
0042 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0043 %   See https://matpower.org for more info.
0044 
0045 if isstruct(i2e)
0046     mpc = i2e;
0047     if nargin < 3
0048         if ~isfield(mpc, 'order')
0049             error('int2ext: mpc does not have the ''order'' field required for conversion back to external numbering.');
0050         end
0051         o = mpc.order;
0052 
0053         if o.state == 'i'
0054             %% define names for columns to data matrices
0055             [PQ, PV, REF, NONE, BUS_I] = idx_bus;
0056             GEN_BUS = idx_gen;
0057             [F_BUS, T_BUS] = idx_brch;
0058 
0059             %% execute userfcn callbacks for 'int2ext' stage
0060             if isfield(mpc, 'userfcn')
0061                 if nargin < 2
0062                     mpopt = struct();
0063                 else
0064                     mpopt = gen;
0065                 end
0066                 mpc = run_userfcn(mpc.userfcn, 'int2ext', mpc, mpopt);
0067             end
0068             
0069             %% convert back "extra" fields
0070             if isfield(mpc, 'gencost')
0071                 ordering = {'gen'};         %% Pg cost only
0072                 if size(mpc.gencost, 1) == 2*size(mpc.gen, 1) && ...
0073                         size(mpc.gencost, 1) ~= 0
0074                     ordering{2} = 'gen';    %% include Qg cost
0075                 end
0076                 mpc = i2e_field(mpc, 'gencost', ordering);
0077             end
0078             if isfield(mpc, 'bus_name')
0079                 mpc = i2e_field(mpc, 'bus_name', {'bus'});
0080             end
0081             if isfield(mpc, 'gentype')
0082                 mpc = i2e_field(mpc, 'gentype', {'gen'});
0083             end
0084             if isfield(mpc, 'genfuel')
0085                 mpc = i2e_field(mpc, 'genfuel', {'gen'});
0086             end
0087             %% assume A and N are "read-only"
0088             %% (otherwise need to convert back, using i2e_field() which
0089             %% requires knowing if they are sized for AC or DC)
0090             if isfield(mpc, 'A')
0091                 o.int.A = mpc.A;
0092                 mpc.A = o.ext.A;
0093             end
0094             if isfield(mpc, 'N')
0095                 o.int.N = mpc.N;
0096                 mpc.N = o.ext.N;
0097             end
0098 
0099             %% save data matrices with internal ordering & restore originals
0100             o.int.bus    = mpc.bus;
0101             o.int.branch = mpc.branch;
0102             o.int.gen    = mpc.gen;
0103             mpc.bus     = o.ext.bus;
0104             mpc.branch  = o.ext.branch;
0105             mpc.gen     = o.ext.gen;
0106 
0107             %% zero pad data matrices on right if necessary
0108             nci = size(o.int.bus, 2);
0109             [nr, nc] = size(mpc.bus);
0110             if nc < nci
0111                 mpc.bus = [mpc.bus zeros(nr, nci-nc)];
0112             end
0113             nci = size(o.int.branch, 2);
0114             [nr, nc] = size(mpc.branch);
0115             if nc < nci
0116                 mpc.branch = [mpc.branch zeros(nr, nci-nc)];
0117             end
0118             nci = size(o.int.gen, 2);
0119             [nr, nc] = size(mpc.gen);
0120             if nc < nci
0121                 mpc.gen = [mpc.gen zeros(nr, nci-nc)];
0122             end
0123 
0124             %% update data (in bus, branch, and gen only)
0125             mpc.bus(o.bus.status.on, :)       = o.int.bus;
0126             mpc.branch(o.branch.status.on, :) = o.int.branch;
0127             mpc.gen(o.gen.status.on, :)       = o.int.gen(o.gen.e2i, :);
0128 
0129             %% revert to original bus numbers
0130             mpc.bus(o.bus.status.on, BUS_I) = ...
0131                     o.bus.i2e( mpc.bus(o.bus.status.on, BUS_I) );
0132             mpc.branch(o.branch.status.on, F_BUS) = ...
0133                     o.bus.i2e( mpc.branch(o.branch.status.on, F_BUS) );
0134             mpc.branch(o.branch.status.on, T_BUS) = ...
0135                     o.bus.i2e( mpc.branch(o.branch.status.on, T_BUS) );
0136             mpc.gen(o.gen.status.on, GEN_BUS) = ...
0137                     o.bus.i2e( mpc.gen(o.gen.status.on, GEN_BUS) );
0138 
0139             if isfield(o, 'ext')
0140                 o = rmfield(o, 'ext');
0141             end
0142             o.state = 'e';
0143             mpc.order = o;
0144         else
0145             error('int2ext: mpc claims it is already using external numbering.');
0146         end
0147 
0148         bus = mpc;
0149     else                    %% convert extra data
0150         if ischar(bus) || iscell(bus)   %% field
0151             warning('Calls of the form MPC = INT2EXT(MPC, ''FIELD_NAME'', ...) have been deprecated. Please replace INT2EXT with I2E_FIELD.');
0152             if nargin > 3
0153                 dim = branch;
0154             else
0155                 dim = 1;
0156             end
0157             bus = i2e_field(mpc, bus, gen, dim);
0158         else                            %% value
0159             warning('Calls of the form VAL = INT2EXT(MPC, VAL, ...) have been deprecated. Please replace INT2EXT with I2E_DATA.');
0160             if nargin > 4
0161                 dim = areas;
0162             else
0163                 dim = 1;
0164             end
0165             bus = i2e_data(mpc, bus, gen, branch, dim);
0166         end
0167     end
0168 else            %% old form
0169     %% define names for columns to data matrices
0170     [PQ, PV, REF, NONE, BUS_I] = idx_bus;
0171     [GEN_BUS] = idx_gen;
0172     [F_BUS, T_BUS] = idx_brch;
0173 
0174     bus(:, BUS_I)               = i2e( bus(:, BUS_I)            );
0175     gen(:, GEN_BUS)             = i2e( gen(:, GEN_BUS)          );
0176     branch(:, F_BUS)            = i2e( branch(:, F_BUS)         );
0177     branch(:, T_BUS)            = i2e( branch(:, T_BUS)         );
0178 end