solver

Find the value(s) of one or more variables that drive an expression to a root or extremum.

solver takes the SAME expression language as calculate — every operator, function, literal form, and (crucially) multi-line programs with name = expr assignments — but instead of evaluating the expression it SEARCHES for the value of the unknown(s) that drive the expression to the chosen objective:

• "find-root" (default): find where the expression equals zero. Write an equation f = g as the expression f - g and find its root.

• "find-minimum" / "find-maximum": find where the expression reaches its smallest / largest value within the bracket(s).

There are two input forms for the unknowns:

• SINGLE: variable + lower + upper — one unknown searched over the bracket [lower, upper] (lower must be below upper). This is the default golden-section engine. variable may be OMITTED when the expression has exactly one free name; the solver then auto-detects it (e.g. n in 12*n - (450 + 3*n)), needing only lower + upper.

• MULTIPLE: variables — a dict mapping each unknown name to its [lower, upper] bracket, e.g. {"x": [0, 5], "y": [-4, 2]}. This needs a multivariate engine (algorithm="nelder-mead", "powell" or "bfgs"), which searches all the unknowns jointly. Give exactly one of the two forms. Each unknown must OCCUR in the expression and must NOT be assigned by it; every OTHER name is a constant the program sets via an assignment line (e.g. "r = 0.05\np = 1000\np * (1 + r)**n - 2000" solving for n with r, p fixed). A name that is neither an unknown nor assigned is an error.

objective (optional) names what to search for — "find-root", "find-minimum", or "find-maximum"; omitted, it defaults to "find-root". (The older spellings solve, minimise/maximise and their min/max and American forms are accepted too.)

algorithm (optional) names the search engine — "golden-section-search" (the default, single-variable), "brent-parabolic" (single-variable too, parabolic interpolation with a golden-section fallback — usually faster on smooth extrema), "bisection", "ridders", "brent-dekker", "chandrupatla" or "secant" (single-variable, find-root ONLY — all five bracket a sign change and need not have straddling endpoints, since they scan the bracket for one; bisection halves the bracket, ridders takes a faster exponential-fit step, brent-dekker interpolates inverse-quadratically with a bisection fallback — the usual library default for a bracketed root — chandrupatla admits that same interpolation under a sharper test, which keeps it at bisection's speed on a repeated root where brent-dekker slows to about a third of it, and secant simply chases the chord through the last two points: the leanest of the five on a simple root, but the slowest on a repeated one), "newton-raphson" or "halley" (single-variable, find-root ONLY as well, but the root engines that bracket NOTHING: they step along the expression's own derivatives — newton along the tangent, x - f(x)/f'(x), halley along a tangent hyperbola that carries the curvature too and so converges cubically for the same work — starting from the best point of a coarse scan of the bracket, with the derivatives taken numerically and every step fenced back into [lower, upper]. Fastest of all on a smooth root, and the only engines that reach a root which merely TOUCHES zero without crossing, where the sign-change engines report "no sign change"), or one of the three MULTIVARIATE engines — "nelder-mead" (a bounds-clamped downhill simplex), "powell" (derivative-free too: each iteration sweeps a full bounded line minimisation along every one of n directions, and re-aims that direction set at the sweep's own net displacement, so it follows a diagonal valley the simplex can only feel out — usually the fewest evaluations of the three on a smooth objective) or "bfgs" (quasi-Newton gradient descent, find-minimum / find-maximum only). The single-variable engines solve only the SINGLE form; the variables form requires a multivariate one. (golden, brent, bisect, ridder, brent-root, newton, simplex, powells and a few other spellings are accepted too — note bare brent names the PARABOLIC MINIMISER, while Brent's root method is brent-dekker.)

mode and min_fixed_point_precision behave as in calculate — the search runs in that numeric type and the found value is reported in it — with ONE solver-only rule: in fixed-point mode (the default) a search at scale 0 would floor the variable to whole numbers and miss any non-integer solution, so when min_fixed_point_precision is omitted it DEFAULTS to 9 (sub-unit resolution) rather than 0. Pass an explicit value for more/fewer decimals, or 0 to search integers only; the other modes (floating-point / rational) resolve sub-unit values natively and take no floor. See calculate and help for the shared grammar and modes; if a found value or objective looks off, analyze shows the per-node parse tree of the expression (with the unknowns substituted) to reveal where it rounded or overflowed.

The search is bounded by a hard 2-second time limit. If it has not converged by then it stops and reports the best value reached so far (a find-root that has not got close enough to zero in that time is reported as no-solution, naming the limit).

Returns a dict: solutions is a list of {variable, solution, solution_hex_dump}, one per unknown in input order — each solution rendered and marked "(approximate)" (the search locates it to a tolerance, never exactly), with its bit-backed hex. For the SINGLE form the scalar variable / solution / solution_hex_dump are also set (the one unknown); for the MULTIPLE form those scalars are null and solutions carries every value. value is the EXPRESSION evaluated at that solution, annotated with its own precision verdict (near zero for find-root, the extremum otherwise), and value_hex_dump its hex. mode is the resolved numeric type; exact and precision describe value exactly as in calculate. objective echoes the resolved objective, algorithm names the engine used, and iterations is how many search steps it took. On any failure — a bad mode/precision, a malformed expression, an invalid request (no/both input forms, empty bracket, unknown not in the expression, golden-section asked for multiple unknowns, unknown objective or algorithm), or no solution in the bracket — every data field is null and error carries the message (a no-solution error reports the closest |expr| it reached); on success error is null.