Add a design document for cached output files

[xylar]

This is being implemented in #184

[xylar]

@mark-petersen, as I mentioned in #184, I think we need a design document for this work. Here it is.

@matthewhoffman, this work is general enough that it could affect the landice core. If you are not interested in this capability, that's fine. Please just give the design doc a quick glance to make sure it seems to "do no harm" for you. If you do want to have the capability, please look more closely and make sure it meets the needs you foresee having.

I will make some additional comments or ask questions in specific sections.

[xylar]

To render the design doc in sphinx, set up the compass environment as usual. Hopefully, you can set it up on your laptops because that makes it easier to open the results in a browser. Once you have sourced the activation script, run:

cd docs
make html

Then, open _build/html/design_docs/cached_outputs.html in your browser.

[xylar]

@mark-petersen, I believe this is finished but please feel free to commend and request changes.

[mark-petersen]

@xylar thanks, this looks great. I really like the brief notation of 'c' in

compass setup -n 40c

and then the ability for a longer format with the --cached flag.

I agree that we do not need to require the ability to set up a cached version of every step in a test case. For some domains, like low-resolution regular hexes, it does not make sense to cache the input file.

[xylar]

I agree that we do not need to require the ability to set up a cached version of every step in a test case. For some domains, like low-resolution regular hexes, it does not make sense to cache the input file.

To be clear, the current implementation does support caching the outputs of every single step of every test case. But I haven't actually run all tests and cached their outputs. So in that sense, we will need to add cache files to the compass_cache database using the compass cache tool as we find we need them.

[xylar]

Thanks very much for the review! I think I'll merge this, and then we can make minor tweaks in #184 if need be.