Low-level API

initialize(printfile, summfile, leniw = 30500, lenrw = 60000) -> SnoptWorkspace
initialize(f, printfile, summfile, leniw = 30500, lenrw = 60000)

Open a SNOPT workspace with integer and real work arrays of length leniw and lenrw (at least 500), and return it. printfile and summfile are the paths of the SNOPT log and summary; "" writes no file. snmemb gives the sizes for a large problem.

The second form calls f(workspace), closes the workspace, also on error, and returns the value of f. Close a workspace from the first form with close.

Only one workspace is open per Julia process, so initialize closes the previous one; do not call it from a callback. Throws an error if the SNOPT library is not loaded.

Examples

initialize("", "") do workspace
    set_option!(workspace, "Major print level", 0)
    # Build and solve a low-level problem.
end

SnoptWorkspace

SNOPT session with its integer and real work arrays.

Create a workspace with initialize, and close it with close or with the do form of initialize. isopen(workspace) tells if it is still open. Only one workspace can be open in a Julia process: initialize closes the previous one. snopt manages its own workspace, so this type is needed only for the Low-level interface.

The only public field is iw, the integer work array, which the callback builders make_objfun, make_confun and make_usrfun_c take as an argument.

set_option!(ws, option::String) -> Int
set_option!(ws, name::String, value::Real) -> Int

Set one SNOPT option in the workspace ws and return 0.

ws is an open SNOPT.SnoptWorkspace or a low-level problem. The first form takes the full option text, for example "Hessian limited memory". The second form takes the option name and a number, for example set_option!(ws, "Major iterations limit", 500).

Throws an ArgumentError if SNOPT does not accept the option, if value is a Bool or not finite, or if the workspace is closed. To set options in snopt, use its options keyword instead; see Set solver options.

read_options(ws, specsfile::String) -> Int

Read SNOPT options from the specs file specsfile into the workspace ws, and return the SNOPT status code.

ws is an open SNOPT.SnoptWorkspace or a low-level problem. The status code is 101 if SNOPT read the file without errors; otherwise SNOPT.jl shows a warning, and specs_status_message explains the code. Throws an ArgumentError if the file does not exist. See Set solver options for the file format.

specs_status_message(info::Int) -> String

Return a description of the status code info from read_options.

101 means that SNOPT read the specs file without errors. A code info > 134 means that SNOPT found info - 134 errors in the file.

snmemb(m, n, neJ, negCon, nnCon, nnObj, nnJac; options = nothing,
       printfile = "", summfile = "") -> SnoptMemory

Return the minimum workspace sizes that SNOPT needs for an snOptB or snOptC problem.

The arguments are the problem dimensions: m constraint rows (at least 1), n variables, neJ Jacobian entries, negCon nonlinear Jacobian entries, nnCon nonlinear constraints, nnObj nonlinear objective variables and nnJac nonlinear Jacobian variables. Some options change the sizes, so pass the options that the solve will use.

snmemb opens and closes a temporary workspace, so it closes any open workspace. Throws an ArgumentError if the dimensions are not consistent.

Examples

memory = snmemb(m, n, neJ, negCon, nnCon, nnObj, nnJac)
initialize("", "", memory.miniw, memory.minrw) do workspace
    # Build and solve the problem.
end

SnoptMemory

Minimum workspace sizes returned by snmemb.

Fields

• info: SNOPT status code of the estimate. 100 and 104 mean success.
• miniw: minimum length of the integer work array.
• minrw: minimum length of the real work array.

AbstractSnoptProblem

Supertype of the low-level problem types SnoptA, SnoptB and SnoptC.

Each problem holds a SNOPT.SnoptWorkspace, the problem data and the user functions. snopt! solves any subtype in place.

SnoptA(ws, nf, n, objadd, objrow, iAfun, jAvar, A, iGfun, jGvar,
       xlow, xupp, flow, fupp, x, xstate, xmul, F, Fstate, Fmul,
       status, nS, num_inf, sum_inf, usrfun)

