.. index:: configuration

.. _config:

=============================
FMS experiments configuration
=============================

FMS needs a detailed description of an experiment before being able able to run
it. The experiment configuration file contains this description.

.. index::
    pair: configuration file; name of

The experiment configuration file name might be whatever you want (provided your
operating system allows it) but should have an '.yml' extension for FMS to know
how to parse it (other formats such as XML exist for compatibility reasons, even
if their use is discouraged).

This file is written in the YAML_ format, which is hopefully rather easy to
read and write. A minimal configuration file should contain three items with
their required parameters: world, engines/markets, agents.

.. _YAML: http://www.yaml.org/

.. index::
    pair: configuration file; syntax

Configuration file syntax
=========================

Configuration files are provided in the ``examples`` directory, which is located
in the main documentation directory [1]_. It is strongly recommanded to study
those before writing your own (see `examples provided`_ below).

.. index::
    pair: configuration file; example

A minimal configuration file might be::

    --- # Experiment

    world:
          classname: NullWorld

    engines:
        - classname: AsynchronousRandWReplace
          market:
              classname: ContinuousOrderDriven

    agents:
        - classname: ZeroIntelligenceTrader
          number: 1000
          money: 5000
          stocks: 1000

Classnames coming from the ``fms/contrib`` directory should be prefixed with the
name of the directory in which they are grouped (usually the contributor name).
For an example, an *AgentSmith* agent class contributed by The Matrix would be available 
in the ``fms/contrib/atrix/agents/agentsmith.py`` module and would be referenced
as ``matrix.AgentSmith`` in a configuration file. See the ``exp01b.yml`` file in
the ``examples`` directory for an example of contributed class use.

An FMS YAML configuration file should contain one and only one YAML *document*,
i.e. only one section delimited by ``---``. The parameters it describes are as
follows:  

.. index::
    pair: outputfilename; parameter
    pair: transaction; filename
    pair: output; filename

.. _outputfilename:

outputfilename 
    Name of (and optional path to) transactions output file (optional)

    The name of the file to which the transactions resulting from the experiment
    should be output. This file is a comma separated values one, suitable for
    use in whatever processing you need afterwards. The transactions are output
    to the console if this parameter is missing.

    If a relative path or no path is given with the file name, the file location
    will be relative to the experiment configuration file directory. Suppose the
    configuration file contains::

        outputfilename: myexperiments/exp01output.csv

    If the current directory is ``/home/mydir`` and you start fms using the
    command::

        ~$ python startfms.py run fmsdata/exp01config.yml

    Then the resulting transactions will be output to
    ``/home/mydir/fmsdata/myexperiments/exp01output.csv`` 

.. index::
    pair: orderslogfilename; parameter
    pair: filename; orders

orderslogfilename
    Name of (and optional path to) order log file (optional)

    The name of the file to which the different orders generated by the agents
    are saved in a chronological manner. This file is a comma separated values
    one, and is necessary to replay an experiment, for an example. If this
    parameter is missing, the orders are not saved.

    If a relative path or no path is given with the file name, the file location
    will be relative to the experiment configuration file directory. See
    :ref:`outputfilename <outputfilename>` above for an example.

.. index:: 
    pair: repeat; parameter
    pair: experiment; repeat

repeat
    Number of times the experiment should be repeated (optional, default 1)

    If an experiment is repeated, a sequence number is appended to the first
    part of the the output file names (transactions or orders) as a ``-%03d``
    string. Thus, if the output filename is `myoutput.csv` and the experiment is
    repeated twice, it will result in two output files, named `myoutput-001.csv`
    and `myoutput-002.csv`.

.. index:: 
    pair: randomseed; parameter

randomseed
    Seed of the pseudo-ramdom numbers generator (optional)

    As some agents take random decisions, and some engines randomly choose the
    agents allowed to speak, a random generator is sometimes needed. FMS uses
    Python's random library, which uses the Mersenne Twister as the core
    generator (see http://docs.python.org/library/random.html for more about
    this).  As this library accepts an optional seed parameter, you may specify
    it here.

.. index:: 
    single: comma separated value
    pair: delimiter; csv file
    pair: csvdelimiter; parameter

csvdelimiter
    Delimiter used in the comma separated value files (optional)

    The field delimiter in the various csv output files. This is optional, as
    the default value is semicolon ``;`` and is automatically accepted by most
    spreadsheets. Accepted values are semicolon ``;``, comma ``,``, tab, space,
    colon ``:``, pipe ``|``, dash ``-``, exclamation mark ``!``, slash ``/``.  

.. index:: 
    pair: unique_by_agent; parameter
    pair: agent; order

unique_by_agent
    Should orders in books be unique per agent ? (optional, default ``True``)

    If this parameter is ``True`` or missing, any order placed by an agent
    replaces any previous order from the same agent.

.. index:: 
    pair: show_books; parameter
    pair: display; books

