# Test cases

The following test cases are run automatically whenever the code
changes.

Note that only the documented test cases appear in the list below
(follow the [All tests](/src/test/) link for a complete list).

## Advection

* [Pure rotation of a smooth tracer field](rotation.c)
* [Time-reversed advection in a vortex](advection.c)

## Systems of conservation laws

* [Bouncing Saint-Venant bump](bump2D1.c)
* [1D arterial flow](artery1D.c)
* [Two- and three-dimensional explosions](explosion.c)

## Incompressible Euler/Navier--Stokes

* [Lid-driven cavity at Re=1000](lid.c)
* [Merging of two vertices](stream.c)
* [Merging of two vortices (centered Euler solver)](vortex.c)
* [Taylor--Green vortices](taylor-green.c)
* [Non-hydrostatic lock-exchange](kh-ns.c)

## Shallow-water flows

* [Drying of a lake](dry.c)
* [Simple Saint-Venant Riemann problem](bore1.c)
* [Oscillations in a parabolic container](parabola.c)
* [Undular bores for the Green-Naghdi equations](bore.c)
* [Green-Naghdi soliton](soliton.c)
* [Solitary wave run-up on a plane beach](beach.c)
* [Solitary wave overtopping a seawall](seawall.c)
* [Sinusoidal wave propagation over a bar](bar.c)
* [Runup of a solitary wave on a conical island](conical.c)
* [Stress test for wetting and drying](ponds.c)
* [Shock reflection by a circular cylinder](shock.c)
* [Flow rates for multiple rivers](multiriverinflow.c)
* [Source of a river](source.c)
* [Implicit Saint-Venant solutions for waves](implicit.c)
* [Viscous hydraulic jump](higuera.c)
* [Transcritical flow over a bump with multiple layers](layered.c)
* [Wind-driven lake](wind-driven-stvt.c)
* [Lake flowing into itself](lake-tr.c)

## Multilayer model

* [Dispersion relation](dispersion.c)
* [Solitary wave run-up on a plane beach](beach-ml.c)
* [Solitary wave overtopping a seawall](seawall.c)
* [Runup of a solitary wave on a conical island](conical.c)
* [Stress test for wetting and drying](ponds-ml.c)
* [Sinusoidal wave propagation over a bar](bar-ml.c)
* [Oscillations in a parabolic container](parabola.c)
* [Circular dam break on a sphere](lonlat-ml.c)
* [Wind-driven lake](wind-driven.c)
* [Large-amplitude standing wave](large.c)
* [Transcritical flow over a bump with multiple layers](gaussian.c)
* [Breaking Stokes wave](stokes.c)
* [Galilean invariance](galilean_invariance.c)
* [Typical (1D) tsunami wave](tsunami.c)

## Coriolis

* [Stommel gyre](stommel-ml.c)
* [Geostrophic adjustment](geo.c)
* [Non-linear geostrophic adjustment](nonlinear.c)

## Stratified multilayer

* [Internal solitary waves](horn.c)
* [Overflow](overflow.c)
* [Lock-exchange](lock.c)
* [Non-hydrostatic lock-exchange](kh.c)

## Volume-Of-Fluid

* [Computation of volume fractions from a levelset function](fractions.c)
* [Computation of volume fractions on a variable-resolution grid](fractions1.c)
* [Fractions in marginal cases](fractions2.c)
* [Computation of a levelset field from a contour](basilisk.c)
* [Time-reversed VOF advection in a vortex](reversed.c)

## Surface tension

* [Curvature of a circular/spherical interface](curvature.c)
* [Circular droplet in equilibrium](spurious.c)
* [Capillary wave](capwave.c)
* [Gravity wave](gravity.c)
* [Shape oscillation of an inviscid droplet](oscillation.c)
* [Rising bubble](rising.c)
* [Sessile drop](sessile.c)
* [3D Sessile drop](sessile3D.c)
* [Marangoni-induced translation due to a temperature gradient](marangoni.c)

## Compressible two-phase flows

* [Shock tube problem for a single ideal gas (strong shock wave)](shockwave.c)
* [Advection of two fluids at different pressures](discontinuity-advection.c)
* [Zero reflection of a wave propagating across an interface between two fluids
   with impedance matching](reflectionperfect.c)
* [Transmission/reflection of a wave propagating across an interface
  between two fluids](reflectiongaussian3.c)