Low-level problem for SNOPT's snOptA interface; solve it with snopta!. The positional arguments are the fields below. See Low-level interface.

The objective and the constraints form one vector F(x) of nf rows, with the objective in row objrow. The derivatives of F are split into constant entries and entries that usrfun computes.

Fields

• ws: open SNOPT.SnoptWorkspace.
• nf, n: number of rows of F and number of variables.
• objadd, objrow: constant added to the objective, and its row (0 for none).
• iAfun, jAvar, A: rows, columns (Int32) and values of the constant entries.
• iGfun, jGvar: rows and columns (Int32) of the entries that usrfun computes.
• xlow, xupp, flow, fupp: bounds of x (length n) and of F (length nf); ±1.0e20 means no bound.
• x, xstate, xmul: variables, basis states (Int32) and multipliers, length n. x holds the starting point, then the solution.
• F, Fstate, Fmul: the same for the rows, length nf.
• status, nS, num_inf, sum_inf: outputs; pass 0, 0, 0, 0.0.
• usrfun: function from make_usrfun_a.

SnoptB(ws, n, nc, m_eff, nnobj, x, bl, bu, hs, J, obj_val, status, lambda,
       objfun, confun, nS = 0)

Low-level problem for SNOPT's snOptB interface, with separate objective and constraint functions; solve it with snoptb!. The positional arguments are the fields below. See Low-level interface.

Fields

• ws: open SNOPT.SnoptWorkspace.
• n, nc: number of variables and of constraints; all constraints are nonlinear.
• m_eff: number of rows, max(nc, 1); SNOPT needs at least one.
• nnobj: the objective is nonlinear in x[1:nnobj]; usually n.
• x, bl, bu, hs: values, bounds and basis states (Int32) of the variables followed by one slack variable per row, length n + m_eff. ±1.0e20 means no bound; hs is zero for a cold start.
• J: m_eff × n sparsity pattern, a SparseMatrixCSC{Float64, Int32} with at least one entry.
• obj_val, status, lambda: outputs; pass 0.0, 0, Float64[].
• objfun, confun: from make_objfun, and from make_confun or make_dummy_confun.
• nS: number of superbasic variables; 0 for a cold start.

SnoptProblem

Alias for SnoptB.

SnoptC(ws, n, nc, m_eff, nnobj, x, bl, bu, hs, J, obj_val, status, lambda,
       usrfun, nS = 0)

Low-level problem for SNOPT's snOptC interface, with one function for the objective and the constraints. Solve it with snoptc!.

The fields are the same as those of SnoptB, except that one function usrfun replaces objfun and confun. Build usrfun with make_usrfun_c. See Low-level interface for an example.

snopt!(prob::AbstractSnoptProblem; start = "Cold", name = "Julia",
       snlog = nothing, snstop = nothing) -> Int

Solve the low-level problem prob in place with snopta!, snoptb! or snoptc!, and return the SNOPT status code.

start is "Cold", "Warm" (from the basis in prob) or "Hot" (also reuses the factorization and Hessian of the previous solve of prob in the same workspace). snlog, snstop and name work as in snopt.

Throws an ArgumentError if the workspace is closed, a solve is running, or start or name is not valid. An error in a user function is thrown again after the solve.

snopta!(prob::SnoptA; start = "Cold", name = "Julia", snlog = nothing,
        snstop = nothing) -> Int

Solve prob in place with SNOPT's snOptA interface and return the SNOPT status code.

After the solve, prob.x, prob.F, prob.xmul, prob.Fmul, prob.xstate, prob.Fstate and prob.status hold the result. The keywords are the same as for snopt!. If prob.usrfun gives no derivatives, set the option "Derivative option" to 0 before the solve.

Throws a DimensionMismatch if the array lengths in prob do not agree.

snoptb!(prob::SnoptB; start = "Cold", name = "Julia", snlog = nothing,
        snstop = nothing) -> Int

Solve prob in place with SNOPT's snOptB interface and return the SNOPT status code.

After the solve, prob.x, prob.obj_val, prob.lambda, prob.hs, prob.nS and prob.status hold the result. The keywords are the same as for snopt!.

