Using apprentice to construct and use Rational Approximation Surrogate Model

Overview

Rational approximation models are surrogate models that can be used to approximate a continuous function. The rational approximation can be constructed with numerator order \(m\in\mathbb{Z}^+\) and denominator order \(n\in\mathbb{Z}^+\).

In this tutorial, we describe how to setup the surrogate model construction problem, the options to construct the rational approximation model, how to store and use the the rational approximation model. More specifically, in this tutorial, you will be shown how to:

Test the install
Set up the rational approximation surrogate model construction problem
Construct the rational approximation surrogate model
Use the rational approximation surrogate model

Getting started

To install apprentice, execute the following commands:

git clone git@github.com:HEPonHPC/apprentice.git
cd  apprentice/
pip install .
cd ..

Then, test the installation as described in the test installation documentation.

Construct rational approximation surrogate model

There are multiple ways to construct a rational approximation object.

From interpolation points

Before constructing the object

To construct a rational approximation object using from_interpolation_points, we need data of size \(d \times N_p\), where \(d\) is the dimension and the \(N_p\) is the number of data points. Note that \(N_p \ge {d + m \choose m} + {d + n \choose n}\). Additionally, we need arguments that describe the strategy, order and other relevant model parameters:

from apprentice import RationalApproximation
R = RationalApproximation.from_interpolation_points(X,Y,
                                                    m = <int>,
                                                    n = <int>,
                                                    strategy = <int>,
                                                    pnames=[
                                                            <str>,
                                                            <str>,
                                                            ...
                                                    ])

In this call,

X is 2-D an array of size \(d \times N_p\) and it is the x data values to fit
Y is 1-D an array of size \(N_p\) and it is the y data values to fit
m is the order of the numerator polynomial
n is the order of the denominator polynomial
pnames are the names of the dimension and it is an array of size \(d\).
strategy is the strategy to use
- strategy = "1.1": find pole-free coefficients of the rational approximation with numerator order \(m\) and denominator order \(1\)
- strategy = "2.1": find coefficients of the rational approximation with numerator order \(m\) and denominator order \(n\). The resulting rational approximation may contain poles using the linear algebra technique proposed in our paper practical algorithms for multivariate rational approximation [arXiv].
- strategy = "2.2": find coefficients of the rational approximation with numerator order \(m\) and denominator order \(n\). F = p/q is reformulated as 0 = p - qF using the Vandermonde matrices. That defines the problem Ax = b and we solve for x using using Singular Value Decomposition (SVD), exploiting A = U x S x V.T. There is an additional manipulation exploiting on setting the constant coefficient in q to 1. The resulting rational approximation may contain poles.
- strategy = "2.3": find coefficients of the rational approximation with numerator order \(m\) and denominator order \(n\). F = p/q is reformulated as 0 = p - qF using the Vandermonde matrices. That defines the problem Ax = b and we solve for x using using Singular Value Decomposition (SVD), exploiting A = U x S x V.T. We get the solution as the last column in V (corresponds to the smallest singular value). The resulting rational approximation may contain poles.
- strategy = "3.1": find coefficients of the rational approximation with numerator order \(m\) and denominator order \(n\) with minimal number of poles. The number of poles is reduced using the semi-infinite programming technique proposed in our paper practical algorithms for multivariate rational approximation [arXiv].

For each strategy above, there maybe additional parameters, some of which are described below. A complete list of available parameters is described in code documentation

strategy = "1.1"
- fit_solver=<str>: fit solver to use. Examples include:
  - ipopt
  - filter
  - scipy
  If ipopt or filter is used, then the optimization problem is solved using AMPL models via Pyomo. Additionally, you can use any solver that can optimize a quadratic objective function with linear constraints and compatible with Pyomo. Please note that if you use ipopt or filter or any other solver as described above, then the executable of the solver needs to be set up in your bash environment for Pyomo to find.
- use_abstract_model=<bool>: if the fit solver used requires the construction of AMPL models, then using a True value in this parameter, will construct abstract Pyomo models. On the other hand, if a false value is used then a concrete Pyomo model will be constructed. See Pyomo documentation for more details
strategy = "3.1"
- fit_solver=<str>: solver to use in the outer optimization. Examples include:
  - ipopt
  - filter
  - scipy
  If ipopt or filter is used, then the optimization problem is solved using AMPL models via Pyomo. Additionally, you can use any solver that can optimize a quadratic objective function with linear constraints and compatible with Pyomo. Please note that if you use ipopt or filter or any other solver as described above, then the executable of the solver needs to be set up in your bash environment for Pyomo to find.
- local_solver=<str>: solver to use in the inner (local) optimization. Examples include:
  - ipopt
  - scipy
  If ipopt is used, then the optimization problem is solved using AMPL models via Pyomo. Additionally, you can use any solver that can optimize a nonlinear objective function and compatible with Pyomo. Please note that if you use ipopt or filter or any other solver as described above, then the executable of the solver needs to be set up in your bash environment for Pyomo to find.

After constructing the object

Once the rational approximation is constructed using from_interpolation_points, the coefficients and other metrics of the rational approximation fit can be obtained into a variable as a dict using:

R_output = R.as_dict

Additionally, to save the coefficients and other metrics of the rational approximation fit to a file at location <file location> use:

R.save(<file location>)

From data structure

Construct a saved rational approximation object using from_data_structure from a variable R_output:

R_from_data_structure = RationalApproximation.from_data_structure(R_output)

From file

Construct a saved rational approximation object using from_file from file location <file location> using:

R_from_file = RationalApproximation.from_file(tmp_file)

Operations allowed on the rational approximation object

The following operations can be performed on a constructed rational approximation object R.

y = R(x): compute the rational approximation at a single point x, an array of size \(d\). y is a single value of type float
Y = R.f_X(X): compute the rational approximation at multiple points X, an array of size \(d \times N_p\). Y is an array of size \(N_p\).
R_output = R.as_dict: get the coefficients and other metrics of the rational approximation fit into a variable. R_output is a dict.
R.save(<file location>): save the coefficients and other metrics of the rational approximation fit into a file at location <file location>
v = R.coeff_norm: get 1-norm of the coefficients. v is a single value of type float
v2 = R.coeff2_norm: get 2-norm of the coefficients. v2 is a single value of type float
g = R.gradient(x): get the gradient of the rational approximation at point x, an array of size \(d\). g is an array of size \(d\).

More information about the code is in the code documentation for rational approximation. Additionally, the rational approximation unit test script contains the construction and usage of the operations over the rational approximation object.