mp.task

class mp.task

Bases: handle

mp.task - MATPOWER task abstract base class.

Each task type (e.g. power flow, CPF, OPF) will inherit from mp.task.

Provides properties and methods related to the specific problem specification being solved (e.g. power flow, continuation power flow, optimal power flow, etc.). In particular, it coordinates all interactions between the 3 (data, network, mathematical) model layers.

The model objects, and indirectly their elements, as well as the solution success flag and messages from the mathematical model solver, are available in the properties of the task object.

mp.task Properties:

  • tag - task tag - e.g. ‘PF’, ‘CPF’, ‘OPF’

  • name - task name - e.g. ‘Power Flow’, etc.

  • dmc - data model converter object

  • dm - data model object

  • nm - network model object

  • mm - mathematical model object

  • mm_opt - solve options for mathematical model

  • i_dm - iteration counter for data model loop

  • i_nm - iteration counter for network model loop

  • i_mm - iteration counter for math model loop

  • success - success flag, 1 - math model solved, 0 - didn’t solve

  • message - output message

  • et - elapsed time (seconds) for run() method

mp.task Methods:

See the Task Object section in the MATPOWER Developer’s Manual for more information.

See also mp.data_model, mp.net_model, mp.math_model, mp.dm_converter.

Property Summary
tag

(char array) task tag - e.g. ‘PF’, ‘CPF’, ‘OPF’

name

(char array) task name - e.g. ‘Power Flow’, etc.

dmc

(mp.dm_converter) data model converter object

dm

(mp.data_model) data model object

nm

(mp.net_model) network model object

mm

(mp.math_model) mathematical model object

mm_opt

(struct) solve options for mathematical model

i_dm

(integer) iteration counter for data model loop

i_nm

(integer) iteration counter for network model loop

i_mm

(integer) iteration counter for math model loop

success

(integer) success flag, 1 - math model solved, 0 - didn’t solve

message

(char array) output message

et

(double) elapsed time (seconds) for run() method

Method Summary
run(d, mpopt, mpx)

Execute the task.

