OccBin V2.0 — Directory Contents
==================================
Guerrieri and Iacoviello (2015), "OccBin: A toolkit for solving dynamic
models with occasionally binding constraints easily", Journal of Monetary
Economics 70, 22-38.

Tested on: Dynare 6.5 and Dynare 7.0, MATLAB R2026a, macOS ARM64.


ROOT DIRECTORY
--------------
readme.tex / readme.pdf
    User manual.  Describes the toolkit API, input/output conventions,
    and the four included model examples.

setpathdynare6_5.m
    Sets the MATLAB path for Dynare 6.5 and the toolkit.  Run this from
    the root directory before using any model example with Dynare 6.5.

setpathdynare7.m
    Sets the MATLAB path for Dynare 7.0 and the toolkit.  Run this from
    the root directory before using any model example with Dynare 7.0.

dynare_manual_excerpt.txt
    Excerpt from the Dynare 7.0 manual describing the built-in OccBin
    solver (occbin_constraints block, occbin_setup, occbin_solver).
    Relevant to model_irrcap_dynoccbin.

dynare6_migration_notes.md
    Developer notes documenting changes required when migrating from
    Dynare 4 to Dynare 6, and from Dynare 6 to Dynare 7.  Covers
    steadystate file signature changes, cell-array variable names,
    the ZEROP parameter fix, and the get_deriv dispatcher pattern.

run_cleanup.m
    Scans all model_* subdirectories and deletes files added by Dynare at
    runtime (driver scripts, log files, _dynamic/_static/_results files,
    +modelname/ package directories, modelname/ compiled directories).
    Accepts an optional dry-run argument: call_cleanup(true) lists what
    would be deleted without actually deleting anything.

run_all_tests.m
    Automated test runner.  Runs every runsim_*.m in every model_*
    subdirectory and reports PASS/FAIL for each.  Works with both Dynare
    6.5 and 7.0 (9/9 pass on each).  Usage: setpathdynare7 (or
    setpathdynare6_5), then run_all_tests.  Uses function-scope isolation
    so that runsim scripts that call 'clear' cannot corrupt the test loop.

notes_for_luca.txt
    Research notes on possible extensions (Dynare built-in Jacobians,
    higher constraint count, second-order perturbation, uncertainty).


TOOLKIT_FILES/
--------------
Core MATLAB functions used by all model examples.  Add this directory to
the MATLAB path via setpathdynare6_5.m or setpathdynare7.m.

--- Solvers (one constraint) ---
solve_one_constraint.m
    Main entry point for models with one occasionally binding constraint.
    Calls dynare on the reference and alternative .mod files, runs the
    OccBin piecewise-linear algorithm, returns linear and piecewise paths.

solve_one_constraint_no_parse.m
    Variant of solve_one_constraint that skips constraint string parsing;
    the caller must pass pre-parsed constraint expressions directly.

solve_one_constraint_no_parse_short.m
    Compact variant returning only the nshocks x nvars piecewise matrix
    (one row per shock period) rather than the full nperiods x nvars path.

solve_no_constraint.m
    Solves the model ignoring the constraint (pure linear solution).

solve_no_constraint_no_parse.m
    No-parse variant of solve_no_constraint.

--- Solvers (two constraints) ---
solve_two_constraints.m
    Entry point for models with two occasionally binding constraints.
    Returns linear and piecewise paths (5 outputs).

solve_two_constraints_add_violvecbool.m
    Extended two-constraint solver that also returns the constraint
    violation boolean from the last shock period (17 outputs).

solve_two_constraints_add_violvecbool_no_parse.m
    No-parse variant of solve_two_constraints_add_violvecbool.

--- OccBin algorithm internals ---
get_deriv.m
    Dispatcher: detects Dynare version via dynare_version() and calls
    get_deriv_d6 or get_deriv_d7 accordingly.

get_deriv_d6.m
    Evaluates Dynare 6 dynamic equations at steady state and returns
    Jacobian matrices hm1, h, hl1 (lags, current, leads) and residual.
    Uses compact y vector and eval fname.dynamic().

get_deriv_d7.m
    Dynare 7 counterpart of get_deriv_d6.  Uses the full 3*nvars y vector
    and the split dynamic_resid / dynamic_g1 (sparse) functions.

get_pq.m
    Reorders Dynare's decision rule matrices (ghx, ghu) from Dynare's
    internal variable ordering to .mod file definition order, returning
    the state transition matrix p and shock impact matrix q.

map_regime.m
    Converts a boolean constraint-violation vector into the regime
    sequence and regime-start index vectors used by mkdatap_anticipated.

mkdatap_anticipated.m
    Core OccBin backward recursion for one constraint.  Computes the
    time-varying P(t) and D(t) matrices and assembles the piecewise path.

mkdatap_anticipated_2constraints.m
    Two-constraint extension of mkdatap_anticipated.

mkdata.m
    Computes the unconstrained (linear) solution path given a shock
    sequence, using the reference-regime decision rules.

