How to specify params#

params is the first argument of any criterion function in optimagic. It collects all the parameters to estimate, optimize, or differentiate over. In many optimization libraries, params must be a one-dimensional numpy array. In optimagic, it can be an arbitrary pytree (think nested dictionary) containing numbers, arrays, pandas.Series, and/or pandas.DataFrames.

Below, we show a few examples of what is possible in optimagic and discuss the advantages and drawbacks of each of them.

Again, we use the simple sphere function you know from other tutorials as an example.

A frequent choice of params is a one-dimensional numpy array. This is because one-dimensional numpy arrays are all that is supported by most optimizer libraries.

In our opinion, it is rarely a good choice to represent parameters as flat numpy arrays and then access individual parameters or sclices by positions. The only exception are simple optimization problems with very-fast-to-evaluate criterion functions where any overhead must be avoided.

If you still want to use one-dimensional numpy arrays, here is how:

import optimagic as om


def sphere(params):
    return params @ params


om.minimize(
    fun=sphere,
    params=np.arange(3),
    algorithm="scipy_lbfgsb",
)

Originally, pandas DataFrames were the mandatory format for params in optimagic. They are still highly recommended and have a few special features. For example, they allow to bundle information on start parameters and bounds together into one data structure.

Let’s look at an example where we do that:

def sphere(params):
    return (params["value"] ** 2).sum()


params = pd.DataFrame(
    data={"value": [1, 2, 3], "lower_bound": [-np.inf, 1.5, 0]},
    index=["a", "b", "c"],
)

om.minimize(
    fun=sphere,
    params=params,
    algorithm="scipy_lbfgsb",
)

DataFrames have many advantages:

  • It is easy to select single parameters or groups of parameters or work with the entire parameter vector. Especially, if you use a well designed MultiIndex.

  • It is very easy to produce publication quality LaTeX tables from them.

  • If you have nested models, you can easily update the parameter vector of a larger model with the values from a smaller one (e.g. to get good start parameters).

  • You can bundle information on bounds and values in one place.

  • It is easy to compare two params vectors for equality.

If you are sure you won’t have bounds on your parameter, you can also use a pandas.Series instead of a pandas.DataFrame.

A drawback of DataFrames is that they are not JAX compatible. Another one is that they are a bit slower than numpy arrays.

params can also be a (nested) dictionary containing all of the above and more.

def sphere(params):
    return params["a"] ** 2 + params["b"] ** 2 + (params["c"] ** 2).sum()


res = om.minimize(
    fun=sphere,
    params={"a": 0, "b": 1, "c": pd.Series([2, 3, 4])},
    algorithm="scipy_neldermead",
)

Dictionarys of arrays are ideal if you want to do vectorized computations with groups of parameters. They are also a good choice if you calculate derivatives with JAX.

While optimagic won’t stop you, don’t go too far! Having parameters in very deeply nested dictionaries makes it hard to visualize results and/or even to compare two estimation results.

If you have a one-dimensional optimization problem, the natural way to represent your params is a float:

def sphere(params):
    return params**2


om.minimize(
    fun=sphere,
    params=3,
    algorithm="scipy_lbfgsb",
)