ExternalFunction

(class from pyomo.core.base.external)

class pyomo.core.base.external.ExternalFunction(*args, **kwargs)

Bases: Component

Interface to an external (non-algebraic) function.

ExternalFunction provides an interface for declaring general user-provided functions, and then embedding calls to the external functions within Pyomo expressions.

Note

Just because you can express a Pyomo model with external functions does not mean that the resulting model is solvable. In particular, linear solvers do not accept external functions. The AMPL Solver Library (ASL) interface does support external functions for general nonlinear solvers compiled against it, but only allows functions in compiled libraries through the AMPLExternalFunction interface.

__init__(*args, **kwargs)

Construct a reference to an external function.

There are two fundamental interfaces supported by ExternalFunction: Python callback functions and AMPL external functions.

Python callback functions (PythonCallbackFunction interface)

Python callback functions can be specified one of two ways:

1. FGH interface:

A single external function call with a signature matching the evaluate_fgh() method.

2. Independent functions:

One to three functions that can evaluate the function value, gradient of the function [partial derivatives] with respect to its inputs, and the Hessian of the function [partial second derivatives]. The function interface expects a function matching the prototype:

def function(*args): float

The gradient and hessian interface expect functions matching the prototype:

def gradient_or_hessian(args, fixed=None): List[float]

Where args is a tuple of function arguments and fixed is either None or a list of values equal in length to args indicating which arguments are currently fixed (True) or variable (False).

ASL function libraries (AMPLExternalFunction interface)

Pyomo can also call functions compiled as part of an AMPL External Function library (see the Imported functions section in the Hooking your solver to AMPL report). Links to these functions are declared by creating an ExternalFunction and passing the compiled library name (or path) to the library keyword and the name of the function to the function keyword.

Methods

__init__(*args, **kwargs)	Construct a reference to an external function.
clear_suffix_value(suffix_or_name[, expand])	Clear the suffix value for this component data
cname(*args, **kwds)	DEPRECATED.
construct([data])	API definition for constructing components
display([ostream, verbose, prefix])
evaluate(args)	Return the value of the function given the specified arguments
evaluate_fgh(args[, fixed, fgh])	Evaluate the function and gradients given the specified arguments
get_arg_units()	Return the units for this ExternalFunctions arguments
get_suffix_value(suffix_or_name[, default])	Get the suffix value for this component data
get_units()	Return the units for this ExternalFunction
getname([fully_qualified, name_buffer, ...])	Returns the component name associated with this object.
is_component_type()	Return True if this class is a Pyomo component
is_constructed()	Return True if this class has been constructed
is_expression_type([expression_system])	Return True if this numeric value is an expression
is_indexed()	Return true if this component is indexed
is_logical_type()	Return True if this class is a Pyomo Boolean object.
is_named_expression_type()	Return True if this numeric value is a named expression
is_numeric_type()	Return True if this class is a Pyomo numeric object
is_parameter_type()	Return False unless this class is a parameter object
is_reference()	Return True if this object is a reference.
is_variable_type()	Return False unless this class is a variable object
model()	Returns the model associated with this object.
parent_block()	Returns the parent of this object.
parent_component()	Returns the component associated with this object.
pprint([ostream, verbose, prefix])	Print component information
reconstruct([data])	REMOVED: reconstruct() was removed in Pyomo 6.0.
root_block()	Return self.model()
set_suffix_value(suffix_or_name, value[, expand])	Set the suffix value for this component data
type()	DEPRECATED.
valid_model_component()	Return True if this can be used as a model component.

Attributes

active	Return the active attribute
ctype	Return the class type for this component
local_name	Get the component name only within the context of the immediate parent container.
name	Get the fully qualified component name.

Member Documentation

clear_suffix_value(suffix_or_name, expand=True)

Clear the suffix value for this component data

cname(*args, **kwds)

DEPRECATED.

