mp.math_model
- class mp.math_model
Bases:
mp.element_container
,opt_model
mp.math_model
- Abstract base class for MATPOWER mathematical model objects.The mathematical model, or math model, formulates and defines the mathematical problem to be solved. That is, it determines the variables, constraints, and objective that define the problem. This takes on different forms depending on the task (e.g. power flow, optimal power flow, etc.) and the formulation (e.g. DC, AC-polar-power, etc.).
A math model object is a container for math model element (
mp.mm_element
) objects and it is also an MP-Opt-Model (opt_model
) object. All math model classes inherit frommp.math_model
and therefore also frommp.element_container
,opt_model
, andmp_idx_manager
. Concrete math model classes are task and formulation specific. They also sometimes inherit from abstract mix-in classes that are shared across tasks or formulations.By convention, math model variables are named
mm
and math model class names begin withmp.math_model
.- mp.math_model Properties:
aux_data
- auxiliary data relevant to the model
- mp.math_model Methods:
task_tag()
- returns task tag, e.g.'PF'
,'OPF'
task_name()
- returns task name, e.g.'Power Flow'
,'Optimal Power Flow'
form_tag()
- returns network formulation tag, e.g.'dc'
,'acps'
form_name()
- returns network formulation name, e.g.'DC'
,'AC-polar-power'
build()
- create, add, and build math model element objectsdisplay()
- display the math model objectadd_aux_data()
- builds auxiliary data and adds it to the modelbuild_base_aux_data()
- builds base auxiliary data, including node types & variable initial valuesadd_vars()
- add variables to the modeladd_system_vars()
- add system variables to the modeladd_constraints()
- add constraints to the modeladd_system_constraints()
- add system constraints to the modeladd_node_balance_constraints()
- add node balance constraints to the modeladd_costs()
- add costs to the modeladd_system_costs()
- add system costs to the modelsolve_opts()
- return an options struct to pass to the solverupdate_nm_vars()
- update network model variables from math model solutiondata_model_update()
- update data model from math model solutionnetwork_model_x_soln()
- convert solved state from math model to network model solution
See the Mathematical Model Object section in the MATPOWER Developer’s Manual for more information.
See also
mp.task
,mp.data_model
,mp.net_model
.- Property Summary
- aux_data
(struct) auxiliary data relevant to the model, e.g. can be passed to model constraint functions
- Method Summary
- task_tag()
Returns task tag, e.g.
'PF'
,'OPF'
.tag = mm.task_tag()
- task_name()
Returns task name, e.g.
'Power Flow'
,'Optimal Power Flow'
.name = mm.task_name()
- form_tag()
Returns network formulation tag, e.g.
'dc'
,'acps'
.tag = mm.form_tag()
- form_name()
Returns network formulation name, e.g.
'DC'
,'AC-polar-power'
.name = mm.form_name()
- build(nm, dm, mpopt)
Create, add, and
build()
math model element objects.mm.build(nm, dm, mpopt);
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Create and add network model objects, create and add auxiliary data, and add variables, constraints, and costs.
- display()
Display the math model object.
This method is called automatically when omitting a semicolon on a line that retuns an object of this class.
Displays the details of the variables, constraints, costs, and math model elements.
See also
mp_idx_manager
.
- add_aux_data(nm, dm, mpopt)
Builds auxiliary data and adds it to the model.
mm.add_aux_data(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Calls the build_aux_data() method and assigns the result to the
aux_data
property. The base build_aux_data() method, which simply callsbuild_base_aux_data()
, is defined inmp.mm_shared_pfcpf
(and inmp.math_model_opf
) allowing it to be shared across math models for different tasks (PF and CPF).
- build_base_aux_data(nm, dm, mpopt)
Builds base auxiliary data, including node types & variable initial values.
ad = mm.build_base_aux_data(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
- Output:
ad (struct) – struct of auxiliary data
- add_vars(nm, dm, mpopt)
Add variables to the model.
mm.add_vars(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Adds system variables, then calls the
add_vars()
method for each math model element.
- add_system_vars(nm, dm, mpopt)
Add system variables to the model.
mm.add_system_vars(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Variables which correspond to a specific math model element should be added by that element’s
add_vars()
method. Other variables can be added byadd_system_vars()
. In this base class this method does nothing.
- add_constraints(nm, dm, mpopt)
Add constraints to the model.
mm.add_constraints(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Adds system constraints, then calls the
add_constraints()
method for each math model element.
- add_system_constraints(nm, dm, mpopt)
Add system constraints to the model.
mm.add_system_constraints(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Constraints which correspond to a specific math model element should be added by that element’s
add_constraints()
method. Other constraints can be added byadd_system_constraints()
. In this base class, it simply callsadd_node_balance_constraints()
.
- add_node_balance_constraints(nm, dm, mpopt)
Add node balance constraints to the model.
mm.add_node_balance_constraints(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
In this base class this method does nothing.
- add_costs(nm, dm, mpopt)
Add costs to the model.
mm.add_costs(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Adds system costs, then calls the
add_costs()
method for each math model element.
- add_system_costs(nm, dm, mpopt)
Add system costs to the model.
mm.add_system_costs(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
Costs which correspond to a specific math model element should be added by that element’s
add_costs()
method. Other variables can be added byadd_system_costs()
. In this base class this method does nothing.
- solve_opts(nm, dm, mpopt)
Return an options struct to pass to the solver.
opt = mm.solve_opts(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
- Output:
opt (struct) – options struct for solver
In this base class, returns an empty struct.
- update_nm_vars(mmx, nm)
Update network model variables from math model solution.
nm_vars = mm.update_nm_vars(mmx, nm)
- Inputs:
mmx (double) – vector of math model variable
x
nm (
mp.net_model
) – network model object
- Output:
nm_vars (struct) – updated network model variables
Returns a struct with the network model variables as fields. The
mm.aux_data.var_map
cell array is used to track mappings of math model variables back to network model variables. Each entry is itself a 7-element cell array of the form{nm_var_type, nm_i1, nm_iN, nm_idx, mm_i1, mm_iN, mm_idx}
where
nm_var_type
- network model variable type (e.g.va
,vm
,zr
,zi
)nm_i1
- starting index for network model variable typenm_iN
- ending index for network model variable typenm_idx
- vector of indices for network model variable typemm_i1
- starting index for math model variablemm_iN
- ending index for math model variablemm_idx
- vector of indices for math model variable
Uses either
i1:iN
(ifi1
is not empty) oridx
as the indices, unless both are empty, in which case it uses':'
.
- data_model_update(nm, dm, mpopt)
Update data model from math model solution.
dm = mm.data_model_update(nm, dm, mpopt)
- Inputs:
nm (
mp.net_model
) – network model objectdm (
mp.data_model
) – data model objectmpopt (struct) – MATPOWER options struct
- Output:
dm (
mp.data_model
) – updated data model object
Calls the
data_model_update()
method for each math model element.
- network_model_x_soln(nm)
Convert solved state from math model to network model solution.
nm = mm.network_model_x_soln(nm)
- Input:
nm (
mp.net_model
) – network model object- Output:
nm (
mp.net_model
) – updated network model object
Calls convert_x_m2n() to which is defined in a subclass of in
mp.mm_shared_pfcpf
(and ofmp.math_model_opf
) allowing it to be shared across math models for different tasks (PF and CPF).