ExternalGreyBoxModel

(class from pyomo.contrib.pynumero.interfaces.external_grey_box)

class pyomo.contrib.pynumero.interfaces.external_grey_box.ExternalGreyBoxModel

Bases: object

This is the base class for building external input output models for use with Pyomo and CyIpopt. See the module documentation above, and documentation of individual methods.

There are examples in: pyomo/contrib/pynumero/examples/external_grey_box/react-example/

Most methods are documented in the class itself. However, there are methods that are not implemented in the base class that may need to be implemented to provide support for certain features.

Hessian support:

If you would like to support Hessian computations for your external model, you will need to implement the following methods to support setting the multipliers that are used when computing the Hessian of the Lagrangian. - set_equality_constraint_multipliers: see documentation in method - set_output_constraint_multipliers: see documentation in method You will also need to implement the following methods to evaluate the required Hessian information:

def evaluate_hessian_equality_constraints(self):

Compute the product of the equality constraint multipliers with the hessian of the equality constraints. E.g., y_eq^k is the vector of equality constraint multipliers from set_equality_constraint_multipliers, w_eq(u)=0 are the equality constraints, and u^k are the vector of inputs from set_inputs. This method must return H_eq^k = sum_i (y_eq^k)_i * grad^2_{uu} w_eq(u^k)

def evaluate_hessian_outputs(self):

Compute the product of the output constraint multipliers with the hessian of the outputs. E.g., y_o^k is the vector of output constraint multipliers from set_output_constraint_multipliers, u^k are the vector of inputs from set_inputs, and w_o(u) is the function that computes the vector of outputs at the values for the input variables. This method must return H_o^k = sum_i (y_o^k)_i * grad^2_{uu} w_o(u^k)

def evaluate_hessian_objective(self):

Compute the hessian of the objective

Examples that show Hessian support are also found in: pyomo/contrib/pynumero/examples/external_grey_box/react-example/

__init__()

Methods

__init__()
equality_constraint_names()	Provide the list of string names corresponding to any residuals for this external model.
evaluate_equality_constraints()	Compute the residuals from the model (using the values set in input_values) and return as a numpy array
evaluate_grad_objective([out])	Compute the gradient of the objective from the values set in input_values
evaluate_jacobian_equality_constraints()	Compute the derivatives of the residuals with respect to the inputs (using the values set in input_values).
evaluate_jacobian_outputs()	Compute the derivatives of the outputs with respect to the inputs (using the values set in input_values).
evaluate_objective()	Compute the objective from the values set in input_values
evaluate_outputs()	Compute the outputs from the model (using the values set in input_values) and return as a numpy array
finalize_block_construction(pyomo_block)	Implement this callback to provide any additional specifications to the Pyomo block that is created to represent this external grey box model.
get_equality_constraint_scaling_factors()	This method is called by the solver interface to get desired values for scaling the equality constraints.
get_output_constraint_scaling_factors()	This method is called by the solver interface to get desired values for scaling the constraints with output variables.
has_objective()
input_names()	Provide the list of string names to corresponding to the inputs of this external model.
n_equality_constraints()	This method returns the number of equality constraints.
n_inputs()	This method returns the number of inputs.
n_outputs()	This method returns the number of outputs.
output_names()	Provide the list of string names corresponding to the outputs of this external model.
set_equality_constraint_multipliers(...)	This method is called by the solver to set the current values for the multipliers of the equality constraints.
set_input_values(input_values)	This method is called by the solver to set the current values for the input variables.
set_output_constraint_multipliers(...)	This method is called by the solver to set the current values for the multipliers of the output constraints.

Member Documentation

equality_constraint_names()

Provide the list of string names corresponding to any residuals for this external model. These should be in the order corresponding to values returned from evaluate_residuals. Return an empty list if there are no equality constraints.

evaluate_equality_constraints()

Compute the residuals from the model (using the values set in input_values) and return as a numpy array

evaluate_grad_objective(out=None)

Compute the gradient of the objective from the values set in input_values

evaluate_jacobian_equality_constraints()

Compute the derivatives of the residuals with respect to the inputs (using the values set in input_values). This should be a scipy matrix with the rows in the order of the residual names and the cols in the order of the input variables.

evaluate_jacobian_outputs()

Compute the derivatives of the outputs with respect to the inputs (using the values set in input_values). This should be a scipy matrix with the rows in the order of the output variables and the cols in the order of the input variables.

evaluate_objective() → float

Compute the objective from the values set in input_values

evaluate_outputs()

Compute the outputs from the model (using the values set in input_values) and return as a numpy array

finalize_block_construction(pyomo_block)

Implement this callback to provide any additional specifications to the Pyomo block that is created to represent this external grey box model.

Note that pyomo_block.inputs and pyomo_block.outputs have been created, and this callback provides an opportunity to set initial values, bounds, etc.

get_equality_constraint_scaling_factors()

This method is called by the solver interface to get desired values for scaling the equality constraints. None means no scaling is desired. Note that, depending on the solver, one may need to set solver options so these factors are used

get_output_constraint_scaling_factors()

This method is called by the solver interface to get desired values for scaling the constraints with output variables. Returning None means that no scaling of the output constraints is desired. Note that, depending on the solver, one may need to set solver options so these factors are used

input_names()

Provide the list of string names to corresponding to the inputs of this external model. These should be returned in the same order that they are to be used in set_input_values.

n_equality_constraints()

This method returns the number of equality constraints. You do not need to overload this method in derived classes.

n_inputs()

This method returns the number of inputs. You do not need to overload this method in derived classes.

n_outputs()

This method returns the number of outputs. You do not need to overload this method in derived classes.

output_names()

Provide the list of string names corresponding to the outputs of this external model. These should be in the order corresponding to values returned from evaluate_outputs. Return an empty list if there are no computed outputs.

set_equality_constraint_multipliers(eq_con_multiplier_values)

This method is called by the solver to set the current values for the multipliers of the equality constraints. The derived class must cache these if necessary for any subsequent calls to evaluate_hessian_equality_constraints

set_input_values(input_values)

This method is called by the solver to set the current values for the input variables. The derived class must cache these if necessary for any subsequent calls to evaluate_outputs or evaluate_derivatives.

set_output_constraint_multipliers(output_con_multiplier_values)

This method is called by the solver to set the current values for the multipliers of the output constraints. The derived class must cache these if necessary for any subsequent calls to evaluate_hessian_outputs