|
| 1 | +# Checkpoint and Restart (Splitting a Transient Calculation) |
| 2 | + |
| 3 | +A step-by-step tutorial for **checkpointing and restarting** a code_saturne |
| 4 | +calculation: a transient run is stopped after 1200 time steps, then a second run |
| 5 | +restarts from its checkpoint and continues to step 3000. The restarted history |
| 6 | +superposes the one of an uninterrupted reference run down to the write precision |
| 7 | +of the probe files, demonstrating that a split calculation is equivalent to a |
| 8 | +continuous one. |
| 9 | + |
| 10 | +The transient is a laminar channel whose inlet velocity ramps between plateaus |
| 11 | +(driven by a time table, see |
| 12 | +[Inc_Time_Table_Inlet](../Inc_Time_Table_Inlet)): the restart happens in the |
| 13 | +middle of the scenario, which also shows that time-dependent inputs resume |
| 14 | +correctly. |
| 15 | + |
| 16 | +Maintained by [Simvia](https://Simvia.tech/fr), part of the |
| 17 | +[tutoriel-code_saturne](https://github.com/simvia-tech/tutorials-code_saturne) collection. |
| 18 | + |
| 19 | +## Learning objectives |
| 20 | + |
| 21 | +After completing this tutorial you will be able to: |
| 22 | + |
| 23 | +1. Know what code_saturne writes in the `checkpoint/` directory of a run. |
| 24 | +2. Configure a restart in the GUI (checkpoint path, or automatic mode) and understand that the iteration count is absolute. |
| 25 | +3. Split a transient calculation into successive runs with named result directories. |
| 26 | +4. Verify that a restarted calculation reproduces the uninterrupted one. |
| 27 | + |
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +| Requirement | Detail | |
| 31 | +|---|---| |
| 32 | +| code_saturne | **v9.1** | |
| 33 | +| Background | Any transient code_saturne case | |
| 34 | + |
| 35 | +If code_saturne is not yet installed, build it from the |
| 36 | +[official homepage](https://code-saturne.org/), pull a |
| 37 | +ready-to-use Singularity image from the |
| 38 | +[Open Simulation Center](https://open-simulation-center.org/downloads/code_saturne/code_saturne), |
| 39 | +or pull the |
| 40 | +[Simvia Docker image](https://hub.docker.com/r/Simvia/code_saturne) before continuing. |
| 41 | + |
| 42 | +## Case files |
| 43 | + |
| 44 | +```text |
| 45 | +Inc_Checkpoint_Restart/ |
| 46 | +├── CASE/ |
| 47 | +│ └── DATA/ |
| 48 | +│ ├── setup.xml # pre-configured GUI case (continuous reference) |
| 49 | +│ └── inlet_velocity.csv # time table driving the inlet ramps |
| 50 | +├── FIGURES/ # figures used in this README |
| 51 | +└── README.md |
| 52 | +``` |
| 53 | + |
| 54 | +There is no mesh file: the channel grid is built by code_saturne's internal |
| 55 | +Cartesian mesher, directly from `setup.xml`. |
| 56 | + |
| 57 | +## Physical model |
| 58 | + |
| 59 | +The flow is laminar, incompressible and truly transient |
| 60 | +($\Delta t=0.01\ \mathrm{s}$, 3000 steps, 30 s): a viscous fluid |
| 61 | +($\rho=900\ \mathrm{kg\,m^{-3}}$, $\mu=0.09\ \mathrm{Pa\,s}$) enters a plane |
| 62 | +channel ($L=1\ \mathrm{m}$, $H=0.02\ \mathrm{m}$, $Re_{D_h}=40$ to $200$) with a |
| 63 | +velocity that ramps between plateaus (0.1, 0.5 and 0.25 m/s). The physics is |
| 64 | +deliberately simple: the subject of the tutorial is the calculation workflow, |
| 65 | +not the flow. |
| 66 | + |
| 67 | +<p align="center"> |
| 68 | + <img src="FIGURES/mesh_boundary_conditions.png" |
| 69 | + alt="Transient channel, and the timeline of the three runs: part1, restarted part2, and the continuous reference." |
| 70 | + width="1000"/> |
| 71 | + <br> |
| 72 | + <em>Figure 1: (a) The transient channel. (b) The three runs: part1 stops at |
| 73 | + step 1200 and writes a checkpoint; part2 restarts from it and continues to |
| 74 | + step 3000; the continuous run is the reference.</em> |
| 75 | +</p> |
| 76 | + |
| 77 | +## The checkpoint (the feature) |
| 78 | + |
| 79 | +Every run writes a `checkpoint/` directory inside its result directory |
| 80 | +(`RESU/<id>/checkpoint/`), containing the mesh (`mesh_input.csm`), the main |
| 81 | +variables (`main.csc`), auxiliary data (`auxiliary.csc`) and, when relevant, |
| 82 | +notebook and time-table state. By default it is written at the end of the run |
| 83 | +and periodically during long calculations. |
| 84 | + |
| 85 | +A restart is configured in the GUI under **Calculation management, Start/Restart** |
| 86 | +by pointing to a previous checkpoint, which stores in `setup.xml`: |
| 87 | + |
| 88 | +```xml |
| 89 | +<start_restart> |
| 90 | + <restart path="RESU/part1/checkpoint"/> |
| 91 | +</start_restart> |
| 92 | +``` |
| 93 | + |
| 94 | +(`path="*"` selects the most recent checkpoint automatically.) Two important |
| 95 | +behaviours: |
| 96 | + |
| 97 | +- The **iteration count is absolute**: with 3000 iterations requested, a restart |
| 98 | + from step 1200 performs steps 1201 to 3000. |
| 99 | +- Time-dependent inputs (time tables, notebook values saved in the checkpoint) |
| 100 | + resume at the restart time. |
| 101 | + |
| 102 | +## Running the simulation |
| 103 | + |
| 104 | +The shipped `setup.xml` is the continuous reference (3000 steps, no restart). |
| 105 | +The split workflow changes one setting between runs: |
| 106 | + |
| 107 | +```bash |
| 108 | +cd CASE |
| 109 | + |
| 110 | +# run A: set iterations to 1200 in the GUI, then |
| 111 | +code_saturne run --n 4 --id part1 |
| 112 | + |
| 113 | +# run B: set iterations back to 3000 and select the restart |
| 114 | +# (Calculation management > Start/Restart > RESU/part1/checkpoint), then |
| 115 | +code_saturne run --n 4 --id part2 |
| 116 | + |
| 117 | +# run C (reference): iterations 3000, restart disabled |
| 118 | +code_saturne run --n 4 --id continuous |
| 119 | +``` |
| 120 | + |
| 121 | +Each run creates its own `CASE/RESU/<id>/` with `run_solver.log`, `monitoring/` |
| 122 | +(probe histories recorded at every step) and `checkpoint/`. The `part2` log |
| 123 | +confirms the restart (`Reading file: restart/main.csc`). |
| 124 | + |
| 125 | +## Results and verification |
| 126 | + |
| 127 | +<p align="center"> |
| 128 | + <img src="FIGURES/restart_superposition.png" |
| 129 | + alt="Restarted history on top of the continuous reference, and their pointwise difference." |
| 130 | + width="1000"/> |
| 131 | + <br> |
| 132 | + <em>Figure 2: (a) The outlet velocity history of part1 and of the restarted |
| 133 | + part2, on top of the continuous reference. (b) Pointwise difference between |
| 134 | + part2 and the reference: zero at most steps, with isolated points at the |
| 135 | + $10^{-8}$ write precision of the probe files.</em> |
| 136 | +</p> |
| 137 | + |
| 138 | +| Comparison | Max difference | |
| 139 | +|---|---:| |
| 140 | +| part1 vs continuous (steps 1 to 1200) | 0 (bitwise identical) | |
| 141 | +| part2 (restarted) vs continuous (steps 1201 to 3000) | $10^{-8}\ \mathrm{m\,s^{-1}}$ (probe-file precision) | |
| 142 | + |
| 143 | +The split calculation is therefore indistinguishable from the uninterrupted one: |
| 144 | +the checkpoint stores the complete solver state. The restart happened in the |
| 145 | +middle of the inlet ramp scenario and the time table resumed exactly. |
| 146 | + |
| 147 | +## Summary |
| 148 | + |
| 149 | +This tutorial split a 3000-step transient calculation into two runs: a first run |
| 150 | +stopped at step 1200 (writing its `checkpoint/`), and a second run restarted |
| 151 | +from that checkpoint through the GUI setting |
| 152 | +(`start_restart/restart path`), continuing to the absolute iteration target. The |
| 153 | +restarted history matches the uninterrupted reference exactly, at the write |
| 154 | +precision of the probe files. Checkpointing is the standard way to handle long |
| 155 | +calculations (job time limits, staged convergence, model changes on a converged |
| 156 | +state) and works identically for every code_saturne physics. |
| 157 | + |
| 158 | +## References |
| 159 | + |
| 160 | +1. code_saturne documentation: <https://code-saturne.org/doc/>. |
| 161 | + |
| 162 | +## Authors |
| 163 | + |
| 164 | +[Simvia](https://Simvia.tech/fr) - Questions, remarks and requests are welcome. |
0 commit comments