GitLab

The GitLab interface also supports hosting a contribution guide.
This guide is fairly basic, but outlines three main points
1. Talk with Chris Subich before merging changes
2. How to submit a merge request via GitLab
3. Version number etiquette

wave_reader accidentally wrote tracer to rho.dump
this has been corrected and now outputs tracer.dump

Updated version to 2.0.3

Previous parallel write needed to have separate function for grids and
arrays. They have now been merged into one function. The cross-over
should be seemless, as the new parallel write is still called
write_array and accepts the same inputs.

Updated version to 2.0.2

GiLab (and other git servers) include the main README as the front page
of the repository. This commit initializes the README with basic
information including a link to the thesis, paper, and relevant page on
the fluids wiki.

The previous memmap read commands would require large amounts of virtual
memory. This could cause memory problems when restarting large
simulations. The new parallel read/write should side-step these
problems.

Tested on gravity_current casefile for 2D and 3D simulations.

Updated version to 2.0.1

Running './casefile.x --version' prints the SPINS version with which
the executable was compiled.

The file VERSION now records the MAJOR_VERSION, MINOR_VERSION,
and PATCH_VERSION.
To update the version number, the user only needs to modify the
appropriate lines in VERSION.

Makefile has been updated to automatically pass the version
information through compiler flags.

BaseCase.cpp has been updated to add a print statement into the
initialization function. By default, every casefile that uses
BaseCase will now print the SPINS version with which is was compiled.
This should help avoid issues with mis-matched versions.

It will appear in the output as:
SPINS Version 1.0.1

The starting version is set to 2.0.0

StackOverflow has a nice summary of when to change which version number
(https://stackoverflow.com/questions/3826580/what-rules-does-software-version-numbering-follow)
 - Major version numbers change whenever there is some significant change
being introduced. For example, a large or potentially
backward-incompatible change to a software package.
 - Minor version numbers change when a new, minor feature is introduced or
when a set of smaller features is rolled out.
 - Patch numbers change when a new build of the software is released to
customers. This is normally for small bug-fixes or the like.

=== Science ===
The directory Science/ now contains files corresponding to
the various functions in the now-removed Science.cpp.

Filenames correspond directly with the function name, and each
file contains only one functions, with a few notable exceptions.
 - Science/get_quads.cpp contains get_quads_x, get_quads_y, and get_quads_z
 - Science/compute_background_PE contains the helper function
compare_pairs

The global variables _quadw_x, _quadw_y, and _quadw_z are declared as
extern in Science.hpp and declared in Science/compute_quadweights.cpp

=== Makefile ===
The Makefile has been modified accordingly. It now automatically detects
all Science/*.cpp files and includes them in the compile recipe.

The Makefile has also been tidied up a little bit by defining a variable
SPINS_BASE which points to the core files.

Combined the mapped and unmapped cases for this into a single
case file.

With the retirement of belize, which formerly hosted a fixed
copy of the dependency libraries, make_deps.sh would no
longer download and build said libraries.

These libraries are now instead hosted in a dedicated
repository at UWGit, so make_deps.sh has been changed to
clone this repository.

The order of the input arguments for compute_vort_x,y,z was changed
some time over the last year, but this was not accounted for in
the calculation for enstrophy density.

This case has uncovered that the BPE calculation returns
incorrect values when a Chebyshev grid is used on a field scale.
The BPE calculation uses the quadrature weights as the volumes
of each cell. This is true when the grid is regular, but incorrect
for Chebyshev grids.

To first approximation the Cheb quadrature weights are close to
the volumes of the cells. This leads to the BPE calculation
being accurate to 8 significant figures. 8 sig figs is not enough
on fields scales since the magnitude of the PE can be very, very
large. The difference of the BPE from the PE can thus be smaller
than these 8 sig figs.

Some simulations have a long clock time per step, but have a short
write to disk time. If only the short write to disk time is
accounted for in the check_and_dump command then insufficient
time may be allocated for the dump to disk. Both are now accounted
for.

The energy transfer rate from internal energy to BPE is generalized
to handle both mapped, and unmapped cases. What had been there
was in fact correct for both, though it wasn't realized at first.

Archived old wave_reader cases.

Minor fixes in other case files.

The full xgrid and ygrid are unnecessary since x and y only
depend on a single variable (or index - ii for x, and jj for y).
The variables xx and yy can be used instead of xgrid and ygrid,
respectively. Creating the full grids for these fields is a
waste of memory.

This commit amends Cheb_2dmg::resid_dot (dot-product of
residual vectors in the context of the 2D GMRES/multigrid
iteration) to perform the dot-product in the simplest way,
as a sum over grid elements.

Before this, the code (which is left in the file but
disabled by #if 1 / #else) tried to be clever and
evenly-weight contributions from the interior, the boundary
conditions, and the mean-pressure error (if the problem was
indeterminate).  This evidently caused the long-standing
problem of the GMRES inner iteration being far more
optimistic about error (as reported by LAPACK) than would be
computed by directly measuring the residual error.

This problem was ultimately discovered when the
doc_map_iwave case broke.  Even though this broken residual
code has been in SPINS since before it was
version-controlled via GIT, the map_iwave case would still
converge (and relatively quickly) when the multigrid
iteration had a relatively large coarse-solve size.

Git bisect pinned the broken documentation case on the
change that reduced the coase-grid size, which reduced the
GMRES convergence rates enough that the errors caused by
*this* problem broke convergence.

Since this change replaces the error norm calculations used
by GMRES, it should be treated with caution and mapped-grid
cases should have a mark-1-eyeball inspection of results for
a while.

--

Additionally, for debugging utility this change also
includes crude residual/basis output for the 2D GMRES
solver.  All current uses are commented out.

The addition of an analysis call on the initial data resulted
in the Nth time step to correspond with iteration N+1. This isn't
a problem, just dissatisfying.

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.

If dt_max is not given in the spins.conf, it is now explicitly
set to 0 so as to be adjusted later to use the buoyancy frequency.
The dt_max is also printed in the initialization for clarity.

A second calling of analysis was previously added to run on the
initial configuration, but this was repeated for each subsequent
time-step. This repetition has been fixed.

Also reorganize how some diagnostics are added to the file.
This is now a little clearer to read since similar diagnostics
are placed near each other.

The dimensional rho option should not be after the mapping options
since the mapping options will need to be specified for an
unmapped dimensional density case. This now makes the optional
argument ordering more logical.

In the previous merge, compilation of Sorter.o went missing from the
Makefile, and a typo was introduced in the gravity_current case file;
each would prevent a build from finishing.  These are fixed.

In certain cases, diagnostic computation required Nx/y/z > 1, but this
check was not repeated for adding the diagnostic output to the
respective file; this could result in unexpectedly writing 0 or
meaningless data to the file.

Conflict in Makefile, fixed with formatting corrections

This changeset adds a compile-time option on whether to include the
timing code.  If SPINS is compiled without TIMINGS=true, the timing code
is #defined to a no-op and should not otherwise affect the performance
of the software; timing_stack_report will instead print a short error
message.

Because this affects #defines in header files, changing from
TIMINGS=true to false (or vice versa) should only be done with a 'make
clean'.  Not doing so could leave the timing code in an inconsistent
state and result in either link-time errors (if older code calls timing
code that is #defined away) or a corrupted/growing timing stack (if for
example a timing_push() is compiled in but the corresponding
timing_pop() is removed.)