task.run(d, mpopt)
task.run(d, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

task (mp.task) – task object containing the solved run() including the data, network, and mathematical model objects.

Execute the task, creating the data model converter and the data, network and mathematical model objects, solving the math model and propagating the solution back to the data model.

See the Task Object section in the MATPOWER Developer’s Manual for more information.

next_mm(mm, nm, dm, mpopt, mpx)

Controls iterations over mathematical models.

[mm, nm, dm] = task.next_mm(mm, nm, dm, mpoopt, mpx)
Inputs:
Output:

  • mm (mp.math_model) – new or updated mathmatical model object, or empty matrix

  • nm (mp.net_model) – potentially updated network model object

  • dm (mp.data_model) – potentially updated data model object

Called automatically by run() method. Subclasses can override this method to return a new or updated math model object for use in the next iteration or an empty matrix (the default) if finished.

next_nm(mm, nm, dm, mpopt, mpx)

Controls iterations over network models.

[nm, dm] = task.next_nm(mm, nm, dm, mpoopt, mpx)
Inputs:
Output:

  • nm (mp.net_model) – new or updated network model object, or empty matrix

  • dm (mp.data_model) – potentially updated data model object

Called automatically by run() method. Subclasses can override this method to return a new or updated network model object for use in the next iteration or an empty matrix (the default) if finished.

next_dm(mm, nm, dm, mpopt, mpx)

Controls iterations over data models.

dm = task.next_dm(mm, nm, dm, mpoopt, mpx)
Inputs:
Output:

dm (mp.data_model) – new or updated data model object, or empty matrix

Called automatically by run() method. Subclasses can override this method to return a new or updated data model object for use in the next iteration or an empty matrix (the default) if finished.

run_pre(d, mpopt)

Called at beginning of run() method.

[d, mpopt] = task.run_pre(d, mpopt)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

Outputs:

  • d – updated value of corresponding input

  • mpopt (struct) – updated value of corresponding input

Subclasses can override this method to update the input data or options before beginning the run.

run_post(mm, nm, dm, mpopt)

Called at end of run() method.

task.run_post(mm, nm, dm, mpopt)
Inputs:
Output:

task (mp.task) – task object

Subclasses can override this method to do any final processing after the run is complete.

print_soln(mpopt, fname)

Display the pretty-printed results.

task.print_soln(mpopt)
task.print_soln(mpopt, fname)
Inputs:

  • mpopt (struct) – MATPOWER options struct

  • fname (char array) – file name for saving pretty-printed output

Display to standard output and/or save to a file the pretty-printed solved case.

print_soln_header(mpopt, fd)

Display solution header information.

task.print_soln_header(mpopt, fd)
Inputs:

  • mpopt (struct) – MATPOWER options struct

  • fd (integer) – file identifier (1 for standard output)

Called by print_soln() to print success/failure, elapsed time, etc. to a file identifier.

save_soln(fname)

Save the solved case to a file.

task.save_soln(fname)
Input:

fname (char array) – file name for saving solved case

dm_converter_class(d, mpopt, mpx)

Get data model converter constructor.

dmc_class = task.dm_converter_class(d, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

dmc_class (function handle) – handle to the constructor to be used to instantiate the data model converter object

Called by dm_converter_create() to determine the class to use for the data model converter object. Handles any modifications specified by MATPOWER options or extensions.

dm_converter_class_mpc2_default()

Get default data model converter constructor.

dmc_class = task.dm_converter_class_mpc2_default()
Output:

dmc_class (function handel) – handle to default constructor to be used to instantiate the data model converter object

Called by dm_converter_class() to determine the default class to use for the data model converter object when the input is a version 2 MATPOWER case struct.

dm_converter_create(d, mpopt, mpx)

Create data model converter object.

dmc = task.dm_converter_create(d, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

dmc (mp.dm_converter) – data model converter object, ready to build

Called by dm_converter_build() method to instantiate the data model converter object. Handles any modifications to data model converter elements specified by MATPOWER options or extensions.

dm_converter_build(d, mpopt, mpx)

Create and build data model converter object.

dmc = task.dm_converter_build(d, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

dmc (mp.dm_converter) – data model converter object, ready for use

Called by run() method to instantiate and build the data model converter object, including any modifications specified by MATPOWER options or extensions.

data_model_class(d, mpopt, mpx)

Get data model constructor.

dm_class = task.data_model_class(d, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

dm_class (function handle) – handle to the constructor to be used to instantiate the data model object

Called by data_model_create() to determine the class to use for the data model object. Handles any modifications specified by MATPOWER options or extensions.

data_model_class_default()

Get default data model constructor.

dm_class = task.data_model_class_default()
Output:

dm_class (function handel) – handle to default constructor to be used to instantiate the data model object

Called by data_model_class() to determine the default class to use for the data model object.

data_model_create(d, mpopt, mpx)

Create data model object.

dm = task.data_model_create(d, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

dm (mp.data_model) – data model object, ready to build

Called by data_model_build() to instantiate the data model object. Handles any modifications to data model elements specified by MATPOWER options or extensions.

data_model_build(d, dmc, mpopt, mpx)

Create and build data model object.

dm = task.data_model_create(d, dmc, mpopt, mpx)
Inputs:

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • dmc (mp.dm_converter) – data model converter object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

dm (mp.data_model) – data model object, ready for use

Called by run() method to instantiate and build the data model object, including any modifications specified by MATPOWER options or extensions.

data_model_build_pre(dm, d, dmc, mpopt)

Called at beginning of data_model_build().

[dm, d] = task.data_model_build_pre(dm, d, dmc, mpopt)
Inputs:

  • dm (mp.data_model) – data model object

  • d – data source specification, currently assumed to be a MATPOWER case name or case struct (mpc)

  • dmc (mp.dm_converter) – data model converter object

  • mpopt (struct) – MATPOWER options struct

Outputs:

  • dm (mp.data_model) – updated data model object

  • d – updated value of corresponding input

Called just before calling the data model’s build() method. In this base class, this method does nothing.

data_model_build_post(dm, dmc, mpopt)

Called at end of data_model_build().

dm = task.data_model_build_post(dm, dmc, mpopt)
Inputs:
Output:

dm (mp.data_model) – updated data model object

Called just after calling the data model’s build() method. In this base class, this method does nothing.

network_model_class(dm, mpopt, mpx)

Get network model constructor.

nm_class = task.network_model_class(dm, mpopt, mpx)
Inputs:

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

nm_class (function handle) – handle to the constructor to be used to instantiate the network model object

Called by network_model_create() to determine the class to use for the network model object. Handles any modifications specified by MATPOWER options or extensions.

network_model_class_default(dm, mpopt)

Get default network model constructor.

nm_class = task.network_model_class_default(dm, mpopt)
Inputs:

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

Output:

nm_class (function handle) – handle to default constructor to be used to instantiate the network model object

Called by network_model_class() to determine the default class to use for the network model object.

Note: This is an abstract method that must be implemented by a subclass.

network_model_create(dm, mpopt, mpx)

Create network model object.

nm = task.network_model_create(dm, mpopt, mpx)
Inputs:

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

nm (mp.net_model) – network model object, ready to build

Called by network_model_build() to instantiate the network model object. Handles any modifications to network model elements specified by MATPOWER options or extensions.

network_model_build(dm, mpopt, mpx)

Create and build network model object.

nm = task.network_model_build(dm, mpopt, mpx)
Inputs:

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

nm (mp.net_model) – network model object, ready for use

Called by run() method to instantiate and build the network model object, including any modifications specified by MATPOWER options or extensions.

network_model_build_pre(nm, dm, mpopt)

Called at beginning of network_model_build().

nm = task.network_model_build_pre(nm, dm, mpopt)
Inputs:

  • nm (mp.net_model) – network model object

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

Output:

nm (mp.net_model) – updated network model object

Called just before calling the network model’s build() method. In this base class, this method does nothing.

network_model_build_post(nm, dm, mpopt)

Called at end of network_model_build().

nm = task.network_model_build_post(nm, dm, mpopt)
Inputs:

  • nm (mp.net_model) – network model object

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

Output:

nm (mp.net_model) – updated network model object

Called just after calling the network model’s build() method. In this base class, this method does nothing.

network_model_x_soln(mm, nm)

Update network model state from math model solution.

nm = task.network_model_x_soln(mm, nm)
Inputs:
Output:

nm (mp.net_model) – updated network model object

Called by network_model_update().

network_model_update(mm, nm)

Update network model state, solution values from math model solution.

nm = task.network_model_update(mm, nm)
Inputs:
Output:

nm (mp.net_model) – updated network model object

Called by run() method.

math_model_class(nm, dm, mpopt, mpx)

Get mathematical model constructor.

mm_class = task.math_model_class(nm, dm, mpopt, mpx)
Inputs:

  • nm (mp.net_model) – network model object

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

mm_class (function handle) – handle to the constructor to be used to instantiate the mathematical model object

Called by math_model_create() to determine the class to use for the mathematical model object. Handles any modifications specified by MATPOWER options or extensions.

math_model_class_default(nm, dm, mpopt)

Get default mathematical model constructor.

mm_class = task.math_model_class_default(nm, dm, mpopt)
Inputs:

  • nm (mp.net_model) – network model object

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

Output:

mm_class (function handle) – handle to the constructor to be used to instantiate the mathematical model object

Called by math_model_class() to determine the default class to use for the mathematical model object.

Note: This is an abstract method that must be implemented by a subclass.

math_model_create(nm, dm, mpopt, mpx)

Create mathematical model object.

mm = task.math_model_create(nm, dm, mpopt, mpx)
Inputs:

  • nm (mp.net_model) – network model object

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

mm (mp.math_model) – mathmatical model object, ready to build

Called by math_model_build() to instantiate the mathematical model object. Handles any modifications to mathematical model elements specified by MATPOWER options or extensions.

math_model_build(nm, dm, mpopt, mpx)

Create and build mathematical model object.

mm = task.math_model_build(nm, dm, mpopt, mpx)
Inputs:

  • nm (mp.net_model) – network model object

  • dm (mp.data_model) – data model object

  • mpopt (struct) – MATPOWER options struct

  • mpx (cell array of mp.extension) – MATPOWER Extensions

Output:

mm (mp.math_model) – mathmatical model object, ready for use

Called by run() method to instantiate and build the mathematical model object, including any modifications specified by MATPOWER options or extensions.

math_model_opt(mm, nm, dm, mpopt)

Get the options struct to pass to mm.solve().

opt = task.math_model_opt(mm, nm, dm, mpopt)
Inputs:
Output:

opt (struct) – options struct for mathematical model solve() method

Called by run() method.