Cycles_tutorial.ipynb exists but is not findable from docs.econ-ark.org

[Haruki-Shibuya]

Describe the bug
When you search for Cycles_tutorial in docs.econ-ark.org, it is not found.

To Reproduce
Steps to reproduce the behavior:

1. Go to 'docs.econ-ark.org'
2. Click on either 'Overview and Example' or 'API Reference'
3. Search using any method to find 'Cycles_tutorial'
4. See that there is no match

Expected behavior
Somehow this documentation should be easy to find because the usage of cycles, T_cycle, T_sim, and sim_periods are hard to undrstand.

[DominicWC]

I'm in favor of adding it. What do you think Matt? It's definitely a little rough around the edges but we don't have any documentation about cycles currently, and something rough is probably better than nothing.

[mnwhite]

I really thought it was somewhere. This is one of the topics that would be in the "A Little Rough Introduction to HARK" that we discussed. Maybe I should write that soon.

…

On Fri, Aug 16, 2024, 9:53 PM DominicWC ***@***.***> wrote: I'm in favor of adding it. What do you think Matt? It's definitely a little rough around the edges but we don't have any documentation about cycles currently, and something rough is probably better than nothing. — Reply to this email directly, view it on GitHub <#1485 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADKRAFPAMA5MZXNEMCJW4I3ZR2ULFAVCNFSM6AAAAABMUXUL36VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDEOJUGUZDSMRZGE> . You are receiving this because you were assigned.Message ID: ***@***.***>

[DominicWC]

I've added it to PR#1470

[Haruki-Shibuya]

@DominicWC
Thank you!
Could you let me know whenever Cycles_tutorial is merged so that I can check the documentation?

[DominicWC]

You should be able to check it right now. It isn't on the website, but the notebook is in the HARK/examples/LifecycleModel folder. When the notebook gets added to the HARK documentation, it's going to look essentially the same. I plan on making a few edits to make its material more comprehensive, but it won't be anything too significant.

[Haruki-Shibuya]

Hi Dominic, it doesn't seem that the documentation has been merged yet. Could you provide me with an update if any?
I guess we are waiting for @mnwhite to review and merge as he is most knowledgeable about these things.

[mnwhite]

I thought I had merged everything from Dominic, but this might have been missed. I'm at the NumFocus conference right now, but will get back tomorrow.

…

On Fri, Sep 6, 2024, 6:05 PM Haruki Shibuya ***@***.***> wrote: Hi Dominic, it doesn't seem that the documentation has been merged yet. Could you provide me with an update if any? I guess we are waiting for @mnwhite <https://github.com/mnwhite> to review and merge as he is most knowledgeable abou these things. — Reply to this email directly, view it on GitHub <#1485 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADKRAFKSAKPOSQVRYC42PFTZVIRMHAVCNFSM6AAAAABMUXUL36VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDGMZUHA3TAMZUGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[DominicWC]

@Haruki-Shibuya cycles_tutorial has been merged and is currently on the website. The notebooks in the documentation are titled based on the title used in the Jupyter Notebook. The page you should look for is called "A number of Life-Cycle Examples in HARK".

[Haruki-Shibuya]

Thank you so much!

[Haruki-Shibuya]

If you have time I hope you could add a brief, explicit explanation on the difference among T_cycle, T_sim, sim_periods, and t_cycle since these were the thing I struggled to understand. I could do this based on my rough understanding but this can be too inaccurate. Perhaps Matthew knows the most about them?

[DominicWC]

@Haruki-Shibuya
Matts working on making a more in-depth tutorial, but since that will take a while:
For Hark models, if you want to make them time-varying, then you have to specify what the parameters are for each time-varying parameter, and then choose a number of times you want that to repeat.

As an example, if you're simulating a consumer who does seasonal work for 20 years, you might define the parameters for each of the 4 seasons, and then run that for 20 cycles.

T_cycle is the number of periods in each cycle. In the example above, T_cycle would be 4, because there are four distinct periods/sets of parameters. If you wanted different parameters for each month then T_cycle would be 12. If you want to fully specify their lifetime then T_cycle is just the number of periods that you've specified parameters for. An easy rule of thumb is that T_cycle should be the same as the length of any time-varying lists you've specified.

cycles is the number of cycles you want to simulate. In the above example, this would be 20. If we set it to 0, then it does an infinite lifecycle where the model keeps running cycles until the solution stops changing. If we're specifying a full lifecycle we should set it to one, because we only want them living their life once.

T_sim is the number of periods that get simulated during the simulation step. Technically this can be whatever you want it to be, but the results can start getting very tricky to interperate if you use weird numbers. The way HARK simulates is that it agents have a probability of death, and every time an agent dies, they are replaced by a randomly drawn child. Typically T_sim should be cycles*T_cycle+1 or less, unless it's an infinite horizon model in which case it can be whatever you want.

sim_periods is an optional parameter that you can give HARK's simulate function which essentially overrides T_sim. I'm not sure what you're doing so it might be useful for you, but most users can just ignore it. Matt would probably have more to say about it.

As far as I know, t_cycle (lowercase) isn't a thing. It might be a typo from us in the documentation, so If you can find any examples of us using it that would be super helpful.

I hope that's helpful