.. _method_options:

METHOD_OPTIONS
###############

This details the methods to be used in the script and is a required section. 

.. _method_options_fit_example:

Example METHOD_OPTIONS from a Fit Script
==========================================

.. code-block:: pyml

    METHOD_OPTIONS:
        # Python module required to process this script file
        py_module: fit

        # Option to set seed to make run result
        # reproducible -e.g. when debugging.
        # rand_seed: 12345
        rand_seed: auto

        # Format string for numerical output
        float_format: default

.. _method_options_main_fields:
        
Main METHOD_OPTIONS Fields
=============================

.. _method_options_pymodule_spec:

py_module
----------

When calling this script using :ref:`popy_run`, |popy| needs to know which :ref:`type of script<script_formats>` is being called. This is determined by the 'py_module' field. 

In the example above a 'fit' script is specified. Other possible entries are 'fit', 'tut', 'gen', 'mtut' etc. See :ref:`script_formats` for more information.    
    
.. _method_options_randseed_spec:

rand_seed
-----------

There are two types of scripts run by |popy|:-

* Deterministic - given the same inputs the same outputs are **always** returned
* Stochastic -  given the same inputs the result are dependent on a random number generator

For example a :ref:`gen_script` is inherently stochastic. Whereas a :ref:`fit_script` using the 'JOE' fitting method is inherently deterministic.  

When running a stochastic method you have two options, this setting:-

.. code-block:: pyml

    rand_seed: auto

Will ensure that the random number generator is seeded with a different random number, every time the script is run. This will generate different output each time. Alternatively you set the seed explicitly:-

.. code-block:: pyml

    rand_seed: 314159
    
This will initialise the pseudorandom number generator with the value '314159', which will then generate the same output every time, given the same inputs. For more information on seeding and pseudorandom number generators, see Wikipedia page:- 

http://en.wikipedia.org/wiki/Random_seed

Note: if your script is deterministic then the 'rand_seed' setting will have no effect.


.. _method_options_float_format_spec:

float_format
--------------

This field allows you to control how numbers output by |popy| are rendered as strings. If you leave this field out it defaults to:-

.. code-block:: pyml

    float_format: default
    
This has the effect of outputting float values to 4 decimal places. :numref:`table_float_format_options` shows both named float formats.
    
.. _table_float_format_options:

.. list-table:: float format options
    :header-rows: 1
    
    * - Entry
      - Format String
      - Example Input
      - Example Output

    * - default 
      - .4F
      - 1.0123456
      - '1.0123'
            
    * - 2 decimal places in exponent format 
      - .2E
      - 1.0123456
      - '1.01E+00'
    
You can also specify your own custom format, |eg| '.3G' for 3 significant figures in general format or '.6F' for 6 decimal places in float point format or '.4E' for 4 decimal places in exponent format. Examples of different format strings on the |python| command prompt are:-
    
.. code-block:: pycon
    
    >>> '{:.4E}'.format(1.0123456)
    '1.0123E+00'
    >>> '{:.6F}'.format(1.0123456)
    '1.012346'
    >>> '{:.3G}'.format(1.0123456)
    '1.01'

You can experiment with your own formatting. See the rather esoteric instructions here:-
    
https://docs.python.org/3.4/library/string.html#format-specification-mini-language

Setting the output to six decimal places in |popy| could be achieved by:- 

.. code-block:: pyml

    float_format: .6F

Note that |popy| adds the prefix '{:' and the suffix '}' to your 'float_format' config file entry.
