Updates to text.

docs/source/user_libs_opt_taguchi.rst

@@ -58,7 +58,7 @@ Package overview
 Implementation
 --------------
 
-The process by which Taguchi's method optimises parameters is illustrated in the following figure.
+The process by which Taguchi's method optimises parameters is illustrated in the following figure:
 
 .. figure:: images/user_libs/taguchi_process.png
     :width: 300 px
@@ -70,19 +70,19 @@ In stage 1a, one of the 2 pre-built OAs will automatically be chosen depending o
 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 ``fitness_functions.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
+* ``args`` a dictionary which can contain any number of additional arguments for the function, e.g. names of outputs (rxs) in the model
 
-Additionally all fitness functions must return a single fitness value which the optimsation process will aim to maximise.
+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.
+Stages 2-6 are iterated through 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:
+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.
+* ``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 (rxs) in the model
+* ``stop`` a value from the fitness function which when exceeded the optimisation should stop
 
-Optionally a variable called ``maxiterations`` maybe specified within the ``#taguchi``/``#end_taguchi`` block which will set a maximum number of iterations after which the optimisation process will terminate irrespective of any other criteria.
+Optionally a variable called ``maxiterations`` maybe specified which will set a maximum number of iterations after which the optimisation process will terminate irrespective of any other criteria. If it is not specified it defaults to a maximum of 20 iterations.
 
 
 How to use the package
@@ -101,20 +101,20 @@ The package requires ``#python`` and ``#end_python`` to be used in the input fil
 Example
 -------
 
-The following example demonstrates using the Taguchi optimisation process to optimise values of loading resistors used in a bowtie antenna. The example is slighty contrived as the goal is simply to find values for the resistors that produce a maximal amplitude response from the antenna. We already know this should occur when the values of the resistors are at a minimum. Nevertheless, it is useful to illustrate the optimisation process and how to use it.
+The following example demonstrates using the Taguchi optimisation process to optimise values of loading resistors used in a bowtie antenna. The example is slighty contrived as the goal is simply to find values for the resistors that produces a maximum absolute amplitude in the response from the antenna. We already know this should occur when the values of the resistors are at a minimum. Nevertheless, it is useful to illustrate the optimisation process and how to use it.
 
 .. figure:: images/user_libs/antenna_bowtie_opt.png
     :width: 600 px
 
     FDTD geometry mesh showing bowtie antenna with slots and loading resistors.
 
-The bowtie design features 3 vertical slots (y-direction) in each arm of the bowtie. Each slot has different loading resistors, but within each slot there are 4 resistors of the same value. A resistor is modelled as two parallel edges of a cell. The bowtie is placed on a lossless substrate of relative perimittivity 4.8. The antenna is modelled free space, and an output point (the electric field value) is specified at a distance of 60mm from the feed of the bowtie (red coloured cell).
+The bowtie design features 3 vertical slots (y-direction) in each arm of the bowtie. Each slot has different loading resistors, but within each slot there are 4 resistors of the same value. A resistor is modelled as two parallel edges of a cell. The bowtie is placed on a lossless substrate of relative permittivity 4.8. The antenna is modelled in free space, and an output point of the electric field (named ``Ex60mm``) is specified at a distance of 60mm from the feed of the bowtie (red coloured cell).
 
 .. literalinclude:: ../../user_libs/optimisation_taguchi/antenna_bowtie_opt.in
     :language: none
     :linenos:
 
-The first part of the input file (lines 1-7) contains the parameters to optimise, their initial ranges, and fitness function information for the optimisation process. Three parameters representing the resistor values are defined with ranges between 0.1 :math:`\Omega` and 5 :math:`k\Omega`. A pre-built fitness function called ``maxvalue`` is specified with a stopping criterion of 50V/m. The output point in the model that will be used in the optimisation is specified as having the name ``Ex60mm``. Finally, a limit of 5 iterations is placed on the optimisation process, i.e. it will stop after 5 iterations irrespectively of whether it has reached the target of 50V/m.
+The first part of the input file (lines 1-7) contains the parameters to optimise, their initial ranges, and fitness function information for the optimisation process. Three parameters representing the resistor values are defined with ranges between 0.1 :math:`\Omega` and 5 :math:`k\Omega`. A pre-built fitness function called ``maxabsvalue`` is specified with a stopping criterion of 50V/m. The output point in the model that will be used in the optimisation is specified as having the name ``Ex60mm``. Finally, a limit of 5 iterations is placed on the optimisation process, i.e. it will stop after 5 iterations irrespectively of whether it has reached the target of 50V/m.
 
 The next part of the input file (lines 9-93) contains the model. For the most part there is nothing special about the way the model is defined - a mixture of Python, NumPy and functional forms of the input commands (available by importing the module ``input_cmd_funcs``) are used. However, it is worth pointing out how the values of the parameters to optimise are accessed. On line 29 a NumPy array of the values of the resistors is created. The values are accessed using their names as keys to the ``optparams`` dictionary. On line 30 the values of the resistors are converted to conductivities, which are used to create new materials (line 34-35). The resistors are then built by applying the materials to cell edges (e.g. lines 55-62). The output point in the model in specifed with the name ``Ex60mm`` and as having only an ``Ex`` field output (line 42).