show_books
    Should FMS show 5 best limits of order books on each step ? (optional, default
    ``False``)

    If this parameter is ``False`` or missing, best limits of order books are
    not printed on each step (tick).

.. index:: 
    pair: timer; parameter
    pair: display; timer

timer
    Should FMS show a timer while running (optional, default ``False``)

    If this parameter is ``True``, a day:time timer is displayed while the
    experiment is running.

.. index::
    pair: world; parameter
    pair: world; class name
    pair: world; arguments
    pair: world; configuration

world
    World class information (required)

    Parameters describing the World class to use in this experiment:

    classname
        World class name (required)

        The name of the world class to use. The class source should be in a
        module named after the class, in all lowercase chars, with a '.py'
        extension, located either in the ``fms/worlds/`` or in the
        ``fms/contrib/<contributor>/worlds/`` directory.

        args
        World class arguments (optional)

        Any arguments required by or optional to the world class.

.. index::
    pair: engines; parameter
    pair: engine; class name
    pair: engine; arguments
    pair: engine; configuration
    pair: market; parameter
    pair: market; class name
    pair: market; arguments
    pair: market; configuration
    pair: days; parameter
    pair: parameter; days (number of)
    pair: clearbooksateod; parameter
    pair: daylength; parameter

engines
    Engine classes information (required)

    Parameters describing the Engine classes to use in this experiment. The
    experiment might use multiple engines, one after the other, thus the list
    syntax is required for the classname arguments (that is, they should be
    preceded by a dash, see the examples).

    classname
        Engine class name (at least one required)

        The name of the engine class to use. The class source should be in a
        module named after the class, in all lowercase chars, with a '.py'
        extension, located either in the ``fms/engines/`` or in the
        ``fms/contrib/<contributor>/engines/`` directory.

    market
        Market class information (required)

        Parameters describing the Market class associated with this Engine class:

        classname
            Market class name (required)

            The name of the market class to use. The class source should be in a
            module named after the class, in all lowercase chars, with a '.py'
            extension, located either in the ``fms/markets/`` or in the
            ``fms/contrib/<contributor>/markets/`` directory. 

        args
            Market class arguments (optional)

            Any arguments required by or optional to the market class.

    days
        Number of days (optional, integer)

        The number of days the experiment will run, as an integer. See daylength
        below. Days is set to one if missing.

    clearbooksateod
        Clear books at end of day (optional, boolean)

        Should engine clear order books at the end of every given day. ``True``
        if missing. Note that if this parameter is set to ``False`` for a given
        engine, there is no difference between an experiment with ``d`` days
        and ``t`` daylength, and another one with ``1`` day and ``d*t``
        daylength.

    daylength
        Day length (optional, integer)

        The number or times the engine will choose an agent and let her speak on
        the market, per day, as an integer. The daylength is set to one if
        missing.  The engine will thus loop 'days times daylength' times before
        stopping.

    args
        Engine class arguments (optional)

        Any arguments required by or optional to the engine class.

.. index::
    pair: agents; parameter
    pair: agent; class name
    pair: agent; arguments
    pair: agent; configuration
    pair: parameter; agents (number of)
    pair: parameter; agents (wealth)
    pair: parameter; money
    pair: parameter; agents (stocks)
    pair: parameter; stocks

agents
    Agents classes information (required)

    Parameters describing the Agent classes to use in this experiment. The
    experiment might use multiple agents classes, one after the other, thus the
    list syntax is required for the classname arguments (that is, they should be
    preceded by a dash, see the examples).

    classname
        Agent class name (at least one required)

        The name of the agent class to use. The class source should be in a
        module named after the class, in all lowercase chars, with a '.py'
        extension, located either in the ``fms/agents/`` or in the
        ``fms/contrib/<contributor>/agents/`` directory.

    number
        Number of agents instances (required)

        The number of agent instances of this class on the market as an integer.
        Especially useful if you want to mix agents classes on the market (e.g.
        informed and non-informed) in given proportions.

    money
        Initial endowment of the agent (required)

        The money the agent owns for investing when the experiment starts, as a
        float.  This parameter might be used (or not) in the agent class, to
        check that the agents is able to pay for the orders she puts, for an
        example.

    stocks
        Initial number of stocks in the agent's portfolio (required)

        The number of stocks the agent owns when the experiment starts, as an
        integer.  This parameter might be used (or not) in the agent class, to
        check for shortselling, for an example.

    args
        Agent class arguments (optional)

        Any arguments required by or optional to the agent class.

.. index::
    pair: configuration file; example

Examples provided
=================

The ``examples`` directory in the main documentation directory [1]_ contains
example configuration files, all of which are heavily commented.


-----------------------

.. rubric:: Footnotes

.. [1] The main documentation directory is located in the ``docs`` directory of FMS
    installation under Linux or BSD, and in the ``Doc\fms-documentation`` 
    directory in the Python installation directory under Windows