diff --git a/README.rst b/README.rst index d93f3dd3..01654709 100644 --- a/README.rst +++ b/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: diff --git a/docs/source/user_libs_opt_taguchi.rst b/docs/source/user_libs_opt_taguchi.rst index 04f4144a..b4c9b13b 100644 --- a/docs/source/user_libs_opt_taguchi.rst +++ b/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 ------- \ No newline at end of file