* [Propagation of an acoustic disturbance in a tube](gaussianaxi.c)
* [Small-amplitude oscillations due to surface tension](bubble.c)
* [Small-amplitude spherically-symmetric oscillations due to surface tension](bubble-spherical.c)
* [Rayleigh collapse of a compressible gas bubble](collapse.c)
* [Double Mach reflection of a Mach 10 shock from a wall](inclined-shock.c)
* [Shape oscillation of an inviscid droplet](oscillation.c)

### Compressible two-phase flows with thermal effects

* [Bubble shrinking due to thermal effects](shrinking.c)

## General orthogonal coordinates

* [Circular dam break on a sphere](lonlat.c)
* [Axisymmetric mass conservation](axiadvection.c)
* [Axisymmetric Poiseuille flow](poiseuille-axi.c)
* [Convergence of axisymmetric viscous terms](axi.c)
* [Refinement of axisymmetric metric](refine-axi.c)
* [Boundary layer on a rotating disk](swirl.c)

## Embedded boundaries

* [Poisson equation on complex domains](neumann.c)
* [Poisson equation on complex domains in 3D](neumann3D.c)
* [Poisson equation on complex axisymmetric domains](neumann-axi.c)
* [Stability of the embedded face velocity interpolation](uf.c)
* [Hydrostatic balance with refined embedded boundaries](hydrostatic2.c)
* [Hydrostatic balance with refined embedded boundaries in 3D](hydrostatic3.c)

### Stokes

* [Poiseuille flow in a periodic channel inclined at 45 degrees](poiseuille45.c)
* [Couette flow between rotating cylinders](couette.c)
* [Wannier flow between rotating excentric cylinders](wannier.c)
* [Stokes flow past a periodic array of cylinders](cylinders.c)
* [Stokes flow past a periodic array of spheres](spheres.c)
* [Stokes flow through a complex porous medium](porous.c)
* [Stokes flow through a complex porous medium, randomly refined](porous1.c)

### Navier--Stokes

* [Starting flow around a cylinder](starting.c)

## Electrohydrodynamics

* [Gouy-Chapman Debye layer](debye.c)
* [Electrostatic in planar layers](planar.c)
* [Convergence of axisymmetric EHD stresses](ehd_axi_stress.c)
* [Charge relaxation in an axisymmetric insulated conducting column](cyl_axi.c)
* [Charge relaxation in a planar cross-section](cyl_planar.c)
* [Equilibrium of a droplet suspended in an electric field](taylor.c)

## Viscoelasticity

* [Transient planar Poiseuille flow for 
   an Oldroyd-B or FENE-P fluid](poiseuille-oldroydb.c)
* [Oldroyd-B lid-driven cavity](lid-oldroydb.c)
* [Viscoelastic 2D drop in a Couette Newtonian shear flow](viscodrop.c)
* [Impact of a viscoelastic drop on a solid](fall.c)

## Reaction--Diffusion

* [The SAG equation](sag.c)
* [Soluble gas diffusing from a static bubble](static_bubble.c)
* [Soluble gas diffusing from a rising bubble](axi_rising_bubble.c)

## General Ocean Turbulence Model (GOTM)

* [Turbulent Couette flow](couette-gotm.c)
* [Entrainment](entrainment.c)
* [Ocean Weather Ship Papa](ows_papa.c)

## MPI

* [Reduction operations](mpi-reduce.c)
* [Boundary conditions and restriction](mpi-restriction.c)
* [Z-order indexing](indexing.c)
* [Parallel scalability](mpi-laplacian.c)
* [Parallel refinement](mpi-refine.c)
* [Poisson solver on non-uniform mesh](mpi-circle.c)
* [Boundary conditions for face fluxes](mpi-flux.c)
* [Boundary conditions for face vector fields](mpi-interpu.c)
* [Simple test of Basilisk View](view.c)

## Speed benchmarks

* [Speed of elementary operations on different grids](laplacian.c)
* [Poisson equation](poisson.c)
* [Poisson equation with a circular refined patch](circle.c)

## Basic operations

* [Automatic stencils / boundary conditions](stencils.c)
* [Interpolation on halos](interp.c)
* [Tangential interpolation on face vector fields](interpu.c)
* [Height Functions](hf.c)

## Other

