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 from mp.math_model and therefore also from mp.element_container, opt_model, and mp_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 with mp.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 objects

• display() - display the math model object

• add_aux_data() - builds auxiliary data and adds it to the model

• build_base_aux_data() - builds base auxiliary data, including node types & variable initial values

• add_vars() - add variables to the model

• add_system_vars() - add system variables to the model

• add_constraints() - add constraints to the model

• add_system_constraints() - add system constraints to the model

• add_node_balance_constraints() - add node balance constraints to the model

• add_costs() - add costs to the model

• add_system_costs() - add system costs to the model

• solve_opts() - return an options struct to pass to the solver

• update_nm_vars() - update network model variables from math model solution

• data_model_update() - update data model from math model solution

• network_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 object

• dm (mp.data_model) – data model object

• mpopt (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 object

• dm (mp.data_model) – data model object

• mpopt (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 calls build_base_aux_data(), is defined in mp.mm_shared_pfcpf (and in mp.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 object

• dm (mp.data_model) – data model object

• mpopt (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 object

• dm (mp.data_model) – data model object

• mpopt (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 object

• dm (mp.data_model) – data model object

• mpopt (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 by add_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 object

• dm (mp.data_model) – data model object

• mpopt (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 object

• dm (mp.data_model) – data model object

• mpopt (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 by add_system_constraints(). In this base class, it simply calls add_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 object

• dm (mp.data_model) – data model object

• mpopt (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 object

• dm (mp.data_model) – data model object

• mpopt (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 object

• dm (mp.data_model) – data model object

• mpopt (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 by add_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 object

• dm (mp.data_model) – data model object

• mpopt (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 type

• nm_iN - ending index for network model variable type

• nm_idx - vector of indices for network model variable type

• mm_i1 - starting index for math model variable

• mm_iN - ending index for math model variable

• mm_idx - vector of indices for math model variable

Uses either i1:iN (if i1 is not empty) or idx 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 object

• dm (mp.data_model) – data model object

• mpopt (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 of mp.math_model_opf) allowing it to be shared across math models for different tasks (PF and CPF).