The stress along the bottom and top surfaces are calculated
and written to a file (stresses_(top/bottom).txt) using the function
stresses_top and stresses_bottom in BaseCase. These functions are
especially useful with mapped cases.

Christopher Subich authored Nov 01, 2017 and Christopher Subich committed Nov 01, 2017

The template form of add_diagnostic<x> is attractive, but to
be properly used the template implementation must be visible
at the same time as the header file itself.  The
instantiations formerly in BaseCase.cpp were not likely to
be visible to a program, increasing compile time (if they
were re-instantiated) or causing an error (if the
implementation was not visible).  This change:

*) Moves the implementation of add_diagnostic to a new
BaseCase_impl.cc
*) Includes this impementation file from BaseCase.hpp, with
a double-inclusion guard
*) Preserves instantiations of <double> and <int>, with new
'extern' declarations in BaseCase.hpp to prevent
double-definition.

Diagnostic values (like total KE/ total enstrophy/ mass/ etc)
are often desired outputs at each time-step. These values
are easily printed to a txt file using two functions:
add_diagnostic and write_diagnostics.

add_diagnostic adds the name and value of a diagnostic into a
pair of strings which will be written into diagnostics.txt
which the function write_diagnostics.

Usage of add_diagnostic is as follows:
add_diagnostic(name, value, header, line);
This will add the string, 'name', onto the string, 'header', which
will be the header of the diagnostics.txt file. The double (or
int), 'value', will be added onto the string, 'line', which will
be a row (or line) in the diagnostics.txt file.

write_diagnostics will write these lines (header and line) into
diagnostics.txt.

A new case file, derivatives.cpp, gives a means to compute
derivatives of any field or to compute vorticity components.
The vorticity calculation in Science is completely re-written
so-as to also work for mapped grids.

The derivatives file is built to compute secondary variables
after a run has already been completed. This uses spins' built-in
derivative toolkit allowing multiple variables to be calculated
in parallel. A derivative field (one that is the derivative of
another) is denoted by an underscore followed by the direction
the derivative was taken in (ie. u_x is the x derivative of u).

The method get_dt_max inside BaseCase was added in a
previous commit as part of the effort to include the
'default' timestep-checking code inside BaseCase.

The intent is for user code to override this method with a
problem-specific maximum timestep, but if the user code did
not do this the previous implementation would return '0'.

This would cause SPINS to error, as a timestep of <= 0 is
obviously invalid.  However, the error message would be
unintuivie, referring to the <=0 timestep rather than the
root cause of the user not implementing get_dt_max().

This change replaces the previous default method with one
that immediately aborts, with an assertion failure if
assert() is enabled at compile time.

A new case file, derivatives.cpp, gives a means to compute
derivatives of any field or to compute vorticity components.
The vorticity calculation in Science is completely re-written
so-as to also work for mapped grids.

The derivatives file is built to compute secondary variables
after a run has already been completed. This uses spins' built-in
derivative toolkit allowing multiple variables to be calculated
in parallel. A derivative field (one that is the derivative of
another) is denoted by an underscore followed by the direction
the derivative was taken in (ie. u_x is the x derivative of u).

The empty shell of check_timestep in BaseCase has been filled
with what was essentially the same thing in each case file.
Again, this is just more case file house cleaning.

A few ancillary functions have also been written to help.
The most important might be get_dt_max() which returns dt_max.
dt_max can either be specified in spins.conf or defined in the
case file based on the buoyancy frequency. Currently, if
dt_max > 0 and in spins.conf, then that value is used. Otherwise,
0.5/sqrt(N2_max) is used.

The re-definition of check_timestep in each case file can now be
removed so long as the associated ancillary functions and
parameters are included.

This commit moves the helper function that process
expansion/boundary conditions ("FOURIER" -> PERIODIC, etc)
to BaseCase.cpp, from Options.

This change should be invisible to most case files, which
habitually include BaseCase for helper functions as-is, but
it allows Options to once again be independent of
NSIntegrator.  This improves modularity for other uses of
the code, such as a hypothetical SPINSoff (get it?  it's a
pun) that would like to do some spectral voodoo with an
option file but doesn't need the full Navier-Stokes
machinery.

- Added 1D and 2D outputs
- Added parallel writing and reading

The automatic_grid() helper function in BaseCase was not properly
functional if called without supplied arguments for the 1D grids
xx/yy/zz.  Now, if these arguments are null or not supplied, the
function will do its grid generation using temporarily-allocated
internal 1D arrays, deleted at the end of its execution.

and write vertical chain was moved to BaseCase (can write out vertical profile at a high temporal frequency)

Safety dump estimates output write time and writes fields with enough time before the computation limit is reached

The case file source code is embedded into the binary at compile time.
At runtime, the source code is printed to spinscase.cpp. This eliminates
the need to maintain a copy of the case file alongside the binary.

This is the initial commit of SPINS to a git repository, coming from
an essentially unmanaged environment.  While this is a *complete*
archive, this is probably not the most useful form for development
going forward.  Notably, the future management should be:

1) Pare down the case files

2) Establish branches for individual users.  Not as a long-term goal,
   but instead to keep user-specific case files from lingering in
   the main repository long after their use is obsolete.

2b) Establish semipermanent branches for typical users.  A release
   branch should include the basic documentation cases, a benchmark
   case should include benchmarking cases, and there are probably
   others that aren't coming to mind now.

3) Add helpful MATLAB processing scripts to the repository.  Too
   much of that is ad-hoc now, completely unmanaged.

4) For papers/etc, establish tagged versions.