snoptc!(prob::SnoptC; start = "Cold", name = "Julia", snlog = nothing,
        snstop = nothing) -> Int

Solve prob in place with SNOPT's snOptC interface and return the SNOPT status code.

After the solve, prob.x, prob.obj_val, prob.lambda, prob.hs, prob.nS and prob.status hold the result. The keywords are the same as for snopt!.

make_usrfun_a(eval_F; eval_G = nothing, callback = nothing)

Wrap eval_F(F, x) and eval_G(G, x) in the user function of a SnoptA problem.

eval_F(F, x) writes every row value into F. eval_G(G, x) writes the derivative at position (iGfun[k], jGvar[k]) into G[k]. If eval_G is nothing, SNOPT estimates the derivatives by finite differences; then set the option "Derivative option" to 0.

If callback is a function, it is called after each evaluation of F with a NamedTuple with the fields kind = :function, x and F. If it returns false, SNOPT stops.

make_objfun(eval_obj, eval_grad, ws_iw; callback = nothing)

Wrap eval_obj(x) and eval_grad(g, x) in the objective function of a SnoptB problem.

eval_obj(x) returns the objective value; eval_grad(g, x) writes every entry of the gradient into g. Pass the integer work array workspace.iw as ws_iw.

If callback is a function, it is called after each objective evaluation with a NamedTuple with the fields kind = :objective, mode, major_iter, minor_iter, x and f. If it returns false, SNOPT stops. During a solve, major_iter and minor_iter are 0; use snlog for iteration counts.

make_confun(eval_con, eval_jac, J, ws_iw; callback = nothing)
make_confun(eval_con, eval_jac, J)

Wrap eval_con(c, x) and eval_jac(vals, x) in the constraint function of a SnoptB problem.

eval_con(c, x) writes every constraint value into c. eval_jac(vals, x) writes the Jacobian entries into vals, in the order of J.nzval. Pass the integer work array workspace.iw as ws_iw.

If callback is a function, it is called after each constraint evaluation with a NamedTuple with the fields kind = :constraint, mode, major_iter, minor_iter, x and c. If it returns false, SNOPT stops. During a solve, major_iter and minor_iter are 0; use snlog for iteration counts.

make_dummy_confun()

Return a constraint function that does nothing, for a SnoptB problem without constraints.

SNOPT needs a constraint function even when there are no nonlinear constraints.

make_usrfun_c(eval_obj, eval_grad, eval_con, eval_jac, J, ws_iw; callback = nothing)
make_usrfun_c(eval_obj, eval_grad, eval_con, eval_jac, J)

Wrap the objective and constraint functions in the user function of a SnoptC problem.

The four functions have the same form as in snopt: eval_obj(x) returns the objective, eval_grad(g, x) writes the gradient, eval_con(c, x) writes the constraint values, and eval_jac(vals, x) writes the Jacobian entries in the order of J.nzval. Pass workspace.iw as ws_iw.

If callback is a function, it is called after each evaluation with a NamedTuple with the fields kind = :combined, mode, major_iter, minor_iter, x, f and c. If it returns false, SNOPT stops. During a solve, major_iter and minor_iter are 0; use snlog for iteration counts.

make_snlog(callback)

Wrap callback in a function that SNOPT can call once per major iteration.

SNOPT.jl calls callback with a SnoptMajorLog. The function replaces SNOPT's routine snLog, which writes the major-iteration lines of the print and summary files, so these files have no such lines. SNOPT ignores the return value of callback; use make_snstop to stop the solve. An exception from callback is thrown again after the solve ends. The solve functions call make_snlog when they receive the snlog keyword, so a direct call is rarely necessary.

make_snstop(callback)

Wrap callback in a function that SNOPT can call once per major iteration.

SNOPT.jl calls callback with a SnoptStopEvent. If it returns false, SNOPT stops with status code 74 (SnoptStatus.StopInMonitor). The solve functions call make_snstop when they receive the snstop keyword, so a direct call is rarely necessary.