docs menu

Module Jera.Solution

Answers of solves.

A solve returns its answer with a status per lane: one lane per element for an elementwise family (Root, Minimize.bracket, Quad's one-dimensional solves), one per box for Quad.cubature and Quad.qmc, one for a structured family, and one per lane of each Rune.vmap around it. get reads an answer that converged everywhere and raises otherwise; best and ok read every lane.

ocaml

let s = Root.bracket ~tol f ~lo ~hi in
let ok = Solution.ok s in
Nx.where ok (Solution.best s) (Nx.zeros_like lo)

#type ('a, 'd) t

The type for answers of type 'a.

#type status =

#| Converged
(*
The error estimate met the tolerance.
*)
#| Budget_spent
(*
The budget ran out first.
*)
#| Not_bracketed
(*
The ends of a bracket have one sign.
*)
#| Not_finite
(*
A value of the problem's function is not finite.
*)
#| Stalled
(*
The search stopped moving without meeting the tolerance: its steps fell below the resolution of the floats, or the problem has no answer the method can reach, such as a pole in a bracket.
*)

The type for a lane's outcome.

#val get : ('a, 'd) t -> 'a

get s is the answer if every lane converged.

Raises Failure with the report of the first lane in C order that did not converge: the entry point, the lane, its status, the solve's settings, the lane's data, the budget it used, what to change, and how many other elements of its problem converged. Inside Rune.jit, get returns best and the compiled call's check raises: at once on the host, at the next wait on another set.

#val best : ('a, 'd) t -> 'a

best s is the estimate in every lane. A lane that did not converge holds its last finite estimate, and its derivative is zero.

#val ok : ('a, 'd) t -> 'd Nx.bool_t

ok s is is Converged s.

#val is : status -> ('a, 'd) t -> 'd Nx.bool_t

is st s is true in each lane whose status is st, of the lanes' shape.

#val error : ('a, 'd) t -> 'a

error s is each lane's error estimate, of the answer's structure, as its solve defines it: an estimate, never a bound.

#val evaluations : ('a, 'd) t -> 'd Nx.int32_t

evaluations s is each lane's count of the points at which the problem's function was evaluated, of the lanes' shape.

#val ptree : ('a, 'd) Nx.Ptree.t -> (('a, 'd) t, 'd) Nx.Ptree.t

ptree s is the structure of answers of structure s, so a compiled function returns one: the answer at value, the error at error, the statuses at status, the counts at evaluations, the budget used at used and the report's data under report.

#val pp : Stdlib.Format.formatter -> ('a, 'd) t -> unit

pp ppf s formats the count of lanes in each status and the report get would raise for the first lane that did not converge. It reads the statuses, so it runs eagerly.