Add external function library

doc/OnlineDocs/explanation/modeling_utils/external_functions/index.rst

@@ -0,0 +1,112 @@
+External Functions
+==================
+
+Pyomo provides a set of AMPL user-defined functions that commonly occur but cannot be easily written as Pyomo expressions.
+
+Using These External Functions
+------------------------------
+
+Build
+~~~~~
+
+You must build the Pyomo extensions to use these functions.  Run ``pyomo build-extensions`` in the terminal and make sure the ``external_functions`` build status is "ok."
+
+Example
+~~~~~~~
+
+.. doctest::
+
+    >>> import pyomo.environ as pyo
+    >>> from pyomo.common.fileutils import find_library
+    >>> flib = find_library("external_functions")
+    >>> m = pyo.ConcreteModel(name = 'ExternalFunctions')
+    >>> m.sinc = pyo.ExternalFunction(library=flib, function="sinc")
+    >>> m.x = pyo.Var()
+    >>> m.z = pyo.Var()
+    >>> m.constraint = pyo.Constraint(expr = m.z == m.sinc(m.x))
+
+Functions
+---------
+
+sinc(x)
+~~~~~~~
+
+This function is defined as:
+
+.. math::
+
+    \text{sinc}(x) = \begin{cases}
+        \sin(x) / x & \text{if } x \neq 0 \\
+        1 & \text{if } x = 0
+    \end{cases}
+
+In this implementation, the region :math:`-0.1 < x < 0.1` is replaced by a Taylor series with enough terms that the function should be at least :math:`C^2` smooth.  The difference between the function and the Tayor series is near the limits of machine precision, about :math:`1 \times 10^{-16}` for the function value,  :math:`1 \times 10^{-16}` for the first derivative, and :math:`1 \times 10^{-14}` for the second derivative.
+
+These figures show the sinc(x) function, the Taylor series and where the Taylor series is used.
+
+.. image:: figs/sinc_f.png
+
+.. image:: figs/sinc_fx.png
+
+.. image:: figs/sinc_fxx.png
+
+
+sgnsqr(x)
+~~~~~~~~~
+
+This function is defined as:
+
+.. math::
+
+    \text{sgnsqr}(x) = \text{sgn}(x)x^2
+
+This function is only $C^1$ smooth because at 0 the second derivative is undefined and the jumps from -2 to 2.  
+
+sgnsqr_c4(x)
+~~~~~~~~~~~~
+
+
+This function is defined as:
+
+.. math::
+
+    \text{sgnsqr}(x) = \begin{cases}
+        \text{sgn}(x)x^2 & \text{if } |x| \ge 0.1 \\
+        \sum_{i=0}^{11} c_i x^i & \text{if } |x| < 0.1
+    \end{cases}
+
+This function is $C^4$ smooth.  The region :math:`-0.1 < x < 0.1` is replaced by an 11th order polynomial approximates that :math:`\text{sgn}(x)x^2`.  The approximate function has a well behaved derivatives at :math:`x=0`.  If you need to use this function with very small numbers and high accuracy is important, you can scale the argument up (e.g. :math:`\text{sgnsqr\_c4}(sx)/s^2`).
+
+These figures show the sgnsqr(x) function compared to the smooth approximation sgnsqr_c4(x).
+
+.. image:: figs/sgnsqr_f.png
+
+.. image:: figs/sgnsqr_fx.png
+
+.. image:: figs/sgnsqr_fxx.png
+
+
+sgnsqrt_c4(x)
+~~~~~~~~~~~~
+
+This function is a signed square root approximation defined as:
+
+.. math::
+
+    \text{sgnsqr}(x) = \begin{cases}
+        \text{sgn}(x)|x|^{0.5} & \text{if } |x| \ge 0.1 \\
+        \sum_{i=0}^{11} c_i x^i & \text{if } |x| < 0.1
+    \end{cases}
+
+This function is $C^4$ smooth.  The region :math:`-0.1 < x < 0.1` is replaced by an 11th order polynomial approximates that :math:`\text{sgn}(x)x^2`.  The approximate function has a well behaved derivatives at :math:`x=0`.  If you need to use this function with very small numbers and high accuracy is important, you can scale the argument up (e.g. :math:`\text{sgnsqr\_c4}(sx)/s^2`).
+
+These figures show the signed square root function compared to the smooth approximation sgnsqr_c4(x).
+
+.. image:: figs/sgnsqrt_c4_err.png
+
+.. image:: figs/sgnsqrt_c4_f.png
+
+.. image:: figs/sgnsqrt_c4_fx.png
+
+.. image:: figs/sgnsqrt_c4_fxx.png
+

