.. steppyngstounes documentation master file, created by sphinx-quickstart on Wed Dec 16 13:58:55 2020. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. .. title:: steppyngstounes **steppyngstounes** / ˈstɛp ɪŋˌstoʊnz / 1. *pl. n.* *[Middle English]* Stones used as steps of a stairway; also, stones in a stream used for crossing. [#]_ *...while at Calais in 1474 we find 40 'steppyngstounes' bought for the stairways of the town.* [#]_ 2. *n.* *[chiefly Pythonic]* A package that provides iterators for advancing from `start` to `stop`, subject to algorithms that depend on user-defined `value` or `error`. |Testing| |Documentation| |Linting| |GitHub| |Codacy| Computations that evolve in time or sweep a variable often boil down to a control loop like .. code-block:: python for step in range(steps): do_something(step) or .. code-block:: python t = 0 while t < totaltime: t += dt do_something(dt) which works well enough, until the size of the steps needs to change. This can be to save or plot results at some fixed points, or because the computation becomes either harder or easier to perform. The control loop then starts to dominate the script, obscuring the interesting parts of the computation, particularly as different edge cases are accounted for. Packages like `odeint`_ address many of these issues, but do so through callback functions, which effectively turn the computation of interest inside out, again obscuring the interesting bits. Further, because they are often tailored for applications like solving ordinary differential equations, applying them to other stepping problems, even `solving partial differential equations`_, can be rather opaque. The steppyngstounes package is designed to retain the simplicity of the original control loop, while allowing great flexibility in how steps are taken and automating all of the aspects of increasing and decreasing the step size. A steppyngstounes control loop can be as simple as .. code-block:: python from steppyngstounes import FixedStepper for step in FixedStepper(start=0., stop=totaltime, size=dt): do_something(step.size) _ = step.succeeded() which replicates the :strong:`while` construct above, but further ensures that ``totaltime`` is not overshot if it isn't evenly divisible by ``dt``. .. attention:: The call to :meth:`~steppyngstounes.stepper.Step.succeeded` informs the :class:`~steppyngstounes.stepper.Stepper` to advance, otherwise it will iterate on the same step indefinitely. Rather than manually incrementing the control variable (e.g., ``t``), the values of the control variable before and after the step are available as the :class:`~steppyngstounes.stepper.Step` attributes :attr:`~steppyngstounes.stepper.Step.begin` and :attr:`~steppyngstounes.stepper.Step.end`. The attribute :attr:`~steppyngstounes.stepper.Step.size` is a shorthand for ``step.end - step.begin``. If the size of the steps should be adjusted by some characteristic of the calculation, such as the change in the value since the last solution, the error (normalized to 1) can be passed to :meth:`~steppyngstounes.stepper.Step.succeeded`, causing the :class:`~steppyngstounes.stepper.Stepper` to advance (possibly adjusting the next step size) or to retry the step with a smaller step size. .. code-block:: python from steppyngstounes import SomeStepper old = initial_condition for step in SomeStepper(start=0., stop=totaltime, size=dt): new = do_something_else(step.begin, step.end, step.size) err = (new - old) / scale if step.succeeded(error=err): old = new # do happy things else: # do sad things A hierarchy of :class:`~steppyngstounes.stepper.Stepper` iterations enables saving or plotting results at fixed, possibly irregular, points, while allowing an adaptive :class:`~steppyngstounes.stepper.Stepper` to find the most efficient path between those checkpoints. .. code-block:: python from steppyngstounes import CheckpointStepper, SomeStepper old = initial_condition for checkpoint in CheckpointStepper(start=0., stops=[1e-3, 1, 1e3, 1e6]): for step in SomeStepper(start=checkpoint.begin, stop=checkpoint.end, size=checkpoint.size): new = do_something_else(step.begin, step.end, step.size) err = (new - old) / scale if step.succeeded(error=err): old = new # do happy things else: # do sad things save_or_plot() _ = checkpoint.succeeded() A variety of stepping algorithms are described and demonstrated in the documentation of the individual :mod:`steppyngstounes` classes. ---- .. [#] *Middle English Dictionary*, Ed. Robert E. Lewis, *et al.*, Ann Arbor: University of Michigan Press, 1952-2001. Online edition in *Middle English Compendium*, Ed. Frances McSparran, *et al.*, Ann Arbor: University of Michigan Library, 2000-2018. . Accessed 16 December 2020. .. [#] *Building in England, Down to 1540: A Documentary History*, L. F. Salzman, Clarenden Press, Oxford, 1952. . Accessed 16 December 2020. .. _odeint: https://docs.scipy.org/doc/scipy/reference/generated/scipy.integrate.odeint.html .. _solving partial differential equations: https://www.ctcms.nist.gov/fipy .. |Testing| image:: https://github.com/usnistgov/steppyngstounes/actions/workflows/testing-and-coverage.yml/badge.svg :target: https://github.com/usnistgov/steppyngstounes/actions/workflows/testing-and-coverage.yml .. |Documentation| image:: https://github.com/usnistgov/steppyngstounes/actions/workflows/Docs4NIST.yml/badge.svg :target: https://github.com/usnistgov/steppyngstounes/actions/workflows/Docs4NIST.yml .. |Linting| image:: https://github.com/usnistgov/steppyngstounes/actions/workflows/linting-and-spelling.yml/badge.svg :target: https://github.com/usnistgov/steppyngstounes/actions/workflows/linting-and-spelling.yml .. |Codacy| image:: https://app.codacy.com/project/badge/Grade/d500954988fd495681418c58510b3636 :target: https://app.codacy.com/gh/usnistgov/steppyngstounes/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade .. |GitHub| image:: https://img.shields.io/github/contributors/usnistgov/steppyngstounes.svg :target: https://github.com/usnistgov/steppyngstounes .. toctree:: :hidden: INSTALLATION-proxy SUPPORT API LICENSE-proxy