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-2015 by Power System Engineering Research Center (PSERC)
0036 %   by Ray Zimmerman, PSERC Cornell
0037 %
0038 %   $Id: int2ext.m 2644 2015-03-11 19:34:22Z ray $
0039 %
0040 %   This file is part of MATPOWER.
0041 %   Covered by the 3-clause BSD License (see LICENSE file for details).
0042 %   See http://www.pserc.cornell.edu/matpower/ for more info.
0043 
0044 if isstruct(i2e)
0045     mpc = i2e;
0046     if nargin == 1
0047         if ~isfield(mpc, 'order')
0048             error('int2ext: mpc does not have the ''order'' field required for conversion back to external numbering.');
0049         end
0050         o = mpc.order;
0051 
0052         if o.state == 'i'
0053             %% define names for columns to data matrices
0054             [PQ, PV, REF, NONE, BUS_I] = idx_bus;
0055             GEN_BUS = idx_gen;
0056             [F_BUS, T_BUS] = idx_brch;
0057 
0058             %% execute userfcn callbacks for 'int2ext' stage
0059             if isfield(mpc, 'userfcn')
0060                 mpc = run_userfcn(mpc.userfcn, 'int2ext', mpc);
0061             end
0062             
0063             %% convert back "extra" fields
0064             if isfield(mpc, 'gencost')
0065                 ordering = {'gen'};         %% Pg cost only
0066                 if size(mpc.gencost, 1) == 2*size(mpc.gen, 1)
0067                     ordering{2} = 'gen';    %% include Qg cost
0068                 end
0069                 mpc = i2e_field(mpc, 'gencost', ordering);
0070             end
0071             %% assume A and N are "read-only"
0072             %% (otherwise need to convert back, using i2e_field() which
0073             %% requires knowing if they are sized for AC or DC)
0074             if isfield(mpc, 'A')
0075                 o.int.A = mpc.A;
0076                 mpc.A = o.ext.A;
0077             end
0078             if isfield(mpc, 'N')
0079                 o.int.N = mpc.N;
0080                 mpc.N = o.ext.N;
0081             end
0082 
0083             %% save data matrices with internal ordering & restore originals
0084             o.int.bus    = mpc.bus;
0085             o.int.branch = mpc.branch;
0086             o.int.gen    = mpc.gen;
0087             mpc.bus     = o.ext.bus;
0088             mpc.branch  = o.ext.branch;
0089             mpc.gen     = o.ext.gen;
0090 
0091             %% zero pad data matrices on right if necessary
0092             nci = size(o.int.bus, 2);
0093             [nr, nc] = size(mpc.bus);
0094             if nc < nci
0095                 mpc.bus = [mpc.bus zeros(nr, nci-nc)];
0096             end
0097             nci = size(o.int.branch, 2);
0098             [nr, nc] = size(mpc.branch);
0099             if nc < nci
0100                 mpc.branch = [mpc.branch zeros(nr, nci-nc)];
0101             end
0102             nci = size(o.int.gen, 2);
0103             [nr, nc] = size(mpc.gen);
0104             if nc < nci
0105                 mpc.gen = [mpc.gen zeros(nr, nci-nc)];
0106             end
0107 
0108             %% update data (in bus, branch, and gen only)
0109             mpc.bus(o.bus.status.on, :)       = o.int.bus;
0110             mpc.branch(o.branch.status.on, :) = o.int.branch;
0111             mpc.gen(o.gen.status.on, :)       = o.int.gen(o.gen.i2e, :);
0112 
0113             %% revert to original bus numbers
0114             mpc.bus(o.bus.status.on, BUS_I) = ...
0115                     o.bus.i2e( mpc.bus(o.bus.status.on, BUS_I) );
0116             mpc.branch(o.branch.status.on, F_BUS) = ...
0117                     o.bus.i2e( mpc.branch(o.branch.status.on, F_BUS) );
0118             mpc.branch(o.branch.status.on, T_BUS) = ...
0119                     o.bus.i2e( mpc.branch(o.branch.status.on, T_BUS) );
0120             mpc.gen(o.gen.status.on, GEN_BUS) = ...
0121                     o.bus.i2e( mpc.gen(o.gen.status.on, GEN_BUS) );
0122 
0123             if isfield(o, 'ext')
0124                 o = rmfield(o, 'ext');
0125             end
0126             o.state = 'e';
0127             mpc.order = o;
0128         else
0129             error('int2ext: mpc claims it is already using external numbering.');
0130         end
0131 
0132         bus = mpc;
0133     else                    %% convert extra data
0134         if ischar(bus) || iscell(bus)   %% field
0135             warning('Calls of the form MPC = INT2EXT(MPC, ''FIELD_NAME'', ...) have been deprecated. Please replace INT2EXT with I2E_FIELD.');
0136             if nargin > 3
0137                 dim = branch;
0138             else
0139                 dim = 1;
0140             end
0141             bus = i2e_field(mpc, bus, gen, dim);
0142         else                            %% value
0143             warning('Calls of the form VAL = INT2EXT(MPC, VAL, ...) have been deprecated. Please replace INT2EXT with I2E_DATA.');
0144             if nargin > 4
0145                 dim = areas;
0146             else
0147                 dim = 1;
0148             end
0149             bus = i2e_data(mpc, bus, gen, branch, dim);
0150         end
0151     end
0152 else            %% old form
0153     %% define names for columns to data matrices
0154     [PQ, PV, REF, NONE, BUS_I] = idx_bus;
0155     [GEN_BUS] = idx_gen;
0156     [F_BUS, T_BUS] = idx_brch;
0157 
0158     bus(:, BUS_I)               = i2e( bus(:, BUS_I)            );
0159     gen(:, GEN_BUS)             = i2e( gen(:, GEN_BUS)          );
0160     branch(:, F_BUS)            = i2e( branch(:, F_BUS)         );
0161     branch(:, T_BUS)            = i2e( branch(:, T_BUS)         );
0162 end