FMS needs a detailed description of an experiment before being able able to run it. The experiment configuration file contains this description.
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.
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).
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:
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
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 outputfilename above for an example.
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.
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.
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 /.
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.
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).
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.
World class information (required)
Parameters describing the World class to use in this experiment:
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.
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).
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 class information (required)
Parameters describing the Market class associated with this Engine class:
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.
Market class arguments (optional)
Any arguments required by or optional to the market class.
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.
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.
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.
Engine class arguments (optional)
Any arguments required by or optional to the engine class.
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).
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 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.
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.
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.
Agent class arguments (optional)
Any arguments required by or optional to the agent class.
The examples directory in the main documentation directory [1] contains example configuration files, all of which are heavily commented.
Footnotes
| [1] | (1, 2) 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 |