extract_islands

extract_islands(mpc, varargin)
extract_islands() - Extracts each island in a network with islands.
MPC_ARRAY = EXTRACT_ISLANDS(MPC)
MPC_ARRAY = EXTRACT_ISLANDS(MPC, GROUPS)
MPC_K = EXTRACT_ISLANDS(MPC, K)
MPC_K = EXTRACT_ISLANDS(MPC, GROUPS, K)
MPC_K = EXTRACT_ISLANDS(MPC, K, CUSTOM)
MPC_K = EXTRACT_ISLANDS(MPC, GROUPS, K, CUSTOM)

Returns a cell array of MATPOWER case structs for each island in
the input case struct. If the optional second argument is a cell
array GROUPS it is assumed to be a cell array of vectors of bus
indices for each island (as returned by FIND_ISLANDS). Providing
the GROUPS avoids the need for another traversal of the network
connectivity and can save a significant amount of time on very
large systems. If an additional argument K is included, it indicates
which island(s) to return and the return value is a single case
struct, rather than a cell array. If K is a scalar or vector, it
it specifies the index(indices) of the island(s) to include in
the resulting case file. K can also be the string 'all' which
will include all islands. This is the same as simply eliminating
all isolated buses.

A final optional argument CUSTOM is a struct that can be used to
indicate custom fields of MPC from which to extract data
corresponding to buses generators, branches or DC lines. It has
the following structure:

    CUSTOM.<ORDERING>{DIM} = FIELDS

<ORDERING> is either 'bus', 'gen', 'branch' or 'dcline' and
indicates that dimension DIM of FIELDS has dimensions
corresponding to this <ORDERING> and should have the appropriate
dimension extracted as well. FIELDS is a cell array, where
each element is either a single string (field name of MPC) or
a cell array of strings (nested fields of MPC).

Examples:
    Extract each island into it's own case struct:
        mpc_list = extract_islands(mpc);

    Extract the 2nd (that is, 2nd largest) island:
        mpc2 = extract_islands(mpc, 2);

    Extract the first and 3rd islands without a re-traverals of the
    network:
        groups = find_islands(mpc);
        mpc1 = extract_islands(mpc, groups, 1);
        mpc3 = extract_islands(mpc, groups, 3);

    Extract the 2nd island, including custom fields, where
    mpc.bus_label{b} contains a label for bus b, and mpc.gen_name{g},
    mpc.emissions.rate(g, :), and mpc.genloc(:, g) contain,
    respectively, the generator's name, emission rates and
    location coordinates:
        custom.bus{1} = {'bus_label'};
        custom.gen{1} = {'gen_name', {'emissions', 'rate'}};
        custom.gen{2} = {'genloc'};
        mpc = extract_islands(mpc, 1, custom);

    Note: Fields bus_name, gentype and genfuel are handled automatically
          and do not need to be included in custom.