# ___________________________________________________________________________
#
# Pyomo: Python Optimization Modeling Objects
# Copyright (c) 2008-2024
# National Technology and Engineering Solutions of Sandia, LLC
# Under the terms of Contract DE-NA0003525 with National Technology and
# Engineering Solutions of Sandia, LLC, the U.S. Government retains certain
# rights in this software.
# This software is distributed under the 3-clause BSD License.
# ___________________________________________________________________________
r"""The pyomo.contrib.pynumero.interfaces.nlp module includes abstract
classes to represent nonlinear programming problems. There are two
classes that provide different representations for the NLP.
The first interface (NLP) presents the NLP in the following form
(where all equality and inequality constraints are combined)
.. math::
\min\ & f(x) \\
s.t.\ & g_L <= g(x) <= g_U \\
& x_L <= x <= x_U
where:
- :math:`x \in R^{n_x}` are the primal variables,
- :math:`x_L \in R^{n_x}` are the lower bounds of the primal variables,
- :math:`x_U \in R^{n_x}` are the upper bounds of the primal variables,
- :math:`g: R^{n_x} \rightarrow R^{n_c}` are constraints (equality and inequality)
The second interface (ExtendedNLP) extends the definition above and
presents the NLP in the following form where the equality and
inequality constraints are separated.
.. math::
\min\ & f(x) \\
s.t.\ & h(x) = 0 \\
& q_L <= q(x) <= q_U \\
& x_L <= x <= x_U
where:
- :math:`x \in R^{n_x}` are the primal variables,
- :math:`x_L \in R^{n_x}` are the lower bounds of the primal variables,
- :math:`x_U \in R^{n_x}` are the upper bounds of the primal variables,
- :math:`h: R^{n_x} \rightarrow R^{n_eq}` are the equality constraints
- :math:`q: R^{n_x} \rightarrow R^{n_ineq}` are the inequality constraints
Note: In the case of the ExtendedNLP, it is generally assumed that
both the NLP and the ExtendedNLP interfaces are supported and
consistent (ExtendedNLP inherits from NLP). For example, a user should
be able to call set_duals or set_duals_eq and set_duals_ineq, or
mix-and-match between evaluate_jacobian or evaluate_jacobian_eq and
evaluate_jacobian_ineq.
.. rubric:: Contents
"""
import abc
[docs]
class NLP(object, metaclass=abc.ABCMeta):
[docs]
def __init__(self):
pass
[docs]
@abc.abstractmethod
def n_primals(self):
"""
Returns number of primal variables
"""
pass
[docs]
def primals_names(self):
"""
Override this to provide string names for the primal variables
"""
return [str(i) for i in range(self.n_primals())]
[docs]
@abc.abstractmethod
def n_constraints(self):
"""
Returns number of constraints
"""
pass
[docs]
def constraint_names(self):
"""
Override this to provide string names for the constraints
"""
return [str(i) for i in range(self.n_constraints())]
[docs]
@abc.abstractmethod
def nnz_jacobian(self):
"""
Returns number of nonzero values in jacobian of equality constraints
"""
pass
[docs]
@abc.abstractmethod
def nnz_hessian_lag(self):
"""
Returns number of nonzero values in hessian of the lagrangian function
"""
pass
[docs]
@abc.abstractmethod
def primals_lb(self):
"""
Returns vector of lower bounds for the primal variables
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def primals_ub(self):
"""
Returns vector of upper bounds for the primal variables
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def constraints_lb(self):
"""
Returns vector of lower bounds for the constraints
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def constraints_ub(self):
"""
Returns vector of upper bounds for the constraints
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def init_primals(self):
"""
Returns vector with initial values for the primal variables
"""
pass
[docs]
@abc.abstractmethod
def init_duals(self):
"""
Returns vector with initial values for the dual variables
of the constraints
"""
pass
[docs]
@abc.abstractmethod
def create_new_vector(self, vector_type):
"""
Creates a vector of the appropriate length and structure as
requested
Parameters
----------
vector_type: {'primals', 'constraints', 'duals'}
String identifying the appropriate vector to create.
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def set_primals(self, primals):
"""Set the value of the primal variables to be used
in calls to the evaluation methods
Parameters
----------
primals: vector_like
Vector with the values of primal variables.
"""
pass
[docs]
@abc.abstractmethod
def get_primals(self):
"""Get a copy of the values of the primal variables as
provided in set_primals. These are the values that will
be used in calls to the evaluation methods
"""
pass
[docs]
@abc.abstractmethod
def set_duals(self, duals):
"""Set the value of the dual variables for the constraints
to be used in calls to the evaluation methods (hessian_lag)
Parameters
----------
duals: vector_like
Vector with the values of dual variables for the equality constraints
"""
pass
[docs]
@abc.abstractmethod
def get_duals(self):
"""Get a copy of the values of the dual variables as
provided in set_duals. These are the values that will
be used in calls to the evaluation methods.
"""
pass
[docs]
@abc.abstractmethod
def set_obj_factor(self, obj_factor):
"""Set the value of the objective function factor
to be used in calls to the evaluation of the hessian
of the lagrangian (evaluate_hessian_lag)
Parameters
----------
obj_factor: float
Value of the objective function factor used
in the evaluation of the hessian of the lagrangian
"""
pass
[docs]
@abc.abstractmethod
def get_obj_factor(self):
"""Get the value of the objective function factor as
set by set_obj_factor. This is the value that will
be used in calls to the evaluation of the hessian
of the lagrangian (evaluate_hessian_lag)
"""
pass
[docs]
@abc.abstractmethod
def get_obj_scaling(self):
"""Return the desired scaling factor to use for the
for the objective function. None indicates no scaling.
This indicates potential scaling for the model, but the
evaluation methods should return *unscaled* values
Returns
-------
float or None
"""
pass
[docs]
@abc.abstractmethod
def get_primals_scaling(self):
"""Return the desired scaling factors to use for the
for the primals. None indicates no scaling.
This indicates potential scaling for the model, but the
evaluation methods should return *unscaled* values
Returns
-------
array-like or None
"""
pass
[docs]
@abc.abstractmethod
def get_constraints_scaling(self):
"""Return the desired scaling factors to use for the
for the constraints. None indicates no scaling.
This indicates potential scaling for the model, but the
evaluation methods should return *unscaled* values
Returns
-------
array-like or None
"""
pass
[docs]
@abc.abstractmethod
def evaluate_objective(self):
"""Returns value of objective function evaluated at the
values given for the primal variables in set_primals
Returns
-------
float
"""
pass
[docs]
@abc.abstractmethod
def evaluate_grad_objective(self, out=None):
"""Returns gradient of the objective function evaluated at the
values given for the primal variables in set_primals
Parameters
----------
out: vector_like, optional
Output vector. Its type is preserved and it
must be of the right shape to hold the output.
Returns
-------
vector_like
"""
pass
[docs]
@abc.abstractmethod
def evaluate_constraints(self, out=None):
"""Returns the values for the constraints evaluated at
the values given for the primal variales in set_primals
Parameters
----------
out: array_like, optional
Output array. Its type is preserved and it
must be of the right shape to hold the output.
Returns
-------
vector_like
"""
pass
[docs]
@abc.abstractmethod
def evaluate_jacobian(self, out=None):
"""Returns the Jacobian of the constraints evaluated
at the values given for the primal variables in set_primals
Parameters
----------
out : matrix_like (e.g., coo_matrix), optional
Output matrix with the structure of the jacobian already defined.
Returns
-------
matrix_like
"""
pass
[docs]
@abc.abstractmethod
def evaluate_hessian_lag(self, out=None):
"""Return the Hessian of the Lagrangian function evaluated
at the values given for the primal variables in set_primals and
the dual variables in set_duals
Parameters
----------
out : matrix_like (e.g., coo_matrix), optional
Output matrix with the structure of the hessian already defined. Optional
Returns
-------
matrix_like
"""
pass
[docs]
@abc.abstractmethod
def report_solver_status(self, status_code, status_message):
"""Report the solver status to NLP class using the values for the
primals and duals defined in the set methods"""
pass
[docs]
class ExtendedNLP(NLP, metaclass=abc.ABCMeta):
"""This interface extends the NLP interface to support a presentation
of the problem that separates equality and inequality constraints
"""
[docs]
def __init__(self):
super(ExtendedNLP, self).__init__()
pass
[docs]
@abc.abstractmethod
def n_eq_constraints(self):
"""
Returns number of equality constraints
"""
pass
[docs]
@abc.abstractmethod
def n_ineq_constraints(self):
"""
Returns number of inequality constraints
"""
pass
[docs]
@abc.abstractmethod
def nnz_jacobian_eq(self):
"""
Returns number of nonzero values in jacobian of equality constraints
"""
pass
[docs]
@abc.abstractmethod
def nnz_jacobian_ineq(self):
"""
Returns number of nonzero values in jacobian of inequality constraints
"""
pass
[docs]
@abc.abstractmethod
def ineq_lb(self):
"""
Returns vector of lower bounds for inequality constraints
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def ineq_ub(self):
"""
Returns vector of upper bounds for inequality constraints
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def init_duals_eq(self):
"""
Returns vector with initial values for the dual variables of the
equality constraints
"""
pass
[docs]
@abc.abstractmethod
def init_duals_ineq(self):
"""
Returns vector with initial values for the dual variables of the
inequality constraints
"""
pass
[docs]
@abc.abstractmethod
def create_new_vector(self, vector_type):
"""
Creates a vector of the appropriate length and structure as
requested
Parameters
----------
vector_type: {'primals', 'constraints', 'eq_constraints', 'ineq_constraints',
'duals', 'duals_eq', 'duals_ineq'}
String identifying the appropriate vector to create.
Returns
-------
vector-like
"""
pass
[docs]
@abc.abstractmethod
def set_duals_eq(self, duals_eq):
"""Set the value of the dual variables for the equality constraints
to be used in calls to the evaluation methods (hessian_lag)
Parameters
----------
duals_eq: vector_like
Vector with the values of dual variables for the equality constraints
"""
pass
[docs]
@abc.abstractmethod
def get_duals_eq(self):
"""Get a copy of the values of the dual variables of the equality
constraints as provided in set_duals_eq. These are the values
that will be used in calls to the evaluation methods.
"""
pass
[docs]
@abc.abstractmethod
def set_duals_ineq(self, duals_ineq):
"""Set the value of the dual variables for the inequality constraints
to be used in calls to the evaluation methods (hessian_lag)
Parameters
----------
duals_ineq: vector_like
Vector with the values of dual variables for the inequality constraints
"""
pass
[docs]
@abc.abstractmethod
def get_duals_ineq(self):
"""Get a copy of the values of the dual variables of the inequality
constraints as provided in set_duals_eq. These are the values
that will be used in calls to the evaluation methods.
"""
pass
[docs]
@abc.abstractmethod
def get_eq_constraints_scaling(self):
"""Return the desired scaling factors to use for the
for the equality constraints. None indicates no scaling.
This indicates potential scaling for the model, but the
evaluation methods should return *unscaled* values
Returns
-------
array-like or None
"""
pass
[docs]
@abc.abstractmethod
def get_ineq_constraints_scaling(self):
"""Return the desired scaling factors to use for the
for the inequality constraints. None indicates no scaling.
This indicates potential scaling for the model, but the
evaluation methods should return *unscaled* values
Returns
-------
array-like or None
"""
pass
[docs]
@abc.abstractmethod
def evaluate_eq_constraints(self, out=None):
"""Returns the values for the equality constraints evaluated at
the values given for the primal variales in set_primals
Parameters
----------
out: array_like, optional
Output array. Its type is preserved and it
must be of the right shape to hold the output.
Returns
-------
vector_like
"""
pass
[docs]
@abc.abstractmethod
def evaluate_ineq_constraints(self, out=None):
"""Returns the values of the inequality constraints evaluated at
the values given for the primal variables in set_primals
Parameters
----------
out : array_like, optional
Output array. Its type is preserved and it
must be of the right shape to hold the output.
Returns
-------
vector_like
"""
pass
[docs]
@abc.abstractmethod
def evaluate_jacobian_eq(self, out=None):
"""Returns the Jacobian of the equality constraints evaluated
at the values given for the primal variables in set_primals
Parameters
----------
out : matrix_like (e.g., coo_matrix), optional
Output matrix with the structure of the jacobian already defined.
Returns
-------
matrix_like
"""
pass
[docs]
@abc.abstractmethod
def evaluate_jacobian_ineq(self, out=None):
"""Returns the Jacobian of the inequality constraints evaluated
at the values given for the primal variables in set_primals
Parameters
----------
out : matrix_like (e.g., coo_matrix), optional
Output matrix with the structure of the jacobian already defined.
Returns
-------
matrix_like
"""
pass