pnes_master
- pnes_master(fcn, x0, opt)
pnes_master()- Parameterized Nonlinear Equation Solver wrapper function.[X, F, EXITFLAG, OUTPUT, JAC] = PNES_MASTER(FCN, X0, OPT) [X, F, EXITFLAG, OUTPUT, JAC] = PNES_MASTER(PROBLEM) A common wrapper function for numerical continuation methods for solving parameterized nonlinear equations. Traces the solutions of a parameterized nonlinear equation f(x) = 0, beginning from a starting point x0, where f(x) has dimension n and x has dimension n+1. In the current implementation, the last element of x is taken to be the parameter lambda, where lambda = 0 corresponds to the base solution. Inputs: FCN : handle to function that evaluates the function f(x) to be solved and its Jacobian, J(x). Calling syntax for this function is: f = FCN(x) [f, J] = FCN(x) For a parameterized function, f is n x 1, x is (n+1) x 1, and J is the n x (n+1) matrix of partial derivatives of f (rows) w.r.t. x (cols). X0 : starting value, x0, of vector x ((n+1) x 1) OPT : optional options structure with the following fields, all of which are also optional (default values shown in parentheses) alg ('DEFAULT') : determines which solver to use 'DEFAULT' : automatic, currently there is only one solver implementation, a predictor/corrector method verbose (0) - controls level of progress output displayed 0 = no progress output 1-5 = increasing levels of progress output nleqs_opt - options struct for NLEQS_MASTER used for corrector stage (see NLEQS_MASTER for details), default sets nleqs_opt.verbose to 0, otherwise to 2 if OPT.verbose > 4 solve_base (1) : 0/1 flag that determines whether or not to run a corrector stage for initial solution point, x0 parameterization (3) - choice of parameterization 1 - natural 2 - arc len 3 - pseudo arc len stop_at ('NOSE') - determines stopping criterion 'NOSE' - stop when limit or nose point is reached 'FULL' - trace full continuation curve <lam_stop> - stop upon reaching specified target lambda value max_it (2000) - maximum number of continuation steps step (0.05) - continuation step size adapt_step (0) - toggle adaptive step size feature 0 - adaptive step size disabled 1 - adaptive step size enabled adapt_step_damping (0.7) - damping factor for adaptive step sizing adapt_step_tol (1e-3) - tolerance for adaptive step sizing adapt_step_ws (1) - scale factor for default initial step size when warm-starting with adaptive step size enabled step_min (1e-4) - minimum allowed step size step_max (0.2) - maximum allowed step size default_event_tol (1e-3) - default tolerance for event functions target_lam_tol (0) - tolerance for target lambda detection, 0 means use the value of default_event_tol nose_tol (0) - tolerance for nose point detection, 0 means use the value of default_event_tol events (<empty>) - cell array of specs for user-defined event functions, passed as MY_EVENTS arg to PNE_REGISTER_EVENTS (see PNE_REGISTER_EVENTS for details). callbacks (<empty>) - cell array of specs for user-defined callback functions, to be passed as MY_CBACKS arg to PNE_REGISTER_CALLBACKS (see PNE_REGISTER_CALLBACKS for details). output_fcn (<empty>) - handle to custom output function, called by PNE_CALLBACK_DEFAULT plot - options for plotting of continuation curve by PNE_CALLBACK_DEFAULT .level (0) - control plotting of continuation curve 0 - do not plot continuation curve 1 - plot when completed 2 - plot incrementally at each continuation step 3 - same as 2, with 'pause' at each continuation step .idx (<empty>) - index of quantity to plot, passed to yfcn() .idx_default (<empty>) - function to provide default value for idx, if none provided .xname ('lam') - name of output field holding values that determine horizontal coordinates of plot .yname ('x') - name of output field holding values that determine vertical coordinates of plot .xfcn (<empty>) - handle to function that maps a value from the field of the OUTPUT indicated by value of plot.xname to a horizontal coordinate for plotting .yfcn (<empty>) - handle to function that maps a value from the field of the OUTPUT indicated by value of plot.yname and an index to be applied to that value into a vertical coordinate for plotting .xlabel ('\lambda') - label for horizontal axis .ylabel ('Variable Value') - label for vertical axis .title ('Value of Variable %d') - plot title used for plot of single variable, can use %d as placeholder for var index .title2 ('Value of Multiple Variables') - plot title used for plot of multiple variables .legend ('Variable %d') - legend label, %d can be used as placeholder for variable index warmstart (<empty>) - struct containing warm-start state, see warmstart field in OUTPUT below for details of expected fields PROBLEM : The inputs can alternatively be supplied in a single PROBLEM struct with fields corresponding to the input arguments described above: fcn, x0, opt Outputs (all optional, except X): X : solution vector x F : final function value, f(x) EXITFLAG : exit flag 1 = succeeded 0 = failed OUTPUT : output struct with the following fields: corrector - output return value from NLEQS_MASTER from final corrector run (see NLEQS_MASTER for details) iterations - N, total number of continuation steps performed events - struct array of size NE of events detected with fields: k - continuation step at which event was located name - name of detected event idx - index(es) of critical elements in corresponding event function msg - descriptive text detailing the event done_msg - message describing cause of continuation termination steps - (N+1) row vector of stepsizes taken at each continuation step lam_hat - (N+1) row vector of lambda values from prediction steps lam - (N+1) row vector of lambda values from correction steps max_lam - maximum value of parameter lambda (from OUTPUT.lam) warmstart - optional output with information needed for warm-starting an updated continuation problem, with fields: cont_steps - current value of continuation step counter direction - +1 or -1, for tracing of curve in same or opposite direction, respectively dir_from_jac_eigs - 0/1 flag to indicate whether to use the sign of the smallest eigenvalue of the Jacobian to determine the initial direction x - current solution vector z - current tangent vector xp - previous step solution vector zp - previous step tangent vector parm - function handle for current parameterization function default_parm - function handle for default parameterization fcn default_step - default step size events - current event log, same as OUTPUT.events cbs - struct containing user state information for callbacks see PNES_CALLBACK_DEFAULT for more details (others) - depends on OPT.output_fcn, by default (i.e. with no explicitly provided output function) includes fields: x_hat - NX x (N+1) matrix of solution values from prediction steps x - NX x (N+1) matrix of solution values from correction steps JAC : final Jacobian matrix, J(x) Calling syntax options: [x, f, exitflag, output, jac] = pnes_master(fcn, x0); [x, f, exitflag, output, jac] = pnes_master(fcn, x0, opt); x = pnes_master(problem); where problem is a struct with fields: fcn, x0, opt where opt is optional x = pnes_master(...); [x, f] = pnes_master(...); [x, f, exitflag] = pnes_master(...); [x, f, exitflag, output] = pnes_master(...); [x, f, exitflag, output, jac] = pnes_master(...); Example: (based on https://www.chilimath.com/lessons/advanced-algebra/systems-non-linear-equations/) function [f, J] = f1p(x) f = [ x(1) + x(2) + 6*x(3) - 1; -x(1)^2 + x(2) + 5 ]; if nargout > 1 J = [1 1 6; -2*x(1) 1 0]; end end problem = struct( ... 'fcn', @(x)f1p(x), ... 'x0', [-1; 0; 0], ... 'opt', struct('verbose', 2, 'adapt_step', 1, 'step_max', 10) ... ); [x, f, exitflag, output, jac] = pnes_master(problem);
See also
pne_callback_default(),pne_register_callbacks(),pne_register_events().