Function and module reference¶
The nonlinear optimizer¶
- uopt.uopt(x0, xs, ys, f, g, H=None, Hv=None, Jv=None, s=<function statusDefault>, opts={}, udata=None)¶
Run the UOpt nonlinear optimizer.
Run the UOpt nonlinear optimizer to minimize f(x0).
When H or Hv are provided, the Newton search directions are enabled. Otherwise only CG search directions are used.
- Parameters:
x0 (N-array) – Starting values.
xs (N-array) – Optimized values.
ys (M-array) – Solution value. Must have size M=1.
f (function(x, y, udata)) – Optimization objective function. Must write a scalar value into y as the result.
g (function(x, y, dxdy, udata)) – Function that computes the derivative of the objective function. Must write the scalar result into y and the derivative into dxdy.
H (function(x, y, dxdy, d2xdy2, udata)) – Function that computes the Hessian of the objective function. Must write the scalar result into y, the derivative into dxdy and the Hessian into d2xdy2.
Hv (function(x, y, dx, dxdy, d2xdy2, udata)) – Function that computes Hessian-vector products of the objective function. The derivative direction is in dx and has shape (N, NDD). Hv must write the scalar result into y, the (full) gradient into dxdy and the NDD Hessian-vector products into d2xdy2.
Jv (function(x, y, dx, dxdy, udata)) – Function that computes gradient-vector dot products of the objective function. The derivative direction is in dx and has shape (N, NDD). Jv must write the scalar result into y and the NDD gradient-vector dot products into dxdy.
s (function(x, y, status, udata)) – Function that is called for status output. It is given the current state x, the current result y, a dictionary with status values and the user data udata. The function s should return None or zero (0) to continue, or a non-zero value to stop the iteration.
opts (dict) – Parameters to uopt, like tolObjAbs, tolObjRel, sdirs, maxiter, etc..
udata (any) – User data that is passed to all callbacks.
- Returns:
Returns a status code. Zero indicates success.
- Return type:
The nonlinear solver¶
- uopt.usolve(x0, xs, ys, f, J, Jv=None, JTv=None, s=<function statusDefault>, opts={}, udata=None)¶
Run the UOpt nonlinear solver.
Run the UOpt nonlinear solver to find f(xs) = ys = 0.
When Jv and JTv are provided to compute forward and reverse directional derivatives, the matrix-free method is used, otherwise J must be provided for the full derivative.
- Parameters:
x0 (N-array) – Starting values.
xs (N-array) – Optimized values.
ys (M-array) – Solution values.
f (function(x, y, udata)) – Optimization objective function. Must write a scalar value into y as the result.
J (function(x, y, dxdy, udata)) – Function that computes the derivative of the objective function. Must write the scalar result into y and the derivative into dxdy.
Jv (function(x, y, dx, dxdy, udata)) – Function that computes directional derivatives of the objective function. Must write the scalar result into y, and the directional derivative d/dt f(x+t*dx) evaluated at t=0 into dxdy.
JTv (function(x, y, dy, dxdy, udata)) – Function that computes reverse directional derivatives of the objective function. Must write the scalar result into y, and the derivative d/dx dot(f(x), dy) into dxdy.
s (function(x, y, status, udata)) – Function that is called for status output. It is given the current state x, the current result y, a dictionary with status values and the user data udata. The function s should return None or zero (0) to continue, or a non-zero value to stop the iteration.
opts (dict) – Parameters to uopt, like tolObjAbs, tolObjRel, maxiter, etc..
udata (any) – User data that is passed to all callbacks.
- Returns:
Returns a status code. Zero indicates success.
- Return type:
Utility functions¶
- uopt.getSeries(sfun, sname)¶
Returns matching key values of the field sname from the history of the status function.
- uopt.getEntries(sfun, snames)¶
Returns matching fields from the history of the status function.
Returns fields from the history of the status function that have all of the fields listed in snames.
- uopt.statusDefault(x, y, status, udata)¶
Default status function, prints a line with key=value fields for each status item.
- uopt.statusHist(chain=<function statusDefault>)¶
Returns a status function.
Returns a status to be use with the parameter s of
uopt()andusolve(). After running, this status function can be given togetEntries(),getSeries()andmkPlot()- Parameters:
chain (function) – If given, call this function as well whenever the status function is called. Defaults to statusDefault.
- Returns:
Status function to be used with usolve or uopt.
- Return type:
function
- uopt.mkPlot(sfun, field, over='it', show=False, save=None, outdir='.', title=None, subtitle=None, xunit=None, yunit=None, xlim=None, ylim=None, xscale='linear', yscale='log', usetex=False, hardwareinfo=False)¶
Generate a plot of the iteration history field over the other field over.
Generate a plot of the iteration history with
matplotlib, plotting the values of history field “field” over the other field “over”.When save is a string the figure is saved under that filename. Then show is True, the plot is shown in the foreground.
- Parameters:
sfun (function) – Status function.
field (str) – Desired fieldname for y axsis, like “J” or “Er”.
over (str) – Desired fieldname for x axsis, like “it” or “tj”.
title (str) – Plot title. When None, a title is automatically generated.
subtitle (str) – Plot subtitle. When set to ‘pyinfo’, a subtitle with python information is automatically generated.
show (bool) – Show plot.
save (str) – Save plot as file save
outdir (str) – Save plot in director outdir.
xunit (str) – Add string “ (xunit)” to xlabel.
yunit (str) – Add string “ (yunit)” to ylabel.
xlim (tuple) – Set axis xlim.
ylim (tuple) – Set axis ylim.
xscale (str) – Set axis xscale.
yscale (str) – Set axis yscale.
usetex (bool) – Set usetex in matplotlib.
hardwareinfo (bool) – Add more lines to the plot title describing the hardware and OS.
- Returns:
Returns tuple of figure and axis handles.
- Return type:
figure, axis