Better documentation for restart

[friedmud]

Seriously - there has to be some documentation on this!

There used to be an old wiki page that is now horribly out of date... it's pretty much impossible to use restart right now for a normal human...

[permcody]

This would be a great task while the systems are down. Should we add it to the manual or to the wiki?

I sent this to the mailing list the other day, I can start with this, might need help from @aeslaughter on the SolutionUserObject part:

Hello Dina,

I'm sending this to the mailing list since there's a lot to cover here. We've cleaned up the restart system quite a bit since July and we support several ways of restarting from a solution so you might want to think about your simulation and pick the best one.

1. First if your mesh is exactly the same on your second simulation, you can simply read values in from your solution file right onto the mesh. No interpolation or projection. This is our oldest version of restart but it is useful for several restart cases.
2. We also support a SolutionUserObject/SolutionUserAux restart capability. This is similar to Removed #1 but this version projects the simulation onto a different mesh.
3. Finally we have a "recover" version of restart which is where your simulation can pickup right where it left off and continue. Using the checkpoint files, one can continue a simulation or start a new simulation using data in the checkpoint files.

We need to create better documentation for all of these cases so for now, the best way to learn, is to find an example, and work from there. Here are a few of the folders you might look at in the test directory (under test/tests):

restart
auxkernels/solutionaux

Finally you can control the number of checkpoint files written. You simply need to create a checkpoint subblock underneath the Outputs section of your input file instead of using the shortcut option of checkpoint=true. See

outputs/checkpoint.

As you can see there is a lot to digest here. Please try some of these out and let us know if you have more questions.

[aeslaughter]

I vote for wiki page.

[friedmud]

Wiki

On Wednesday, August 27, 2014, Andrew E Slaughter notifications@github.com
wrote:

I vote for wiki page.

—
Reply to this email directly or view it on GitHub
#3811 (comment).

Sent from my iPhone

[permcody]

Please comment on this page. Hopefully it is captures our ideas of restart and recover
http://mooseframework.org/wiki/Restart/

[permcody]

@friedmud in generating this documentation, it appears that we no longer support pure XDA restart. By this I mean that we can't use an XDA file as the "file_restart_base" in Executioner. Is this correct? If so, we probably should rename the xda_restart_test to something else. If not, why does the XDA restart test use checkpoint files? Just curious

[friedmud]

I agree that we should remove the xda restart test. I believe that I had left it there to make sure that the new restart stuff could do what the old system could do. But now it's time to remove it.

HOWEVER... we do need more restart tests in the restart directory... especially one that uses XDA and one that uses XDR with SolutionUserObject and SolutionFunction

Right now there is not a single one that uses XDR - and the tests that use SolutionUserObject are kinda spread out and hard to find.

[aeslaughter]

The SolutionUserObjects tests are in two places: auxkernels/solution_aux
and functions/solution_function, with the majority in the auxkernels
directory. I feel that it is well tested, I have added several of the past
few months while fixing it up, I know there are tests for exodus, xda, and
xdr, adaptivity, and restart.

On Wed, Aug 27, 2014 at 7:48 PM, Derek Gaston notifications@github.com
wrote:

I agree that we should remove the xda restart test. I believe that I had
left it there to make sure that the new restart stuff could do what the old
system could do. But now it's time to remove it.

HOWEVER... we do need more restart tests in the restart directory...
especially one that uses XDA and one that uses XDR with SolutionUserObject
and SolutionFunction

Right now there is not a single one that uses XDR - and the tests that use
SolutionUserObject are kinda spread out and hard to find.

—
Reply to this email directly or view it on GitHub
#3811 (comment).

[aeslaughter]

SolutionUserObjects currently has 90.3% line coverage and 95% function coverage.

[friedmud]

My point wasn't that this stuff isn't tested.... but that users don't know to look for it (hell, even I don't know exactly where to look for it!). They don't even know that they should be looking for something like SolutionUserObject and SolutionFunction!

We need to clean up the tests/restart directory to make it more clear what the options are. Each option needs to be well represented in that directory: initial_from_file, restart, recover and solution_function_initial_condition.

Users do get used to be able to go to our tests directory and use them as supplemental documentation (something we encourage) so we should make sure that the options are clear there...

[aeslaughter]

I would argue that SolutionUserObject is not really part of restart, it can do far more than load an initial condition. It also support reading and interpolating data on each timestep. It is more of a generic functionality for sampling files. I am working on the documentation now.

[friedmud]

It is both - and should be represented in both places.

Just yesterday I was helping Dina Yuryev here at MIT. She was running a transient phase-field simulation for "c" and computing a complex scaling of that variable that she called "c_aux". She was using mesh adaptivity to track the phase-fronts.

Now - she wanted to take "c_aux" and the adapted mesh at the end of the first simulation and start a new simulation solving for "d" where the initial condition was "c_aux".

We told her to "go look at the restart tests"... which she did. She tried to use initial_from_file... but it just gave her a jumbly mess because it doesn't work with adapted meshes (which isn't documented anywhere). Then she tried to use the actual "restart" capability.... but how do you pull the solution of "c_aux" over to the initial condition for a new nonlinear variable named "d"???

The only answer is to use SolutionUserObject and SolutionFunction... but those aren't represented in the restart directory - and she had never heard of them (why would she). As a user she wanted to "do restart" but in a specific way.

Documentation, tests and examples are not only about reflecting the actual structure of the code... but also about anticipating what a user will be looking for and making sure they can find the tools they need to get their job done....

[friedmud]

BTW - while we're talking about this use of SolutionFunction and SolutionUserObject it's not really clear how things act when you're trying to use a particular timestep of an XDA/R solution as an initial condition.

I was worried that even though we specified a particular timestep's output file that it was going to still do time interpolation and maybe give us the initial condition from the XDA/R sequence. Is time interpolation ever done for XDA/R files?

[aeslaughter]

Time interpolation is not done for XDR/A since the files are all separate for each timestep.

[aeslaughter]

• See http://mooseframework.org/wiki/MooseSystems/UserObjects/
• The Restart and Recovery stuff now also links to http://mooseframework.org/wiki/MooseSystems/UserObjects/SolutionUserObject/