UNCONSTRAINED OPTIMIZATION -- REVIEWED TEACHING EDITION
====================================================

START HERE
1. Extract this ZIP into a NEW folder. Keep all .m files together.
2. Set that folder as MATLAB's Current Folder.
3. Run verify_course_examples for known-solution and edge-case checks.
4. Run gradient_descent_test or theory_examples to inspect the graphics.
5. Run run_all_examples('core',true) for a paced teaching sequence.
6. Optional: export_course_figures exports all open figures to PNG and PDF.

MATLAB REQUIREMENTS
Target: MATLAB R2020a or newer (tiledlayout and exportgraphics).
Only fsolve_test and fminunc_test require Optimization Toolbox; they check
both installation and licensing. The core sequence uses base MATLAB.
No Symbolic Math Toolbox is required. Keep the shared helpers beside the demos.

REVIEW AND VALIDATION
README_REVIEW.md explains each substantive change and covers every original
file. REFERENCE_CHECK_RESULTS.txt records independently calculated numerical
results. SYNTAX_CHECK_RESULTS.txt records the MATLAB static parser result.
MATLAB/Octave was unavailable during this review: the .m files have NOT been
executed in MATLAB and their native graphics have NOT been rendered here.
The two PNGs in reference_previews are explicitly labeled Python reference
illustrations, not MATLAB screenshots. Run the numerical check and the core
visual demos once in your MATLAB installation before teaching.

RECOMMENDED CORE ORDER
- theory_examples: stationarity, local/global distinction, Hessian geometry.
- exercise2_stationary_points: solve and classify the examples.
- exercise1_cobb_douglas: an economic application with input-domain discussion.
- bisec_visual_demo: brief root-finding prerequisite, if needed.
- newton_visual_demo: linearization as a root-finding method.
- newtonraph_test: apply Newton to the gradient; maximum versus minimum.
- gradient_descent_test: contours, descent direction, line search, convergence.
- optimization_comparison: quadratic first, Rosenbrock second; introduce BFGS
  and Nelder-Mead only to the level appropriate for the class.

The driver defaults to this core sequence, pausing after each script.
run_all_examples('all',false) runs the extended collection without pauses.
Scripts may clear the base workspace and console, but no demo closes other
figures. Close figures manually when desired; automatic export is opt-in.

OPTIONAL / APPENDIX MATERIAL
- fixpoint_test / fixpoint_visual_demo: attraction versus repulsion.
- secant_test / secant_visual_demo: derivative-free root updates.
- broyden_test, broyden, inverse_broyden: multivariate root-finding extensions.
- bracket_test / bracket_visual_demo / fminbnd_test: bounded 1D maximization.
- fzero_test / fsolve_test: built-in root solvers.
- bfgs_test: explicit BFGS update and Rosenbrock contour path.
- fminsearch_test / fminunc_test: built-in minimizers; fminunc is advanced.
- root_finding_comparison: residual histories, with costs and tolerances caveat.

TEACHING DISTINCTIONS
Root-finding solves f(x)=0; optimization solves an extremum problem. Solving
its FOCs is a bridge between them, not a guarantee of a maximum/minimum.
Cobb-Douglas inputs lie in the positive orthant; exp(z) enforces that domain.
fminbnd and bracket restrict the search to an interval; the cubic used there
is unbounded above on R, so the computed peak is not a global maximum on R.
A small gradient does not certify a minimum for a general nonconvex objective.
The cubic stationary-point exercise has a LOCAL minimum at (3,-3), not a
global minimum. The entropy and negative-definite quadratic examples do have
unique global maxima on their respective domains.

OUTPUT CONVENTIONS
Existing positional inputs and outputs are retained; optional histories were
added to bisec, bracket, newton, secant and newtonraph.
GD/BFGS histories now include x, f, gradient norm, step sizes, function and
gradient evaluation counts, and a reason string.
GD/BFGS/Newton counts are accepted updates; initial convergence takes zero.
Flags 1/0 in custom solvers mean tolerance met / not met. For bisection, the
criterion can be bracket width OR residual; continuity is assumed.
MATLAB built-in exit flags retain MATLAB's meanings. A positive fminsearch
flag is not equivalent to meeting the custom solvers' gradient tolerance.
For log plots, values below 1e-16 are displayed at 1e-16; this is a display
floor only and is not a convergence tolerance.

COMPARISON LIMITS
Iteration counts are not evaluation counts or runtime comparisons. GD/BFGS
counts include line-search function trials. Nelder-Mead gradients are computed
only after the solve for diagnostics, not supplied to its algorithm.
The comparison deliberately caps GD at 2000 updates on Rosenbrock; a budget
limit is reported honestly. Do not describe that capped run as converged.
The implementations are transparent teaching solvers, not production tools:
Newton/Broyden are undamped local methods; Armijo is not a Wolfe line search;
BFGS skips unsuitable curvature updates. No general convergence guarantee is
claimed for arbitrary objectives or starting points.

Shared helper files
course_figure.m, course_style.m, course_fminsearch.m, root_step_figure.m,
theory_visual_demo.m, export_course_figures.m.
