diff --git a/docs/source/images/user_libs/taguchi_fitness_hist.png b/docs/source/images/user_libs/taguchi_fitness_hist.png new file mode 100644 index 00000000..d306c175 Binary files /dev/null and b/docs/source/images/user_libs/taguchi_fitness_hist.png differ diff --git a/docs/source/images/user_libs/taguchi_parameter_hist.png b/docs/source/images/user_libs/taguchi_parameter_hist.png new file mode 100644 index 00000000..f3725701 Binary files /dev/null and b/docs/source/images/user_libs/taguchi_parameter_hist.png differ diff --git a/docs/source/user_libs_opt_taguchi.rst b/docs/source/user_libs_opt_taguchi.rst index f069ec58..ac166f31 100644 --- a/docs/source/user_libs_opt_taguchi.rst +++ b/docs/source/user_libs_opt_taguchi.rst @@ -24,6 +24,14 @@ Information The package features an optimisation technique based on Taguchi's method. It allows users to define parameters in an input file and optimise their values based on a fitness function, for example it can be used to optimise material properties or geometry in a simulation. +.. warning:: + + This package combines a number of advanced features and should not be used without knowledge and familiarity of the underlying techniques. It requires: + + * Knowledge of Python to contruct a model input file to use with the optimisation + * Understanding of optimisation techniques in general, and in particular Taguchi's method + * Care and 'sanity' checking to be made throughout the process + Taguchi's method ---------------- @@ -84,20 +92,14 @@ Parameters and settings for the optimisation process are specified within a spec 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. +There is also a builtin criterion to terminate the optimisation process is successive fitness values are within 0.1% of one another. + 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 ``--opt-taguchi``. -.. note:: - - A couple of warnings before using this package: - - * It requires a basic knowledge of Python to use the optimisation process and construct models. - * It combines a number of advanced features which must be used carefully, and sanity checks made throughout the process. - - Example ------- @@ -114,7 +116,7 @@ The bowtie design features 3 vertical slots (y-direction) in each arm of the bow :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 ``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 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 1 :math:`k\Omega`. A pre-built fitness function called ``maxabsvalue`` is specified with a stopping criterion of 10V/m. The output point in the model that will be used in the optimisation is specified as having the name ``Ex60mm``. 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). @@ -131,4 +133,26 @@ When the optimisation has completed a summary will be printed showing histories .. code-block:: none - python -m user_libs.optimisation_taguchi.plot_results antenna_bowtie_opt_hist.pickle + python -m user_libs.optimisation_taguchi.plot_results user_libs/optimisation_taguchi/antenna_bowtie_opt_hist.pickle + +.. code-block:: none + + Optimisations summary for: antenna_bowtie_opt_hist.pickle + Number of iterations: 4 + History of fitness values: [4.2720928, 5.68856, 5.7023263, 5.7023263] + History of parameter values: + resinner [250.07498, 0.87031555, 0.1, 0.1] + resmiddle [250.07498, 0.87031555, 0.1, 0.1] + resouter [250.07498, 0.87031555, 0.1, 0.1] + +.. figure:: images/user_libs/taguchi_fitness_hist.png + :width: 300 px + + History of fitness (``maxabsvalue``) value. + +.. figure:: images/user_libs/taguchi_parameter_hist.png + :width: 300 px + + History of values of parameters, ``resinner``, ``resmiddle``, and ``resouter``. + +The optimisation process terminated because succcessive fitness values were within 0.1% of one another.