fixes #39

Adds a mechanism to provide help messages/descriptions for ALL
parameters of command line Python scripts.
Along the `_base.parameters`, we now have `_base.parameter_description`
which is a parallel dictionary.
A similar mechanism should be added for alternative parameter sources in
children of `DNS` etc.

TurTLE/DNS.py

@@ -113,27 +113,49 @@ class DNS(_code):
     def generate_default_parameters(self):
         # these parameters are relevant for all DNS classes
         self.parameters['fftw_plan_rigor'] = 'FFTW_ESTIMATE'
+        self.parameter_description['fftw_plan_rigor'] = 'FFTW plan rigor to use. One of `FFTW_ESTIMATE`, `FFTW_MEASURE`, `FFTW_PATIENT`. Please see FFTW documentation.'
         self.parameters['dealias_type'] = int(1)
+        self.parameter_description['dealias_type'] = 'Dealiasing mehtod to use, integer. Options are: two-thirds (0) or smooth (1).'
         self.parameters['dkx'] = float(1.0)
+        self.parameter_description['dkx'] = 'Smallest wavenumber in the x direction for a pseudo-spectral run.'
         self.parameters['dky'] = float(1.0)
+        self.parameter_description['dky'] = 'Smallest wavenumber in the y direction for a pseudo-spectral run.'
         self.parameters['dkz'] = float(1.0)
+        self.parameter_description['dkz'] = 'Smallest wavenumber in the z direction for a pseudo-spectral run.'
         self.parameters['niter_todo'] = int(8)
+        self.parameter_description['niter_todo'] = 'Number of iterations to compute during a single run.'
         self.parameters['niter_stat'] = int(1)
+        self.parameter_description['niter_stat'] = 'Interval (in iterations) over which to compute field statistics (i.e. call `do_stats`).'
         self.parameters['niter_out'] = int(8)
+        self.parameter_description['niter_out'] = 'Output is performed every `NITER_OUT` iterations.'
         self.parameters['checkpoints_per_file'] = int(1)
+        self.parameter_description['checkpoints_per_file'] = 'Number of checkpoints to store in a single checkpoint file. Rule of thumb: files should hold gigabytes of data, rather than megabytes.'
         self.parameters['dt'] = float(0.01)
+        self.parameter_description['dt'] = 'Fixed timestep to use. It is strongly recommended not to change this value in between jobs.'
         self.parameters['nu'] = float(0.1)
+        self.parameter_description['nu'] = 'Viscosity value used in the equations, given in code units.'
         self.parameters['fmode'] = int(1)
+        self.parameter_description['fmode'] = 'Forcing parameter: mode to use for the Kolmogorov forcing.'
         self.parameters['famplitude'] = float(0.5)
+        self.parameter_description['famplitude'] = 'Forcing parameter: amplitude of Kolmogorov forcing, in code units.'
         self.parameters['friction_coefficient'] = float(0.5)
+        self.parameter_description['friction_coefficient'] = 'Forcing parameter: drag coefficient, in code units.'
         self.parameters['energy'] = float(0.5)
+        self.parameter_description['energy'] = 'Forcing parameter: if fluid is forced by enforcing a constant energy, this is the value (in code units).'
         self.parameters['injection_rate'] = float(0.4)
+        self.parameter_description['injection_rate'] = 'Forcing parameter: if a fixed energy injection rate is used, this is the value (in code units).'
         self.parameters['fk0'] = float(2.0)
+        self.parameter_description['fk0'] = 'Forcing parameter: if forcing acts on wavenumber band, this is the smallest wavenumber where it acts (in code units).'
         self.parameters['fk1'] = float(4.0)
+        self.parameter_description['fk1'] = 'Forcing parameter: if forcing acts on wavenumber band, this is the largest wavenumber where it acts (in code units).'
         self.parameters['forcing_type'] = 'fixed_energy_injection_rate'
+        self.parameter_description['forcing_type'] = 'Forcing parameter: what type of force to use.'
         self.parameters['histogram_bins'] = int(256)
+        self.parameter_description['histogram_bins'] = 'During statistics, histograms of real-valued fields are computed using a number of `HISTOGRAM_BINS` bins.'
         self.parameters['max_velocity_estimate'] = float(1)
+        self.parameter_description['max_velocity_estimate'] = 'During statistics, velocity histogram bins are computed using this estimate (see code for details).'
         self.parameters['max_vorticity_estimate'] = float(1)
+        self.parameter_description['max_velocity_estimate'] = 'During statistics, vorticity histogram bins are computed using this estimate (see code for details).'
         # parameters specific to particle version
         self.NSVEp_extra_parameters = {}
         self.NSVEp_extra_parameters['niter_part'] = int(1)

TurTLE/_base.py

@@ -42,6 +42,11 @@ class _base(object):
         self.parameters = {'nx' : 32,
                            'ny' : 32,
                            'nz' : 32}
+        self.parameter_description = {
+                'nx' : 'Number of real-space grid nodes in the x direction.',
+                'ny' : 'Number of real-space grid nodes in the y direction.',
+                'nz' : 'Number of real-space grid nodes in the z direction.',
+                }
         self.string_length = 512
         self.work_dir = os.path.realpath(work_dir)
         self.simname = simname
@@ -329,14 +334,22 @@ class _base(object):
     def parameters_to_parser_arguments(
             self,
             parser,
-            parameters = None):
+            parameters = None,
+            parameter_description = None):
         if type(parameters) == type(None):
             parameters = self.parameters
+        if type(parameter_description) == type(None):
+            parameter_description = self.parameter_description
         for k in sorted(parameters.keys()):
+            if k in parameter_description.keys():
+                description = parameter_description[k]
+            else:
+                description = 'No description available.'
             parser.add_argument(
                     '--{0}'.format(k),
                     type = type(parameters[k]),
                     dest = k,
+                    help = description,
                     default = None)
         return None