{"action":"created","issue":{"url":"https://api.github.com/repos/landlab/landlab/issues/232","labels_url":"https://api.github.com/repos/landlab/landlab/issues/232/labels{/name}","comments_url":"https://api.github.com/repos/landlab/landlab/issues/232/comments","events_url":"https://api.github.com/repos/landlab/landlab/issues/232/events","html_url":"https://github.com/landlab/landlab/issues/232","id":124147618,"number":232,"title":"Timestep explanation in the docs","user":{"login":"jennyknuth","id":10714699,"avatar_url":"https://avatars.githubusercontent.com/u/10714699?v=3","gravatar_id":"","url":"https://api.github.com/users/jennyknuth","html_url":"https://github.com/jennyknuth","followers_url":"https://api.github.com/users/jennyknuth/followers","following_url":"https://api.github.com/users/jennyknuth/following{/other_user}","gists_url":"https://api.github.com/users/jennyknuth/gists{/gist_id}","starred_url":"https://api.github.com/users/jennyknuth/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jennyknuth/subscriptions","organizations_url":"https://api.github.com/users/jennyknuth/orgs","repos_url":"https://api.github.com/users/jennyknuth/repos","events_url":"https://api.github.com/users/jennyknuth/events{/privacy}","received_events_url":"https://api.github.com/users/jennyknuth/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"gregtucker","id":7528207,"avatar_url":"https://avatars.githubusercontent.com/u/7528207?v=3","gravatar_id":"","url":"https://api.github.com/users/gregtucker","html_url":"https://github.com/gregtucker","followers_url":"https://api.github.com/users/gregtucker/followers","following_url":"https://api.github.com/users/gregtucker/following{/other_user}","gists_url":"https://api.github.com/users/gregtucker/gists{/gist_id}","starred_url":"https://api.github.com/users/gregtucker/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/gregtucker/subscriptions","organizations_url":"https://api.github.com/users/gregtucker/orgs","repos_url":"https://api.github.com/users/gregtucker/repos","events_url":"https://api.github.com/users/gregtucker/events{/privacy}","received_events_url":"https://api.github.com/users/gregtucker/received_events","type":"User","site_admin":false},"milestone":null,"comments":7,"created_at":"2015-12-29T01:11:22Z","updated_at":"2015-12-29T17:12:34Z","closed_at":null,"body":"Somewhere in the docs, I'd like a brief discussion of timesteps and instability. Could be it's own page, but at least its own section. I'd like to link to it from the end of this section: https://github.com/landlab/landlab/wiki/Build-a-Model#5-run-the-model and maybe also from the Components page and from some of the tutorials. Here is some text we had previously on this topic: \r\n```\r\nIf you’ve taken a course in numerical computing, you may remember that an explicit solution to the diffusion equation requires time steps to be small; otherwise, the solution will become unstable (i.e., the numbers will go crazy and be meaningless). The Courant-Friedrichs-Lewy criterion states that the time step size must be smaller than \\Delta x^2 / K_d.\r\n\r\nWith that in mind, we start by setting a value for our diffusion coefficient, ``kd``, and calculating a time-step size that is comfortably smaller than the maximum:\r\n\r\n>>> kd = 0.01   # 0.01 m2 per year\r\n>>> dt = 0.2*mg.dx*mg.dx/kd   # CFL condition\r\n>>> dt\r\n2000.0\r\n```\r\n```\r\nNote that in the model without a component, we calculated a stable *dt* in the model. With the component, the testing of timestep stability happens automatically, and the component will internally subdivide the timestep as necessary. \r\n```\r\n\r\nFirst, figure out a logical place to put this info, then write it to fit that place, then link to it from other areas. \r\n"},"comment":{"url":"https://api.github.com/repos/landlab/landlab/issues/comments/167832787","html_url":"https://github.com/landlab/landlab/issues/232#issuecomment-167832787","issue_url":"https://api.github.com/repos/landlab/landlab/issues/232","id":167832787,"user":{"login":"jennyknuth","id":10714699,"avatar_url":"https://avatars.githubusercontent.com/u/10714699?v=3","gravatar_id":"","url":"https://api.github.com/users/jennyknuth","html_url":"https://github.com/jennyknuth","followers_url":"https://api.github.com/users/jennyknuth/followers","following_url":"https://api.github.com/users/jennyknuth/following{/other_user}","gists_url":"https://api.github.com/users/jennyknuth/gists{/gist_id}","starred_url":"https://api.github.com/users/jennyknuth/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/jennyknuth/subscriptions","organizations_url":"https://api.github.com/users/jennyknuth/orgs","repos_url":"https://api.github.com/users/jennyknuth/repos","events_url":"https://api.github.com/users/jennyknuth/events{/privacy}","received_events_url":"https://api.github.com/users/jennyknuth/received_events","type":"User","site_admin":false},"created_at":"2015-12-29T17:12:34Z","updated_at":"2015-12-29T17:12:34Z","body":"Nice! We now have a page to reference here:\nhttps://github.com/landlab/landlab/wiki/Time-Steps\n\nOn Tue, Dec 29, 2015 at 9:52 AM, Dan Hobley <notifications@github.com>\nwrote:\n\n> Like it\n>\n>\n> > On 29 Dec 2015, at 16:49, Greg Tucker <notifications@github.com> wrote:\n> >\n> > How about something like the following:\n> >\n> > About Components and Time Steps\n> >\n> > Anyone who has taken a numerical computing course knows the importance\n> of time-step size: choose too small a step and your calculation takes\n> forever to run; choose too big a step and it goes unstable. The details\n> depend, of course, on the particular equations and the numerical method\n> used to solve them.\n> >\n> > Landlab Components are responsible for ensuring their own stability.\n> This means, for example, that if your code asks a component to run for ten\n> years, the component needs to make sure ten years isn't too big a step to\n> handle. If it is, the component should subdivide the ten years into smaller\n> steps that are stable and accurate. For example, if the component\n> determines that one year is the biggest step it can get away with, then it\n> should divide the requested ten-year run into ten steps of one year each.\n> If the component uses variable-size time steps, then it should subdivide\n> the ten years as it needs, and return when it has used up exactly ten years.\n> >\n> > Even if each component ensures its own stability, it is still possible\n> for a multi-component model to get into trouble by using \"global\" time\n> steps that are too large. The risk arises because during each global time\n> step, you are effectively de-coupling the components for a small interval\n> of time. For example, suppose you have one component that calculates solar\n> radiation on a landscape and another than calculates the resulting\n> evapotranspiration (ET). When you run the ET component, you assume that the\n> radiation is constant for the duration of the time step---as if the sun's\n> position in the sky became for that period of time. That's probably a\n> reasonable assumption if your time step is 5 minutes long, but obviously\n> problematic if you time step is 12 hours! The moral of the story: test your\n> model with different global time-step sizes to identify a time step that is\n> small enough not to impact the solution in a significant way.\n> >\n> > To learn more about time steps, numerical stability, and solution\n> accuracy, a good source is Numerical Recipes by Press et al. There are also\n> plenty of textbooks on numerical computing available.\n> >\n> > —\n> > Reply to this email directly or view it on GitHub <\n> https://github.com/landlab/landlab/issues/232#issuecomment-167828529>.\n>\n> >\n>\n> —\n> Reply to this email directly or view it on GitHub\n> <https://github.com/landlab/landlab/issues/232#issuecomment-167828955>.\n>\n\n\n\n-- \n\nFull-Stack Web Developer\n303-802-7214\nhttp://jennyknuth.com\nhttps://www.linkedin.com/in/jennyknuth\nhttps://github.com/jennyknuth\n"}}