* [Kuramoto--Sivashinsky equation](kuramoto.c)
* [Convergence of the Runge--Kutta solvers](runge-kutta.c)
* [Segment traversal](segment.c)
* [Redistancing of a perturbed distance field](redistance-ellipse.c)

## Unmaintained

The following tests are not maintained anymore.

* [CVMix KPP interface](unmaintained/cvmix.c)

## [All tests](/src/test/)

# Running and creating test cases (and examples)

First make sure to read the [section on
Makefiles](/Tutorial#using-makefiles) in the [tutorial](/Tutorial).

To run a particular test case yourself, you can then just do

~~~bash
cd src/test
make bump2D1.tst
~~~

which should give something like

    ...
    qcc -g -O2 -Wall -o bump2D1/bump2D1 bump2D1.c -lm
    [bump2D1.tst]

This indicates that the test compiled and ran successfully. 

## Error checking

If the test fails, you will get something like

    ...
    > 2.5 434 0.0678117 0.164104 0.11299303
    > # refined 80 cells, coarsened 108 cells
    make: *** [bump2D1.tst] Error 1

The last line indicates that make failed. The lines before this are
the output of

~~~bash
diff bump2D1/log bump2D1.ref
~~~

That is, to check whether the test case succeeded or not, the default
Makefile of Basilisk just compares (using
[*diff*](http://man7.org/linux/man-pages/man1/diff.1.html)) the *log*
file created by the program to the matching reference log file (with
the *.ref* extension).

To create your own test case (let's call it *mytest*), you only need
to create the source code (i.e. *mytest.c*), run it to create the
*mytest/log* file, check that you are happy with the results and copy
*mytest/log* into *mytest.ref*.

## Graphics

Most tests (but not all) also produce some kind of graph summarising
the results (which allows for example to understand more easily
how/why a particular test failed). Some tests produce these graphs
directly when they run, but most rely on *gnuplot* to generate the
graphs in a post-processing step.

This step is not automatically executed when doing *make
test.tst*. This allows for example to run the test suite on *bare
bones* systems which do not have gnuplot installed.

The makefile system knows about two kinds of graphics: *"inline" plots*
and *"offline" plots*.

### Inline plots

These are generated using gnuplot or python commands embedded directly
in the documentation comments of the source code (*mytest.c*). Using
the standard wiki syntax for scripts these commands appear as

    ~~~gnuplot Caption
    ...
    ~~~

    ~~~pythonplot Caption
    import matplotlib.pyplot as plt
    ...
    plt.savefig('plot.png')
    ~~~

and are replaced by the corresponding figure when the page is displayed
in the wiki.

To generate the figures from the command line, just do

~~~bash
make mytest/plots
~~~

### Offline plots

Alternatively, one can put the gnuplot commands in a separate 
*mytest.plot* file. Note that this method offers few advantages
compared to "inline plots" (the prefered option).

To generate the corresponding plots, one can then do

~~~bash
make bump2D1/plot.png
~~~

which should give something like

    cd bump2D1 && gnuplot -e "batch=1; PNG=\"pngcairo\" ... ../bump2D1.plot ...

Note that, while *plot.png* is the default name for the generated
graph, the gnuplot script can also generate other graphs. Doing

~~~bash
ls bump2D1/*.png
~~~

(or *`eog bump2D1/*.png`*) reveal them all.

Note that if you try to generate plots for a test case which does not
have a corresponding *.plot* gnuplot script, you will get something
like

~~~bash
make events/plot.png
make: *** No rule to make target `events/plot.png'.  Stop.
~~~

## Running the entire test suite

Use something like

~~~bash
cd src/test/
make -k -j8
~~~

where *-k* tells *make* not to stop at the first error and *-j8* uses
parallel processing (assuming you have at least 8 cores on your
system).

## Testing dimensional analysis

[Dimensional analysis](/src/ast/interpreter/dimension.c) can be tested
using reference files with a `.dims.ref` extension. The default
Makefile will then compile the corresponding `.c` file using the
`-dimensions` option to generate a `.dims` file which will be compared
(using `diff`) to the reference file.

A simple way to generate a new reference file for e.g. `test.c` is to do

~~~bash
touch test.dims.ref
make test.s
~~~

The `make test.s` command will fail (since the reference file is empty)
and one can then copy the generated `.dims` file as the new reference
file (after checking that it is correct!) i.e.

~~~bash
cp test.dims test.dims.ref
~~~