More illustrative example for checkpointing

docs/src/model_setup/checkpointing.md

@@ -1,51 +1,61 @@
 # [Checkpointing](@id checkpointing)
 
-A checkpointer can be used to serialize the entire model state to a file from which the model
+A [`Checkpointer`](@ref) can be used to serialize the entire model state to a file from which the model
 can be restored at any time. This is useful if you'd like to periodically checkpoint when running
-long simulations in case of crashes or cluster time limits, but also if you'd like to restore
+long simulations in case of crashes or hitting cluster time limits, but also if you'd like to restore
 from a checkpoint and try out multiple scenarios.
 
 For example, to periodically checkpoint the model state to disk every 1,000,000 seconds of simulation
 time to files of the form `model_checkpoint_iteration12500.jld2` where `12500` is the iteration
-number (automatically filled in)
+number (automatically filled in).
 
-```@meta
-DocTestSetup = quote
-    using Oceananigans
-end
-```
+Here's an example where we checkpoint every 5 iterations. This is _way_ too often, we only do it here for
+illustration purposes.
 
 ```@repl checkpointing
-using Oceananigans, Oceananigans.Units
+using Oceananigans
+
+model = NonhydrostaticModel(grid=RectilinearGrid(size=(8, 8, 8), extent=(1, 1, 1)))
+
+simulation = Simulation(model, Δt=1, stop_iteration=8)
+
+simulation.output_writers[:checkpointer] = Checkpointer(model, schedule=IterationInterval(5), prefix="model_checkpoint")
+```
 
-model = NonhydrostaticModel(grid=RectilinearGrid(size=(16, 16, 16), extent=(1, 1, 1)))
+Again, for illustration purposes of this example, we also add another callback so we can see the iteration
+of the simulation
 
-simulation = Simulation(model, Δt=1, stop_iteration=1)
+```@repl checkpointing
+show_iteration(sim) = @info "iteration: $(iteration(sim)); time: $(prettytime(sim.model.clock.time))"
+add_callback!(simulation, show_iteration, name=:info, IterationInterval(1))
+```
 
-simulation.output_writers[:checkpointer] = Checkpointer(model, schedule=TimeInterval(5days), prefix="model_checkpoint")
+Now let's run
 
+```@repl checkpointing
 run!(simulation)
 ```
 
-The default options should provide checkpoint files that are easy to restore from in most cases.
+The default options should provide checkpoint files that are easy to restore from (in most cases).
 For more advanced options and features, see [`Checkpointer`](@ref).
 
 ## Picking up a simulation from a checkpoint file
 
 Picking up a simulation from a checkpoint requires the original script that was used to generate
-the checkpoint data. Change the first instance of [`run!`](@ref) in the script to take `pickup=true`:
+the checkpoint data. Change the first instance of [`run!`](@ref) in the script to take `pickup=true`.
+
+When `pickup=true` is provided to `run!` then it finds the latest checkpoint file in the current working
+directory, loads prognostic fields and their tendencies from file, resets the model clock and iteration,
+to the clock time and iteration that the checkpoint corresponds to, and updates the model auxiliary state.
+After that, the time-stepping loop. In this simple example, although the simulation run up to iteration 8,
+the latest checkpoint is associated with iteration 5.
 
 ```@repl checkpointing
-simulation.stop_iteration = 2
+simulation.stop_iteration = 12
 
 run!(simulation, pickup=true)
 ```
 
-which finds the latest checkpoint file in the current working directory (in this trivial case,
-this is the checkpoint associated with iteration 0), loads prognostic fields and their tendencies
-from file, resets the model clock and iteration, and updates the model auxiliary state before
-starting the time-stepping loop.
-
 Use `pickup=iteration`, where `iteration` is an `Integer`, to pick up from a specific iteration.
 Or, use `pickup=filepath`, where `filepath` is a string, to pickup from a specific file located
 at `filepath`.

src/Grids/rectilinear_grid.jl

@@ -50,7 +50,6 @@ const XRegularRG   = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Number}
 const YRegularRG   = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Any,    <:Number}
 const ZRegularRG   = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Any,    <:Any,    <:Number}
 const XYRegularRG  = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Number, <:Number}
-const XYRegularRG  = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Number, <:Number}
 const XZRegularRG  = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Number, <:Any,    <:Number}
 const YZRegularRG  = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Any,    <:Number, <:Number}
 const XYZRegularRG = RectilinearGrid{<:Any, <:Any, <:Any, <:Any, <:Number, <:Number, <:Number}