Skip to content

Commit

Permalink
Edits to the tutorial
Browse files Browse the repository at this point in the history
  • Loading branch information
@jrmaddison
jrmaddison committed Sep 15, 2023
1 parent 541f5ca commit faf7824
Showing 1 changed file with 23 additions and 22 deletions.
45 changes: 23 additions & 22 deletions docs/notebooks/tutorial.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
},
{
Expand All @@ -28,25 +28,26 @@
"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",
" self.list_actions = []\n",
" 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",
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand Down Expand Up @@ -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. "
]
},
{
Expand Down Expand Up @@ -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`.*"
]
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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'`."
]
Expand All @@ -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)"
]
Expand Down Expand Up @@ -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`. "
]
Expand Down Expand Up @@ -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
}

0 comments on commit faf7824

Please sign in to comment.