adding necessary functions to time_iteration docstring

[sbenthall]

Adding a mention of transition and arbitrage to parameter docs.

Is this kind of change welcome?

[sbenthall]

It appears that an arbitrage equation has the signature:

m, s, x, M, S, X, p -> r1, r2

What are r1 and r2?

[albop]

Adding a mention of transition and arbitrage to parameter docs.

Is this kind of change welcome?

Yes this is very helpful. When the doc is stable we could link to the algorithm mathematical description

[albop]

It appears that an arbitrage equation has the signature:

m, s, x, M, S, X, p -> r1, r2

What are r1 and r2?

I'm a bit surprised. In the core definition, the result is r with the same size as x. As a standard function you can call it directly, r = arbitrage(...) or r, r_m, r_s, r_x, r_M, r_S, r_X=arbitrage(..., diff=True) in which case you get the derivative w.r.t. to all variables except the last. One way to gather all derivatives together is r, *r_=arbitrage(..., diff=True). Is this what you saw ?

[albop]

Ah, I just saw where the confusion might come from. In the self contained example, you get something like:

@jit(nopython=True)
def arbitrage_(m, s, x, M, S, X, p):

    res_1 = χ*n**η*c**σ - w                    
    res_2 = 1 - β*(c/C)**(σ)*(1-δ+R) 

    return (res_1, res_2)

In this example, (res_1, res_2) represents one vector of size 2, same as vector x, which can also be seen as a tuple of two elements. The reason, I use tuples for the vectors in the jitted functions is because the compiler knows their size and can optimize them away (contrary to numpy arrays).

[sbenthall]

In this PR, I've added something to this page that briefly overviews the necessary functions for each of the solution algorithms: https://dolo.readthedocs.io/en/latest/algos.html

I see now where these equations are defined, here: https://dolo.readthedocs.io/en/latest/algos.html

Perhaps I was being dense not finding them earlier. But I will put some thought into how to create a "dictionary" or "cheat sheet" to make it easier to look up the definition of one of the technical terms that appears in the model language.

I expect doing this correctly will involve clean use of the markup language to manage internal links within the documentation. I also understand that the documentation is currently in flux? Maybe I can revisit this once the MakeTheDocs are more complete.

[albop]

Thanks. Tell me when you want to merge this PR. As for the mkdocs, I expect to complete the transition by the end of next week (and get rid of all concurrent versions of the docs). I just need to figure out how to autodocument python functions.