GSEFM PRE-SEMESTER COURSE -- CONSTRAINED OPTIMIZATION MATLAB EXAMPLES
====================================================================

Purpose
-------
This package complements the constrained-optimization slide decks with runnable
MATLAB examples and graphical teaching demos. It is based on the four original
exercise scripts supplied with the course, but adds examples for the theoretical
material so that the main ideas on the slides can also be illustrated numerically.

QUICK START
-----------
1. Put this folder on the MATLAB path / make it the Current Folder.
2. Run the individual scripts while teaching the corresponding topic.
3. Run *_visual_demo.m files for graphical explanations.
4. Run run_all_constrained_examples.m for a full walkthrough.
5. The untouched starting files are kept in the subfolder originals/.

SLIDE-TO-FILE MAP
-----------------
EQUALITY CONSTRAINTS
- Lagrange tangency intuition; parallel gradients
    lagrange_tangency_visual_demo.m
- NDCQ / LICQ and what failure looks like
    ndcq_visual_demo.m
    constraint_qualification_examples.m
- Lagrange exercise: max 2x-2y+z on a sphere
    equality_exercise1_lagrange.m
- Utility maximization with a budget equality
    utility_maximization_example.m
- Labour-supply Cobb-Douglas example
    labour_supply_example.m
- Bordered-Hessian construction and sign checks
    bordered_hessian_demo.m

INEQUALITY CONSTRAINTS
- KKT conditions, active/slack constraints and complementary slackness
    kkt_inequality_exercise.m
- Example with two local/global maxima and non-uniqueness
    inequality_nonunique_example.m
- The KKT exercise explicitly works through all four active-set possibilities.

MIXED CONSTRAINTS
- Circle equality plus non-negativity inequalities
    exercise1.m
    mixed_constraints_visual_demo.m
- Economic application: production cap, individual capacities and shadow prices
    exercise2.m
    economic_application_visual_demo.m

NUMERICAL METHODS
- fmincon, nonlinear equality + inequalities
    exercise1.m
- fmincon, linear inequality constraints
    exercise2.m
- Quadratic penalty method
    exercise3.m
    penalty_equality_method.m
- Lagrange-Newton / direct solution of equality KKT system
    exercise4.m
    lagrange_newton.m
- Fischer-Burmeister NCP function for inequality complementarity
    ncp_fischer_burmeister_demo.m
- SQP and the sequence of iterates generated by fmincon
    sqp_visual_demo.m
- Linear, quadratic, and linearly constrained nonlinear special cases
    special_cases_linear_quadratic.m
- Penalty vs. Lagrange-Newton vs. fmincon on the same problem
    method_comparison.m
- Generic fmincon input template / reminder
    fmincon_template.m

WHAT WAS CHANGED RELATIVE TO THE ORIGINAL FOUR FILES?
------------------------------------------------------
exercise1.m
- Preserves the course problem max x-y^2 subject to x^2+y^2=4 and x,y>=0.
- Uses correctly shaped fmincon inputs and a sensible feasible starting point.
- Reports slacks/multipliers and produces a contour plot with the feasible arc.

exercise2.m
- Preserves the firm's profit-maximization problem.
- Uses a feasible start and reports which constraints bind and their shadow prices.
- Adds a plot of the feasible polygon, profit contours, and optimum.

exercise3.m
- Keeps the penalty-method logic from the original code but puts it into a reusable
  helper, stores the whole outer-iteration history, and plots convergence of the
  constraint residual and penalty parameter.
- Uses fminunc when Optimization Toolbox is available and falls back to fminsearch.

exercise4.m
- The original file passed the KKT equations to fsolve. The adapted version makes
  the Lagrange-Newton logic explicit by implementing the Newton step for the KKT
  system, including the KKT Jacobian, and plots residual convergence.
- It also optionally checks the result with fsolve if available.

VISUAL TEACHING DEMOS
---------------------
lagrange_tangency_visual_demo.m
    Constraint line + objective level sets + gradients at the tangency point.

ndcq_visual_demo.m
    Side-by-side full-rank and degenerate constraint examples.

kkt_inequality_exercise.m
    Feasible region, active constraint, objective contours, and KKT case table.

mixed_constraints_visual_demo.m
    Feasible quarter-circle, optimum, and constraint-gradient geometry. It also
    highlights the useful subtlety that a constraint may bind with multiplier zero.

economic_application_visual_demo.m
    Quantity-cap solution and the equivalent EUR 12 unit-tax solution.

ncp_fischer_burmeister_demo.m
    Surface/zero-set intuition for the Fischer-Burmeister NCP function and a small
    KKT system written with complementarity equations.

sqp_visual_demo.m
    Records fmincon SQP iterates and plots how they move toward the constrained
    solution.

TOOLBOX NOTES
-------------
- fmincon, fminunc, fsolve, linprog, and quadprog belong to Optimization Toolbox.
- The scripts check for the relevant routines where practical and either skip the
  toolbox-specific portion or use a simple fallback.
- The custom Lagrange-Newton routine and the theory/visual scripts use base MATLAB.

TEACHING NOTE ON MAXIMIZATION
-----------------------------
MATLAB routines such as fmincon minimize by default. Hence a maximization problem
max f(x) is supplied to MATLAB as min -f(x). The examples label this explicitly.

SOURCE CONSISTENCY NOTES
------------------------
Two small inconsistencies are worth flagging for teaching:
1. Coding Exercises 3/4 print the hinted solution as approximately
   (3.512, 0.127, 3.552) on the slide. With the equality constraint
   8*x1+14*x2+7*x3=56 used both on the slide and in the supplied MATLAB codes,
   x2=0.127 does not satisfy the constraint. Solving the supplied system gives
   approximately (3.51212, 0.21699, 3.55217). The package follows the equations
   and original code, not the inconsistent numerical hint.
2. The economic-application prose refers to individual capacity below 28 units,
   while the displayed optimization problem and supplied exercise2.m use
   x1<=27 and x2<=27. The package follows the displayed equations/code (27).
