FAQ#

Use this page for repeated practical questions once the main workflow is already familiar.

Read it after Getting Started or Library Quickstart. If the question is only about exact names or signatures, go to API Reference.

Should I start from the API reference?#

Usually no.

If you are new to the project, start with:

  1. Installation and Environment

  2. Getting Started

  3. BCW2011 Case Study

Then return to API Reference when you need exact names or method signatures.

Why does the documentation focus so much on BCW?#

Because BCW gives you:

  • a fully worked one-dimensional HJB example,

  • endogenous boundary search,

  • interpretable policies,

  • a natural extension from one control to multiple controls.

It is a better teaching path than starting from abstract interfaces alone.

Why must I implement initialize(grid, p) in the policy class?#

Because the solver needs a complete policy container before iteration can begin.

Even if you later choose policy_guess=False, the solver still needs to know:

  • which policy keys exist,

  • what shapes those arrays should have.

When should I use @explicit_policy?#

Use it when the policy update can be written directly and stably in code.

Typical case:

  • you have a closed-form update formula.

When should I use @implicit_policy?#

Use it when the natural mathematical object is a residual or root problem.

Typical case:

  • the policy is defined by a first-order condition that is easier to state as FOC(...) = 0.

Why does policy_guess matter so much?#

Because it changes the starting point of the iteration.

  • good initial guesses can speed convergence,

  • poor initial guesses can slow or distort it.

This is why the BCW examples spend effort constructing reasonable initial policies.

When should I call solve()?#

Call solve() when the boundaries are already fixed and you want the cleanest possible base solve.

This should usually be your first workflow when adapting a new model.

When should I call boundary_update()?#

Call it only when your model implements update_boundary(grid) and the solved grid directly implies a boundary revision.

If your model does not implement that method, boundary_update() correctly raises NotImplementedError.

Why is d2v[-1] so important in the BCW examples?#

Because the payout-side super-contact condition is encoded numerically through the right-tail curvature.

In the BCW scripts, a near-zero d2v[-1] is one of the strongest success signals.

Why can investment be negative at low cash?#

Because financing frictions are severe in distressed states. In the BCW setup, negative low-cash investment is economically meaningful, not automatically a coding bug.

Why is psi between -5 and 0 in the hedging example?#

Because pi = 5 in the benchmark calibration and the code clips the hedge policy to the interval implied by the BCW hedging constraints.

Interpretation:

  • -5 means maximum hedge demand,

  • 0 means no hedge.

How many grid points should I use?#

Start with something moderate and stable, then increase only after the model is behaving sensibly.

The BCW example scripts use number=1000 for high-resolution runs, but the right choice for your workflow depends on:

  • curvature,

  • stiffness,

  • runtime budget,

  • how sharp your policy regions are.

Why not start with sensitivity analysis?#

Because continuation is built on repeated solves. If the base solve is wrong, sensitivity analysis just produces many wrong solves.

Why does grid.aux sometimes fail?#

Because auxiliary(grid) is optional. If your model does not implement it, grid.aux raises NotImplementedError.

What is the safest first custom project?#

Fork the liquidation example and change only:

  1. parameter names and values,

  2. the policy formula,

  3. the HJB residual,

while keeping the class structure and diagnostic workflow intact.

How do I know whether my result is “close enough”?#

Use ranges and qualitative shapes, not exact single numbers.

For BCW, good questions are:

  • is v increasing in s?

  • is dv[-1] near the expected right-boundary slope?

  • is d2v[-1] near zero?

  • do the policies have the expected left-tail and right-tail behavior?