Updated info on Taguchi optimisation.

README.rst

@@ -125,11 +125,12 @@ Optional command line arguments
 
 There are optional command line arguments for gprMax:
 
-* ``--geometry-only`` will build a model and produce any geometry views but will not run the simulation. This option is useful for checking the geometry of the model is correct.
-* ``-n`` is used along with a integer number to specify the number of times to run the input file. This option can be used to run a series of models, e.g. to create a B-scan that uses an antenna model.
-* ``-mpi`` is a flag to turn on Message Passing Interface (MPI) task farm functionality. This option is most usefully combined with ``-n`` to allow individual models to be farmed out using MPI. For further details see the Parallel performance section (http://docs.gprmax.com/en/latest/openmp_mpi.html).
+* ``-n`` is used along with a integer number to specify the number of times to run the input file. This option can be used to run a series of models, e.g. to create a B-scan.
+* ``-mpi`` is a flag to turn on Message Passing Interface (MPI) task farm functionality. This option is most usefully combined with ``-n`` to allow individual models to be farmed out using MPI. For further details see the Parallel performance section (http://docs.gprmax.com/en/latest/openmp_mpi.html)
 * ``-benchmark`` is a flag to turn on benchmarking mode. This can be used to benchmark the threading (parallel) performance of gprMax on different hardware. For further details see the benchmarking section (http://docs.gprmax.com/en/latest/benchmarking.html)
-* ``--write-processed`` will write an input file after any Python code and include commands in the original input file have been processed
+* ``--geometry-only`` will build a model and produce any geometry views but will not run the simulation. This option is useful for checking the geometry of the model is correct.
+*``--optimisation-taguchi`` will run a series of simulations using a optimisation process based on Taguchi's method. For further details see the user libraries section (http://docs.gprmax.com/en/latest/user_libs_opt_taguchi.html)
+* ``--write-processed`` will write an input file after any Python code and include commands in the original input file have been processed.
 * ``-h`` or ``--help`` can be used to get help on command line options.
 
 For example, to check the geometry of a model:

docs/source/user_libs_opt_taguchi.rst

@@ -36,12 +36,7 @@ Taguchi's method is based on the concept of the Orthogonal Array (OA) and has th
 * Global optimum results
 * Independence from initial values of optimisation parameters
 
-Details of Taguchi's method in the context of electromagnetics can be found in [WEN2007a]_ and [WEN2007b]_. The process by which Taguchi's method optimises parameters is illustrated in the following figure.
-
-.. figure:: images/taguchi_process.png
-    :width: 300 px
-
-    Process associated with Taguchi's method.
+Details of Taguchi's method in the context of electromagnetics can be found in [WEN2007a]_ and [WEN2007b]_.
 
 
 Package overview
@@ -58,24 +53,40 @@ Package overview
 * `optimisation_taguchi_fitness.py` is a module containing fitness functions. There are some pre-built ones but users should add their own here.
 * `optimisation_taguchi_plot.py` is a module for plotting the results, such as parameter values and convergence history, from an optimisation process when it has completed.
 
+Implementation
+--------------
 
-Parameters to optimise
-----------------------
+The process by which Taguchi's method optimises parameters is illustrated in the following figure.
 
-The module will select from 2 pre-built OAs (http://neilsloane.com/oadir/) depending on the number of parameters to optimise. Currently, up to 7 independent parameters can be optimised, although a method to construct OAs of any size is under testing.
+.. figure:: images/taguchi_process.png
+    :width: 300 px
 
+    Process associated with Taguchi's method.
 
-Fitness functions
------------------
+In stage 1a, one of the 2 pre-built OAs will automatically be chosen depending on the number of parameters to optimise. Currently, up to 7 independent parameters can be optimised, although a method to construct OAs of any size is under testing.
 
-A fitness function is required to set a goal against which to compare results from the optimisation process. A number of pre-built fitness functions can be found in the `optimisation_taguchi_fitness.py` module, such as `minvalue`, `maxvalue` and `xcorr`. Users can easily add their own fitness functions to this module. All fitness functions must take two arguments and return a single fitness value which will be maximised. The arguments must be:
+In stage 1b, a fitness function is required to set a goal against which to compare results from the optimisation process. A number of pre-built fitness functions can be found in the `optimisation_taguchi_fitness.py` module, e.g. `minvalue`, `maxvalue` and `xcorr`. Users can also easily add their own fitness functions to this module. All fitness functions must take two arguments:
 
 * `filename` a string containing the full path and filename of the output file
 * `args` a dictionary which can contain any number of additional arguments for the function, e.g. names (IDs) of outputs (rxs) from input file
 
+Additionally all fitness functions must return a single fitness value which the optimsation process will aim to maximise.
+
+Stages 2-6 are iterated by the optimisation process.
+
+Parameters and settings for the optimisation process are specified within a special Python block defined by `#taguchi` and `#end_taguchi` in the input file. The parameters to optimise must be defined in a dictionary named `optparams` and their initial ranges specified as lists with lower and upper values. The fitness function, it's parameters, and a stopping value are defined in dictionary named `fitness` which has keys for:
+
+* `name`, a string that is the name of the fitness function to be used.
+* `args`, a dictionary containing arguments to be passed to the fitness function. Within `args` there must be a key called `outputs` which contains a string or list of the names of one or more outputs in the model.
+* `stop`, a value which when exceeded the optimisation should stop.
+
+Optionally a variable called `maxiterations` maybe specified within the `#taguchi` block which will set a maximum number of iterations after which the optimisation process will terminate irrespective of any other criteria.
+
 
 How to use the package
 ======================
 
+The package requires `#python` and `#end_python` to be used in the input file, as well as `#taguchi` and `#end_taguchi` for specifying parameters and setting for the optimisation process. A Taguchi optimisation is run using the command line option `--optimisation-taguchi`.
+
 Example
 -------