Skip to content

Add mps to numpy array support

Recent changes implement a new feature in MPS_AUX_Parser that creates a set of numpy arrays to represent the matrices and vectors that define the bilevel optimization problem. The main addition is implementation of the method MPS_AUX_Parser._model_to_np_arrays, which uses the information of the aux file to extract objective/constraint matrices and vectors for the lower- and upper-level problems and stores them in the InstanceData object. The notation and implementation is based on the mathematical description in the BOBILib report linked on the library's webpage, particularly Eqs. (1) and (2). The arrays are then stored as a dictionary in the MPS_AUX_Parser._instance_data attribute. This dictionary has the following key, value pairs:

Key Value Dim.
leader_ul_constr_mat Upper-level constraint matrix for leader decisions A m_u \times n_x
follower_ul_constr_mat Upper-level constraint matrix for follower decisions B m_u \times n_y
leader_ll_constr_mat Lower-level constraint matrix for leader decisions C m_l \times n_x
follower_ll_constr_mat Lower-level constraint matrix for follower decisions D m_l \times n_y
ul_rhs Right-hand side vector for upper-level constraints a m_u
ll_rhs Right-hand side vector for lower-level constraints b m_l
leader_ul_obj Upper-level objective coefficients for leader decisions c_u n_x
follower_ul_obj Upper-level objective coefficients for follower decisions d_u n_y
follower_ll_obj Lower-level objective coefficients for follower decisions d_l n_y
leader_lbs Vector of leader variable lower bounds [x_1^-,x_2^-, \ldots, x_{n_x}^-] n_x
leader_ubs Vector of leader variable upper bounds [x_1^+,x_2^+, \ldots, x_{n_x}^+] n_x
follower_lbs Vector of follower variable lower bounds [y_1^-,y_2^-, \ldots, y_{n_y}^-] n_y
follower_ubs Vector of follower variable upper bounds [y_1^+,y_2^+, \ldots, y_{n_y}^+] n_y

In implementation, the dimensions are stored as attributes of the instance data:

Attribute Description Dim.
InstanceData.nr_ul_constrs Number of upper-level constraints m_u
InstanceData.nr_ll_constrs Number of lower-level constraints m_l
InstanceData.nr_ul_vars Number of upper-level variables n_x
InstanceData.nr_ll_vars Number of lower-level variables n_y

Additionally, it may be useful for users to have access to constraint coefficient matrices that capture upper- and lower-bounds on variables as well. I found this was particularly useful in my use case, where I am relaxing the integrality constraints and deriving the KKT conditions of the lower-level. In this case, it's typically easier to deal with a set matrices and vectors that store all constraint information, rather than dealing with the bounds separately. To allow the user this option, the following matrices and vectors are also created to allow easy augmentation to the original constraint matrices (e.g., A, B, C and D) and vectors (e.g., a and b) to encompass variable bounds.

Key Value Dim.
leader_bd_mat Constraint coefficients for leader variable lower- and upper-bounds (all entries are -1, 0, or 1) 2n_x \times n_x
leader_bd_vec Lower- and upper-bound vector for leader decisions 2n_x
follower_bd_mat Constraint coefficients for follower variable lower- and upper-bounds (all entries are -1, 0, or 1) 2n_y \times n_y
follower_bd_vec Lower- and upper-bound vector for leader decisions 2n_y

To augment the original constraint data with these bound data, the user should apply a simple np.hstack where applicable. Note that, consistent with the notation in the BOBILib report, all constraints are in \geq form (e.g., Ax + By \geq a for the upper-level constraints), which is accounted for in the declaration of each of these arrays.

Lastly, functionality has been added to read all mps/aux file pairs from a given directory. This is implemented as a static method in the MPS_AUX_Parser class, which takes in a root directory as argument and creates a MPS_AUX_Parser, and corresponding InstanceData object, for each mps/aux pair in the specified directory.

Merge request reports

Loading