Add example config file and docs, remove old one

A version of the new aronnax.conf file has been added to the base directory of the repo. This config file includes all of the paramters and inputs that can be specified as well as comments describing them. This partially completes #103. The documenation page `running_aronnax` ingests this config file and displays it, along with its comments and some additional descriptive text.

Author: edoddridge

aronnax.conf

@@ -0,0 +1,135 @@
+# Aronnax configuration file. Change the values, but not the names.
+
+#------------------------------------------------------------------------------
+# au is the lateral friction coefficient in m^2 / s
+# ah is thickness diffusivity in m^2 / s
+# ar is linear drag between layers in 1/s
+# dt is time step in seconds
+# slip is free-slip (=0), no-slip (=1), or partial slip (something in between)
+# nTimeSteps: number of timesteps before stopping
+# dumpFreq: time between snapshot outputs in seconds
+# avFreq: time between averaged output in seconds
+# hmin: minimum layer thickness allowed by model (for stability) in metres
+# maxits: maximum iterations for the pressure solver algorithm. Should probably
+#   be at least max(nx,ny), and possibly nx*ny
+# eps: convergence tolerance for pressure solver. Algorithm stops when error is 
+#   less than eps*initial_error
+# freesurfFac: 1. = linear implicit free surface, 0. = rigid lid.
+# botDrag is the linear bottom friction in 1/s
+# thickness_error is the  discrepancy between the summed layer thicknesses and 
+#   the depth above which the model emits a warning. 1e-2 is a 1% discrepancy.
+
+[numerics]
+au = 500.
+ah = 0.0
+ar = 0.0
+dt = 600.
+slip = 0.0
+nTimeSteps = 502
+dumpFreq = 1.2e5
+avFreq = 1.2e5
+hmin = 100
+maxits = 1000
+eps = 1e-5
+freesurfFac = 0.
+botDrag = 1e-6
+thickness_error = 1e-2
+#------------------------------------------------------------------------------
+
+# RedGrav selects whether to use n+1/2 layer physics (RedGrav=yes), or n-layer 
+#   physics with an ocean floor (RedGrav=no)
+# depthFile defines the depth of the ocean bottom below the sea surface in metres.
+# hmean is a list of initial thicknesses for the layers in metres. Each value is 
+#   separated by a comma. This input was a useful short cut for specifying 
+#   initial conditions with constant layer thicknesses, but has been superseded 
+#   and may be removed in the future.
+# H0 is the depth of the ocean basin and is only required in n-layer mode. This 
+#   input was a useful short cut for specifying a flat bottomed ocean, but has 
+#   been superseded and may be removed in the future.
+
+[model]
+RedGrav = no
+depthFile
+hmean = 400.,1600.
+H0 = 2000.
+#------------------------------------------------------------------------------
+
+# these variables set the number of processors to use in each direction. 
+#   Currently the model only runs on one processor, so nProcX and nProcY must 
+#   be set to 1
+
+[pressure_solver]
+nProcX = 1
+nProcY = 1
+#------------------------------------------------------------------------------
+
+# g_vec is the reduced gravity at interfaces in m/s^2. g_vec must have as many 
+#   entries as there are layers. The values are given by the delta_rho*g/rho_0. 
+#   In n-layer mode the first entry applies to the surface, i.e. the top of the 
+#   upper layer. In n+1/2 layer mode the first entry applies to the bottom of 
+#   the upper layer.
+# rho0 is the reference density in kg/m^3, as required by the Boussinesq assumption.
+
+[physics]
+g_vec = 9.8, 0.01
+rho0 = 1035.
+#------------------------------------------------------------------------------
+
+# nx is the number of grid points in the x direction
+# ny is the number of grid points in the y direction
+# layers is the number of active layers
+# dx is the x grid spacing in metres
+# dy is the y grid spacing in metres
+# fUfile defines the Coriolis parameter on the u grid points
+# fVfile defines the Coriolis parameter on the v grid points
+# wetMaskFile defines the computational domain - which grid points are ocean and
+#   which are land
+
+[grid]
+nx = 10
+ny = 10
+layers = 2
+dx = 2e4
+dy = 2e4
+fUfile = :beta_plane_f_u:1e-5,2e-11
+fVfile = :beta_plane_f_v:1e-5,2e-11
+wetMaskFile = :rectangular_pool:
+#------------------------------------------------------------------------------
+
+# These files define the values towards which the model variables are relaxed 
+#   (in metres or m/s), and the timescale for the relaxation, in 1/s.
+[sponge]
+spongeHTimeScaleFile
+spongeUTimeScaleFile
+spongeVTimeScaleFile
+spongeHFile
+spongeUfile
+spongeVfile
+
+#------------------------------------------------------------------------------
+
+# These files define the initial values used in the simulation. If no values are
+#   defined for the velocities (in m/s) or the free surface elevation (in m), 
+#   they will be initialised with zeros. Layer thickness (in m) must be initialised, 
+#   either by passing a file, or using the generator functions.
+
+[initial_conditions]
+initUfile
+initVfile
+initHfile
+initEtaFile
+
+#------------------------------------------------------------------------------
+
+# The wind files define the momentum forcing in N/m^2
+# wind_mag_time_series_file defines the constant factor by which the wind is 
+#   multiplied by at each timestep.
+# DumpWind defines whether the model outputs the wind field when it outputs other 
+#   variables (at the rate controlled by DumpFreq).
+
+[external_forcing]
+zonalWindFile = 'input/wind_x.bin'
+meridionalWindFile = 'input/wind_y.bin'
+wind_mag_time_series_file
+DumpWind = no
+#------------------------------------------------------------------------------

docs/running_aronnax.rst

@@ -20,4 +20,20 @@ As described above, it is possible to define functions that can be passed to `ar
                        nx=10, ny=10, exe="aronnax_test", dx=xlen/10, dy=ylen/10)
 
 .. warning::
-    Running Aronnax in a directory that contains outputs from a previous simulation will result in those outputs being overwritten. The model does not currently check if the intended outputs directory is empty.
+    Running Aronnax in a directory that contains outputs from a previous simulation will result in those outputs being overwritten. The model does not currently check if the  output directory is empty.
+
+
+Parameters
+===========
+Parameters can be passed to the model in two ways. Either they can be included in a file called `aronnax.conf` in the working directory, or they can be passed as keyword arguments to :meth:`aronnax.driver.simulate`. The main directory of the repository includes an example `aronnax.conf` file.
+
+.. note::
+    Aronnax takes a deliberately strict approach towards specifying parameter choices. The model contains very few default values, except in situations where a default of zero can sensibly be applied. As such, you will need to specify your parameter choices, either through the configuration file, or the function call. However, parameters that are not required, for example, bottom drag in n+1/2 layer mode, need not be set.
+
+The example file is reproduced here with comments describing the parameters and their units. All possible parameters are included, but they are not all assigned values. After modifying this file for your simulation, any unassigned parameters should be deleted.
+
+.. include:: ../aronnax.conf
+   :literal:
+
+.. warning::
+    The configuration file shown above includes all of the possible input parameters and fields since it forms part of the documentation. IT WILL NOT WORK AS IS. To use it in an actual simulation the file will need to be modified either by giving values to the parameters that are currently unspecified, or deleting them from the file. If you wish to see a configuration file that corresponds to a successful simulation, look in any of the test, benchmark, or reproduction directories.