diff --git a/docs/notebooks/tutorial.ipynb b/docs/notebooks/tutorial.ipynb index e64f6f4..23a5b2c 100644 --- a/docs/notebooks/tutorial.ipynb +++ b/docs/notebooks/tutorial.ipynb @@ -9,14 +9,14 @@ "This notebook aims to present an illustrative example explaining the usage of *checkpoint_schedules* for step-based incremental checkpointing of the adjoints to computer models. While it is an illustrative example, this code can be also employed for real applications.\n", "\n", "## Managing the forward and adjoint executions with schedules\n", - "Fistly, we initially write the `CheckpointingManager` class intending to manage the execution of forward and adjoint models using a checkpointing schedule. The `CheckpointingManager` constructor takes the maximum steps numbers for the models' execution, `max_n`. The `index_action` is a counter of the actions executed, and the `list_actions` is a list of the actions executed. The attributes `index_action` and `list_actions` are here used only for illustration matter.\n", + "We first write the `CheckpointingManager` class intending to manage the execution of forward and adjoint models using a checkpointing schedule. The `CheckpointingManager` constructor takes the maximum number of steps in the model's execution, `max_n`. `index_action` is a counter of the actions executed, and `list_actions` is a list of the actions executed. The attributes `index_action` and `list_actions` are here used only for illustration.\n", "\n", - "In `CheckpointingManager`, we have the method `execute` able to make the step executions of the forward and adjoint models. `execute` takes the `cp_schedule` argument, which expects to be a generator provided by the *checkpoint_schedules* package. In the `execute` method, we iterate over the elements of the `cp_schedule` using `enumerate(cp_schedule)`, which yields a tuple `(count, cp_action)`. Here, `count` represents the index of the action within the list, and `cp_action` is a checkpoint action provided by *checkpoint_schedules*.\n", + "The `CheckpointingManager` has the method `execute` which runs the schedule. `execute` takes the `cp_schedule` argument, which expects to be a generator provided by the *checkpoint_schedules* package. In the `execute` method, we iterate over the elements of the `cp_schedule` using `enumerate(cp_schedule)`, which yields a tuple `(count, cp_action)`. Here, `count` represents the index of the action within the schedule, and `cp_action` is a checkpoint action provided by *checkpoint_schedules*.\n", "\n", - "`cp_action` is the argument to a single-dispatch generic function named `action`. The purpose of this function is to process different types of checkpoint actions using specific function. The overloading of the `action` function is given by its `register()` attribute employed as a decorator in the specific functions, e.g., we have the `@action.register(Forward)` decorator for the `action_forward` function. Thus, `action` is overloaded by `action_forward` if `cp_action` is the `Forward` action. Inside the `action_forward`, we can implement the necessary code to the step execution of the forward model. \n", + "`cp_action` is the argument to a single-dispatch generic function named `action`. The purpose of this function is to process different types of checkpoint actions using a specific function. The overloading of the `action` function is given by its `register()` attribute employed as a decorator in the specific functions, e.g., we have the `@action.register(Forward)` decorator for the `action_forward` function. Thus, `action` is overloaded by `action_forward` if `cp_action` is the `Forward` action. Inside `action_forward`, we can implement the necessary code to step the forward model. \n", "\n", "**Notes:**\n", - "* The `action.register` decorator takes *checkpoint_schedules* actions as the arguments. These actions will be presented with more detail in the following sections of this tutorial.\n" + "* The `action.register` decorator takes *checkpoint_schedules* actions as the arguments. These actions will be presented in more detail in the following sections of this tutorial.\n" ] }, { @@ -28,17 +28,18 @@ "from checkpoint_schedules import *\n", "import functools\n", "\n", + "\n", "class CheckpointingManager():\n", " \"\"\"Manage the executions of the forward and adjoint solvers.\n", "\n", " Attributes\n", " ----------\n", " max_n : int\n", - " Total steps used to execute the solvers.\n", + " Total number of steps.\n", " list_actions : list\n", - " Store the actions. Only used for the illustration matter.\n", + " Store the actions. Only used for illustration.\n", " index_action : int\n", - " Index of the action. Only used for the illustration matter.\n", + " Index of the action. Only used for illustration.\n", " \"\"\"\n", " def __init__(self, max_n):\n", " self.max_n = max_n\n", @@ -46,7 +47,7 @@ " self.index_action = 0\n", " \n", " def execute(self, cp_schedule):\n", - " \"\"\"Execute forward and adjoint with a checkpointing schedule.\n", + " \"\"\"Execute forward and adjoint using a checkpointing schedule.\n", "\n", " Parameters\n", " ----------\n", @@ -75,7 +76,7 @@ " \n", " n1 = min(cp_action.n1, self.max_n)\n", "\n", - " # writting the symbols used in the illustrations \n", + " # the symbols used in the illustrations \n", " if cp_action.write_ics and cp_action.write_adj_deps:\n", " singlestorage = True\n", " a = '\\u002b' \n", @@ -122,7 +123,7 @@ " @action.register(EndForward)\n", " def action_end_forward(cp_action):\n", " assert step_n == self.max_n\n", - " act = \"End Forward\" # action\n", + " act = \"End Forward\"\n", " self.list_actions.append([self.index_action, act, str(cp_action)])\n", " if cp_schedule._max_n is None:\n", " cp_schedule._max_n = self.max_n\n", @@ -134,7 +135,7 @@ " assert step_r == self.max_n\n", " # Informing the schedule that the execution is exhausted\n", " is_exhausted = cp_schedule.is_exhausted\n", - " act = \"End Reverse\" # action\n", + " act = \"End Reverse\"\n", " self.list_actions.append([self.index_action, act, str(cp_action)])\n", " \n", " step_n = 0 # forward step\n", @@ -176,7 +177,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "In this current case, `NoneCheckpointSchedule` class provides the checkpoint schedule to the time execution of the forward model. " + "In this current case, `NoneCheckpointSchedule` class provides the checkpoint schedule , running the forward model. " ] }, { @@ -226,9 +227,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## Trivial Schedule for all storage data\n", + "## Trivial schedule for forward and adjoint computation\n", "\n", - "The following code is practical for the cases where the user intend to store the forward data for all steps. This schedule is given by `stepSingleMemoryStorageSchedule`.\n", + "The following code is practical for the cases where the user intend to store the forward data for all steps. This schedule is given by `SingleMemoryStorageSchedule`.\n", "\n", "*The `SingleMemoryStorageSchedule` schedule does not require the `n1` step. Analagous to `NoneCheckpointSchedule`, `SingleMemoryStorageSchedule` can create its schedule without prerequisite of specifying the `n1`.*" ] @@ -358,7 +359,7 @@ "metadata": {}, "source": [ "## Schedules given by checkointing algorithms\n", - "Here, we start to present the schedules obtained by the checkpointing algorithms\n", + "Here, we start to present schedules obtained by checkpointing algorithms\n", "### Revolve\n", "The Revolve strategy, as introduced in reference [1], generates a schedule that only uses `'RAM'` storage type. \n", "\n", @@ -407,9 +408,9 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "### Multistage checkpoiting \n", + "### Multistage checkpointing \n", "\n", - "The schedule as depicted below, employes a *MultiStage* distribution of checkpoints between `'RAM'` and `'disk'` as described in [2]. This checkpointing allows only memory storage (`'RAM'`), or only `'disk'` storage, or in both `'RAM'` and `'disk'`.\n", + "The schedule as depicted below, employes a *MultiStage* distribution of checkpoints between `'RAM'` and `'disk'` as described in [2]. This checkpointing approach allows only memory storage (`'RAM'`) or `'disk'` storage, or a combination.\n", "\n", "The following code use two types of storage, `'RAM'` and `'disk'`." ] @@ -420,8 +421,8 @@ "metadata": {}, "outputs": [], "source": [ - "snaps_in_ram = 1 # number of checkpoints stored in RAM\n", - "snaps_on_disk = 1 # number of checkpoints stored in disk\n", + "snaps_in_ram = 1 # maximum number of checkpoints stored in RAM\n", + "snaps_on_disk = 1 # maximum number of checkpoints stored in disk\n", "cp_schedule = MultistageCheckpointSchedule(max_n, snaps_in_ram, snaps_on_disk)\n", "solver_manager.execute(cp_schedule)" ] @@ -549,7 +550,7 @@ "\n", "Two-level binomial schedule was presented in reference [6], and its application was performed in the work [7]. \n", "\n", - "The two-level binomial checkpointing stores the forward restart data based on the user-defined `period`. In this schedule, we can define the limite for additional storage of the forward restart data during the step advancing of the adjoint model. The default storage type is `'disk'`.\n", + "The two-level binomial checkpointing stores the forward restart data based on the user-defined `period`. In this schedule, we can define the limit for additional storage of the forward restart data during the step advancing of the adjoint model. The default storage type is `'disk'`.\n", "\n", "The two-level binomial schedule is provided by `TwoLevelCheckpointSchedule`. To obtain this schedule we need the period `period = 2` and the extra forward restart data storage `add_snaps = 1`. " ] @@ -636,9 +637,9 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.11.4" + "version": "3.10.12" } }, "nbformat": 4, - "nbformat_minor": 2 + "nbformat_minor": 4 }