Deprecated since version 5.0: The cname() method has been renamed to getname(). The preferred method of obtaining a component name is to use the .name property, which returns the fully qualified component name. The .local_name property will return the component name only within the context of the immediate parent container.

construct(data=None)

API definition for constructing components

evaluate(args)

Return the value of the function given the specified arguments

Parameters:

args (Iterable) – Iterable containing the arguments to pass to the external function. Non-native type elements will be converted to a native value using the value() function.

Returns:

The return value of the function evaluated at args

Return type:

float

evaluate_fgh(args, fixed=None, fgh=2)

Evaluate the function and gradients given the specified arguments

This evaluates the function given the specified arguments returning a 3-tuple of (function value [f], list of first partial derivatives [g], and the upper triangle of the Hessian matrix [h]).

Parameters:

• args (Iterable) – Iterable containing the arguments to pass to the external function. Non-native type elements will be converted to a native value using the value() function.

• fixed (Optional[List[bool]]) – List of values indicating if the corresponding argument value is fixed. Any fixed indices are guaranteed to return 0 for first and second derivatives, regardless of what is computed by the external function.

• fgh ({0, 1, 2}) –

  What evaluations to return:

  • 0: just return function evaluation

  • 1: return function and first derivatives

  • 2: return function, first derivatives, and hessian matrix

  Any return values not requested will be None.

Returns:

• f (float) – The return value of the function evaluated at args

• g (List[float] or None) – The list of first partial derivatives

• h (List[float] or None) – The upper-triangle of the Hessian matrix (second partial derivatives), stored column-wise. Element \(H_{i,j}\) (with \(0 <= i <= j < N\) are mapped using \(h[i + j*(j + 1)/2] == H_{i,j}\).

get_arg_units()

Return the units for this ExternalFunctions arguments

get_suffix_value(suffix_or_name, default=None)

Get the suffix value for this component data

get_units()

Return the units for this ExternalFunction

getname(fully_qualified=False, name_buffer=None, relative_to=None)

Returns the component name associated with this object.

Parameters:

• fully_qualified (bool) – Generate full name from nested block names

• relative_to (Block) – Generate fully_qualified names relative to the specified block.

is_component_type()

Return True if this class is a Pyomo component

is_constructed()

Return True if this class has been constructed

is_expression_type(expression_system=None)

Return True if this numeric value is an expression

is_indexed()

Return true if this component is indexed

is_logical_type()

Return True if this class is a Pyomo Boolean object.

Boolean objects include constants, variables, or logical expressions.

is_named_expression_type()

Return True if this numeric value is a named expression

is_numeric_type()

Return True if this class is a Pyomo numeric object

is_parameter_type()

Return False unless this class is a parameter object

is_reference()

Return True if this object is a reference.

is_variable_type()

Return False unless this class is a variable object

model()

Returns the model associated with this object.

parent_block()

Returns the parent of this object.

parent_component()

Returns the component associated with this object.

pprint(ostream=None, verbose=False, prefix='')

Print component information

reconstruct(data=None)

REMOVED: reconstruct() was removed in Pyomo 6.0.

Re-constructing model components was fragile and did not correctly update instances of the component used in other components or contexts (this was particularly problemmatic for Var, Param, and Set). Users who wish to reproduce the old behavior of reconstruct(), are comfortable manipulating non-public interfaces, and who take the time to verify that the correct thing happens to their model can approximate the old behavior of reconstruct with:

component.clear() component._constructed = False component.construct()

root_block()

Return self.model()

set_suffix_value(suffix_or_name, value, expand=True)

Set the suffix value for this component data

type()

DEPRECATED.

Return the class type for this component

Deprecated since version 5.7: Component.type() method has been replaced by the .ctype property.

valid_model_component()

Return True if this can be used as a model component.

property active

Return the active attribute

property ctype

Return the class type for this component

property local_name

Get the component name only within the context of the immediate parent container.

property name

Get the fully qualified component name.