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 objectdm
- data model objectnm
- network model objectmm
- mathematical model objectmm_opt
- solve options for mathematical modeli_dm
- iteration counter for data model loopi_nm
- iteration counter for network model loopi_mm
- iteration counter for math model loopsuccess
- success flag, 1 - math model solved, 0 - didn’t solvemessage
- output message
- mp.task Methods:
run()
- execute the tasknext_mm()
- controls iterations over mathematical modelsnext_nm()
- controls iterations over network modelsnext_dm()
- controls iterations over data modelsrun_post()
- called at end ofrun()
methodprint_soln()
- display pretty-printed resultsprint_soln_header()
- display success/failure, elapsed timesave_soln()
- save solved case to filedm_converter_class()
- get data model converter constructordm_converter_class_mpc2_default()
- get default data model converter constructordm_converter_create()
- create data model converter objectdata_model_class()
- get data model constructordata_model_class_default()
- get default data model constructordata_model_create()
- create data model objectdata_model_build()
- create and build data model objectdata_model_build_pre()
- called at beginning ofdata_model_build()
data_model_build_post()
- called at end ofdata_model_build()
network_model_class()
- get network model constructornetwork_model_class_default()
- get default network model constructornetwork_model_create()
- create network model objectnetwork_model_build()
- create and build network model objectnetwork_model_build_pre()
- called at beginning ofnetwork_model_build()
network_model_build_post()
- called at end ofnetwork_model_build()
network_model_x_soln()
- update network model state from math model solutionnetwork_model_update()
- update net model state/soln from math model solnmath_model_class()
- get mathematical model constructormath_model_class_default()
- get default mathematical model constructormath_model_create()
- create mathematical model objectmath_model_build()
- create and build mathematical model objectmath_model_opt()
- get options struct to pass tomm.solve()
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
-
- 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
- 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 solvedrun()
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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
mpx (cell array of
mp.extension
) – MATPOWER Extensions
- Output:
mm (
mp.math_model
) – new or updated mathmatical model object, or empty matrixnm (
mp.net_model
) – potentially updated network model objectdm (
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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
mpx (cell array of
mp.extension
) – MATPOWER Extensions
- Output:
nm (
mp.net_model
) – new or updated network model object, or empty matrixdm (
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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
mpx (cell array of
mp.extension
) – MATPOWER Extensions
- 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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
- 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 objectmpopt (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 objectd – data source specification, currently assumed to be a MATPOWER case name or case struct (
mpc
)dmc (
mp.dm_converter
) – data model converter objectmpopt (struct) – MATPOWER options struct
- Outputs:
dm (
mp.data_model
) – updated data model objectd – 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:
dm (
mp.data_model
) – data model objectdmc (
mp.dm_converter
) – data model converter objectmpopt (struct) – MATPOWER options struct
- 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 objectmpopt (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 objectmpopt (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 objectmpopt (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 objectmpopt (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 objectdm (
mp.data_model
) – data model objectmpopt (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 objectdm (
mp.data_model
) – data model objectmpopt (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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model object
- 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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model object
- 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 objectdm (
mp.data_model
) – data model objectmpopt (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 objectdm (
mp.data_model
) – data model objectmpopt (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 objectdm (
mp.data_model
) – data model objectmpopt (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 objectdm (
mp.data_model
) – data model objectmpopt (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:
mm (
mp.math_model
) – mathmatical model objectnm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
- Output:
opt (struct) – options struct for mathematical model solve() method
Called by
run()
method.