add BH to docs

docs/tutorial/boehl_hommes.rst

@@ -2,9 +2,9 @@
 Boehl-Hommes method
 -------------------
 
-The package also contains an alternative "shooting" method much aligned to the one introduced in Boehl & Hommes (2021). In the original paper we use this method to solve for chaotic asset price dynamics. The method can be understood as a policy function iteration where the initial state is the only fixed grid point and all other grid points are chosen endogenously (as in a "reverse" EGM) to map the expected trajectory.
+The package also contains an alternative "shooting" method much aligned to the one introduced in Boehl & Hommes (2021). In the original paper we use this method to solve for chaotic asset price dynamics. The method can be understood as an extension to Fair & Taylor (1983) and is similar to a  policy function iteration where the initial state is the only fixed grid point and all other grid points are chosen endogenously (as in a "reverse" EGM) to map the expected trajectory.
 
-The main advantage (in terms of robustness) over the stacking method comes from exploiting the property that most determined perfect foresight models are a contraction mapping both, forward and backwards. The model is given by
+Assume the model is given by
 
 .. code-block::
 
@@ -17,39 +17,9 @@ We iterate on the expected trajectory itself instead of the policy function. We
    d f(x_{t-1}, x_t, x_{t+1} ) < d x_{t-1},
    d f(x_{t-1}, x_t, x_{t+1} ) < d x_{t+1}.
 
-This is also the weakness of the method: not every DSGE model (that is determined in the Blanchard-Kahn sense) is such backward-and-forward contraction. In most cases the algorithm converges anyways, but convergence is not guaranteed.
+This is also the weakness of the method: not every DSGE model (that is determined in the Blanchard-Kahn sense) is such backward-and-forward contraction. Thus, unless you are interested in chaotic dynamics, the standard "stacking" method is to be prefered.
 
-The following example shows how to use the shooting method on the simple New Keynesian model.
-
-.. code-block:: python
-
-    import numpy as np
-    import matplotlib.pyplot as plt
-    import econpizza as ep
-    from econpizza import example_nk
-
-    # load the example.
-    # example_nk is nothing else but the path to the yaml, hence you could also use `filename = 'path_to/model.yaml'`
-    mod = ep.load(example_nk)
-    # solve for the steady state
-    _ = mod.solve_stst()
-
-    # get the steady state as an initial state
-    state = mod['stst'].copy()
-    # increase the discount factor by one percent
-    state['beta'] *= 1.02
-
-    # simulate the model
-    x, _, flag = mod.find_path_shooting(state.values())
-
-    # plotting
-    for i,v in enumerate(mod.var_names):
-
-        plt.figure()
-        plt.plot(x[:,i])
-        plt.title(v)
-
-Lets go for a second, numerically more challenging example: the chaotic rational expectations model of Boehl & Hommes (2021)
+The following example shows how to use the shooting method to a numerically challenging example: the chaotic rational expectations model of Boehl & Hommes (2021). The YAML for this model can be found `here <https://github.com/gboehl/econpizza/blob/master/econpizza/examples/bh.yml>`_.
 
 .. code-block:: python
 
@@ -81,3 +51,8 @@ This will give you boom-bust cycles in asset pricing dynamics:
 .. image:: https://github.com/gboehl/econpizza/blob/master/docs/p_and_n.png?raw=true
   :width: 800
   :alt: Dynamics of prices and fractions
+
+Below, find the documentation for the additional function:
+
+.. autofunction:: econpizza.PizzaModel.find_path_shooting
+