mp.dmc_element

class mp.dmc_element

Bases: handle

mp.dmc_element- Abstract base class for data model converter element objects.

A data model converter element object implements the functionality needed to import and export a particular element type from and to a given data format. All data model converter element classes inherit from mp.dmc_element and each element type typically implements its own subclass.

By convention, data model converter element variables are named dmce and data model converter element class names begin with mp.dmce.

Typically, much of the import/export functionality for a particular concrete subclass can be defined simply by implementing the table_var_map() method.

mp.dmc_element Methods:

See the Data Model Converter Elements section in the MATPOWER Developer’s Manual for more information.

See also mp.dm_converter.

Method Summary
name()

Get name of element type, e.g. 'bus', 'gen'.

name = dmce.name()
Output:

name (char array) – name of element type, must be a valid struct field name

Implementation provided by an element type specific subclass.

data_model_element(dm, name)

Get the corresponding data model element.

dme = dmce.data_model_element(dm)
dme = dmce.data_model_element(dm, name)
Inputs:

  • dm (mp.data_model) – data model object

  • name (char array) – (optional) name of element type (default is name of this object)

Output:

dme (mp.dm_element) – data model element object

data_field()

Get name of field in data source corresponding to default data table.

df = dmce.data_field()
Output:

df (char array) – field name

data_subs()

Get subscript reference struct for accessing data source.

s = dmce.data_subs()
Output:

s (struct) – same as the s input argument to the built-in subsref(), to access this element’s data in data source, with fields:

  • type – character vector or string containing '()', '{}', or '.' specifying the subscript type

  • subs – cell array, character vector, or string containing the actual subscripts

The default implementation in this base class uses the return value of the data_field() method to access a field of the data source struct. That is:

s = struct('type', '.', 'subs', dmce.data_field());
data_exists(d)

Check if default field exists in data source.

TorF = dmce.data_exists(d)
Input:

d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

Output:

TorF (boolean) – true if field exists

Check if value returned by data_field() exists as a field in d.

get_import_spec(dme, d)

Get import specification.

spec = dmce.get_import_spec(dme, d)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

Output:

spec (struct) – import specification, with keys:

  • 'subs' - subscript reference struct for accessing data source, as returned by data_subs()

  • 'nr', 'nc', 'r' - number of rows, number of columns, row index vector, as returned by get_import_size()

  • 'vmap' - variable map, as returned by table_var_map()

See also get_export_spec().

get_export_spec(dme, d)

Get export specification.

spec = dmce.get_export_spec(dme, d)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

Output:

spec (struct) – export specification, see get_import_spec()

See also get_import_spec().

get_import_size(d)

Get dimensions of data to be imported.

[nr, nc, r] = dmce.get_import_size(d)
Input:

d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

Outputs:

  • nr (integer) – number of rows of data

  • nc (integer) – number of columns of data

  • r (integer) – optional index vector (empty by default) of rows in data source field that correspond to data to be imported

get_export_size(dme)

Get dimensions of data to be exported.

[nr, nc, r] = dmce.get_export_size(dme)
Input:

dme (mp.dm_element) – data model element object

Outputs:

  • nr (integer) – number of rows of data

  • nc (integer) – number of columns of data

  • r (integer) – optional index vector (empty by default) of rows in main table of dme that correspond to data to be exported

table_var_map(dme, d)

Get variable map for import/export.

vmap = dmce.table_var_map(dme, d)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

Output:

vmap (struct) – variable map, see Table 6.1 in the MATPOWER Developer’s Manual for details

This method initializes each entry to {'col', []} by default, so subclasses only need to assign vmap.(vn){2} for columns that map directly from a column of the data source.

import(dme, d, var_names, ridx)

Import data from data source into data model element.

dme = dmce.import(dme, d, var_names, ridx)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • var_names (cell array) – (optional) list of names of variables (columns of main table) to import (default is all variables)

  • ridx (integer) – (optional) vector of row indices of data to import (default is all rows)

Output:

dme (mp.dm_element) – updated data model element object

See also export().

import_table_values(dme, d, spec, var_names, ridx)

Import table values for given import specification.

dme = dmce.import_table_values(dme, d, spec, var_names, ridx)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • spec (struct) – import specification, see get_import_spec()

  • var_names (cell array) – (optional) list of names of variables (columns of main table) to import (default is all variables)

  • ridx (integer) – (optional) vector of row indices of data to import (default is all rows)

Output:

dme (mp.dm_element) – updated data model element object

Called by import().

get_input_table_values(d, spec, var_names, ridx)

Get values to insert in data model element table.

vals = dmce.get_input_table_values(d, spec, var_names, ridx)
Inputs:

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • spec (struct) – import specification, see get_import_spec()

  • var_names (cell array) – (optional) list of names of variables (columns of main table) to import (default is all variables)

  • ridx (integer) – (optional) vector of row indices of data to import (default is all rows)

Output:

vals (cell array) – values to assign to table columns in data model element

Called by import_table_values().

import_col(d, spec, vn, c, sf)

Extract and optionally modify values from data source column.

vals = dmce.import_col(d, spec, vn, c, sf)
Inputs:

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • spec (struct) – import specification, see get_import_spec()

  • vn (char array) – variable name

  • c (integer) – column index for data in data source

  • sf (double or function handle) – (optional) scale factor, function is called as sf(dmce, vn)

Output:

vals (cell array) – values to assign to table columns in data model element

Called by get_input_table_values().

export(dme, d, var_names, ridx)

Export data from data model element to data source.

d = dmce.export(dme, d, var_names, ridx)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • var_names (cell array) – (optional) list of names of variables (columns of main table) to export (default is all variables)

  • ridx (integer) – (optional) vector of row indices of data to export (default is all rows)

Output:

d – updated data source

See also import().

export_table_values(dme, d, spec, var_names, ridx)

Export table values for given import specification.

d = dmce.export_table_values(dme, d, spec, var_names, ridx)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • spec (struct) – export specification, see get_export_spec()

  • var_names (cell array) – (optional) list of names of variables (columns of main table) to export (default is all variables)

  • ridx (integer) – (optional) vector of row indices of data to export (default is all rows)

Output:

d – updated data source

Called by export().

init_export_data(dme, d, spec)

Initialize data source for export from data model element.

d = dmce.init_export_data(dme, d, spec)
Inputs:
Output:

d – updated data source

Called by export_table_values().

default_export_data_table(spec)

Create default (empty) data table for data source.

dt = dmce.default_export_data_table(spec)
Input:

spec (struct) – export specification, see get_export_spec()

Output:

dt – data table for data source, type depends on implementing subclass

Called by init_export_data().

default_export_data_nrows(spec)

Get number of rows for default_export_data_table().

nr = default_export_data_nrows(spec)
Input:

spec (struct) – export specification, see get_export_spec()

Output:

nr (integer) – number of rows

Called by default_export_data_table().

export_col(dme, d, spec, vn, ridx, c, sf)

Export a variable (table column) to the data source.

d = dmce.export_col(dme, d, spec, vn, ridx, c, sf)
Inputs:

  • dme (mp.dm_element) – data model element object

  • d – data source, type depends on the implementing subclass (e.g. MATPOWER case struct for mp.dm_converter_mpc2)

  • spec (struct) – export specification, see get_export_spec()

  • vn (char array) – variable name

  • ridx (integer) – (optional) vector of row indices of data to export (default is all rows)

  • c (integer) – column index for data in data source

  • sf (double or function handle) – (optional) scale factor, function is called as sf(dmce, vn)

Output:

d – updated data source

Called by export_table_values().