process_constraint.m
    Parses a constraint string (e.g. 'i<log(PHII)') and appends a
    variable-name suffix (e.g. '_difference') to each endogenous variable
    name, returning an expression suitable for eval.

tokenize.m
    Lexer used by process_constraint to split constraint strings into
    tokens (variable names, operators, constants).

--- Utilities ---
setss.m
    Script that assigns steady-state values to workspace variables with
    a '_ss' suffix, used for constraint evaluation.

edit_shocks_this_file.m
    Template / placeholder for custom shock sequences.

makechart.m
    Plots piecewise vs. linear IRFs for up to 5 variables (one figure,
    up to 5 panels).

makechart9.m
    Extended version of makechart supporting up to 9 panels.

pickaxes.m
    Helper used by makechart / makechart9 to select and format axes.

strmerge.m
    String utility: merges a cell array of strings with a delimiter.

--- Second-order / nonlinear extensions ---
solve_secondorder.m
    Experimental solver that computes a second-order perturbation solution
    for models with occasionally binding constraints.

solve_nonlinear.m
    Experimental nonlinear (perfect foresight) solver for OBC models.

makeirfsecondorder.m
    Plots IRFs from the second-order solution.

mymkirf2.m
    Helper for computing and storing second-order IRFs.

mkirf_nonlinear.m
    Computes IRFs using the nonlinear solver.

perfect_foresight_solver_first_guess.m
    Provides a first guess for the perfect foresight solver based on the
    piecewise-linear solution.


MODEL EXAMPLES
--------------
Each model directory contains:
  - One or more Dynare .mod files (reference regime + alternative regimes)
  - A parameter file (paramfile_*.m) loaded by the steadystate file
  - An optional external steadystate file (*_steadystate.m)
  - A runsim_*.m script that sets up shocks and calls the solver
  - Dynare-generated files (.m, _dynamic.m, _static.m, _results.mat, etc.)
  - Dynare 7 generated package directories (+modelname/)

model_irrcap/
    RBC model with irreversible investment (one constraint).
    Constraint: investment cannot fall below a fraction PHII of its
    steady-state level.
    .mod files: dynrbc.mod (reference), dynrbcirr_i.mod (binding regime).
    Entry point: runsim_irrcap.m

model_irrcap_dynoccbin/
    Same irreversible-investment RBC model, reimplemented using Dynare 7's
    built-in OccBin solver instead of the standalone toolkit.  A single
    .mod file (dynrbc_occbin.mod) replaces the two-file approach, using
    occbin_constraints and equation tags.  Outputs match model_irrcap to
    machine precision after converting Dynare's level outputs to deviations
    from steady state.
    Entry point: runsim_irrcap_dynoccbin.m
    Documentation: dynare7_occbin_explainer.tex — explains how Dynare 7
    captures alternative-regime Jacobians via equation tags, and compares
    the two approaches side by side.

model_irrcap_twoconstraints/
    RBC model with two simultaneously active occasionally binding
    constraints: irreversible investment (IRR) and a no-negative-investment
    constraint (INEG).
    .mod files: dynrbc.mod (00), dynrbcirr.mod (10), dynrbcineg.mod (01),
    dynrbcirrineg.mod (11) — one per regime combination.
    Entry points: runsim_irrcap_two_constraints.m,
                  runsim_irrcap_two_constraints_computepolicy.m

model_borrcon/
    Small open economy model with a borrowing constraint (one constraint).
    .mod files: borrconnotbinding.mod (reference), borrcon.mod (binding).
    Entry point: runsim_borrcon.m

model_dnk/
    Dynamic New Keynesian model with a zero lower bound on nominal
    interest rates (one constraint).
    .mod files: dnk.mod (reference), dnk_zlb.mod (ZLB binding).
    Entry point: runsim_dnk.m
    Also contains: Equations.tex / Equations.pdf (model documentation).

model_cgg/
    Clarida-Gali-Gertler (1999) model with a zero lower bound
    (one constraint).
    .mod files: cgg.mod (reference), cgg_zlb.mod (ZLB binding).
    Entry point: runsim_cgg.m
    Note: the discount factor is named BETAP (not BETA) in the .mod files
    and runsim to avoid collision with MATLAB's built-in beta() function.

model_newkeynesian/
    Fuhrer-Violante New Keynesian model with a zero lower bound
    (one constraint).
    .mod files: fv.mod (reference), fv_zlb.mod (ZLB binding).
    Entry point: runsim_newkeynesian.m

model_smetswouters/
    Smets-Wouters (2007) US model with a zero lower bound (one constraint).
    .mod files: usmodel.mod (reference), usmodelzlb.mod (ZLB binding).
    Entry point: runsim_smetswouters.m


QUICK START
-----------
1. From the root directory, run setpathdynare7 (or setpathdynare6_5).
2. Change into a model directory (e.g. cd model_irrcap).
3. Run the entry-point script (e.g. runsim_irrcap).

To use Dynare's built-in OccBin instead of the standalone toolkit:
1. Run setpathdynare7 from the root directory.
2. cd model_irrcap_dynoccbin
3. Run runsim_irrcap_dynoccbin.