doc/OnlineDocs/explanation/modeling_utils/index.rst

@@ -8,7 +8,7 @@ Modeling Utilities
    latex_printer
    preprocessing
    scaling
-
+   external_functions/index
 
 
 ..

pyomo/contrib/external_functions/__init__.py

@@ -0,0 +1,10 @@
+#  ___________________________________________________________________________
+#
+#  Pyomo: Python Optimization Modeling Objects
+#  Copyright (c) 2008-2025
+#  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.
+#  ___________________________________________________________________________

pyomo/contrib/external_functions/build.py

@@ -0,0 +1,32 @@
+#  ___________________________________________________________________________
+#
+#  Pyomo: Python Optimization Modeling Objects
+#  Copyright (c) 2008-2025
+#  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.
+#  ___________________________________________________________________________
+
+import sys
+from pyomo.common.cmake_builder import build_cmake_project
+
+
+def build_external_functions(user_args=[], parallel=None):
+    return build_cmake_project(
+        targets=["src"],
+        package_name="external_functions",
+        description="Useful external function",
+        user_args=["-DBUILD_AMPLASL_IF_NEEDED=ON"] + user_args,
+        parallel=parallel,
+    )
+
+
+class ExternalFunctionBuilder(object):
+    def __call__(self, parallel):
+        return build_external_functions(parallel=parallel)
+
+
+if __name__ == "__main__":
+    build_external_functions(sys.argv[1:])

pyomo/contrib/external_functions/plugins.py

@@ -0,0 +1,17 @@
+#  ___________________________________________________________________________
+#
+#  Pyomo: Python Optimization Modeling Objects
+#  Copyright (c) 2008-2025
+#  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.
+#  ___________________________________________________________________________
+
+from pyomo.common.extensions import ExtensionBuilderFactory
+from pyomo.contrib.external_functions.build import ExternalFunctionBuilder
+
+
+def load():
+    ExtensionBuilderFactory.register("external_functions")(ExternalFunctionBuilder)

pyomo/contrib/external_functions/src/CMakeLists.txt

@@ -0,0 +1,43 @@
+#  ___________________________________________________________________________
+#
+#  Pyomo: Python Optimization Modeling Objects
+#  Copyright (c) 2008-2025
+#  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.
+#  ___________________________________________________________________________
+
+cmake_minimum_required(VERSION 3.0...3.31)
+# This was developed against CMake 3.0, and appears to comply with 3.5
+
+PROJECT( external_functions )
+
+INCLUDE(
+  "${CMAKE_CURRENT_SOURCE_DIR}/../../ampl_function_demo/src/FindASL.cmake")
+
+# Targets in this project
+OPTION(BUILD_EXTERNAL_FCN_LIBRARY
+  "Build the ASL external function example library" ON)
+
+IF( BUILD_EXTERNAL_FCN_LIBRARY )
+  ADD_LIBRARY( external_functions SHARED "functions.cpp" )
+  TARGET_LINK_LIBRARIES( external_functions
+    PUBLIC ${ASL_LIBRARY} ${CMAKE_DL_LIBS})
+  TARGET_INCLUDE_DIRECTORIES( external_functions
+    PUBLIC ${ASL_INCLUDE_DIR}
+    INTERFACE . )
+  # If you need a CPP directive defined when building the library (e.g.,
+  # for managing __declspec(dllimport) under Windows) uncomment the
+  # following:
+  #TARGET_COMPILE_DEFINITIONS( external_functions PRIVATE BUILDING_ASL_DEMO )
+  #SET_TARGET_PROPERTIES( external_functions PROPERTIES ENABLE_EXPORTS 1 )
+  INSTALL( TARGETS external_functions LIBRARY DESTINATION lib
+    RUNTIME DESTINATION lib )
+  IF( BUILD_AMPLASL )
+    # If we are building AMPL/asl (from FindASL), it is possible that we
+    # are linking against it, so we will add the appropriate dependency
+    add_dependencies(external_functions ampl_asl)
+  ENDIF()
+ENDIF()