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.