User Tools

Site Tools


structuring_experimenting:start

Structuring Experimenting

As part of a Masters Team Project, done by Esmée Bertens, Tim de Ridder and Herman de Vos, a framework for performing chi-simulation experiments within the SE Group has been developed. The framework is written in Python and is developed in order to:

  • Structure the way in which chi-simulation experiments are done.
  • Facilitate sharing of used scripts and tools among different users.
  • Save time and effort when setting up an experiment.
  • Improve the quality of the experimenting process.


From this page the required Python files for the framework can be downloaded (see Downloads section below). For a detailed description of the framework is referred to the report of the Masters Team Project that is mentioned above or to the slides of the presentation that was given at the SERR meeting on 3 May 2007.

Main Concept

The experimenting process is divided into three parts:

  • Run - Start the actual simulations with the chi-model.
  • Calculation - Perform the desired calculations on the simulation output.
  • Visualization - Visualize the experiment results by means of a graph for example.


The framework contains three parallel processes in which these three parts of the experimenting process are executed. Data is exchanged between the processes by means of three buffers:

  • r2c - Passes the simulation output from the Run process to the Calculation process
  • c2r - Contains so-called 'simulation jobs', which can be created initially by the Run process and during the experiment by the Calculation process, dependent on the output of former simulation runs.
  • c2v - Passes the calculation results from the Calculation process to the Visualization process.

Implementation

The figure below shows how the functionality described above, is implemented in five different files:

  • frame.py
  • run_*.py
  • calc_*.py
  • vis_*.py
  • main_*.py


structure.eps

In frame.py a class called Frame is defined. Frame possesses three execution threads in which three Python functions, called run_func(), calc_func() and vis_func(), are executed. These functions are defined in run_*.py, calc_*.py and vis_*.py. An experiment is initialized and started by the script main_*.py.

A documentation of the defined classes and functions is created from the Python code using Epydoc. This zip file consists of a number of html files. To read the documentation: Unzip the file and start index.html.

frame.py will soon be installed on the SE racks. Until then, use the frame.py file from the Downloads section. frame.py contains the fixed part of the framework, whereas the other files (the main script and the function files) are specific for each experiment. The latter files are supposed to be created and adapted by the end user.

Creating/adapting Function Files

Below, the interfaces of the Run, Calculation and Visualization functions are shown:

  • run_func(log,r2c,c2r,pars)
  • calc_func(log,r2c,c2r,c2v,pars)
  • vis_func(log,c2v,pars)


In each function, log information can be written by a command like:

log.write("RUN\tThis is log information.")

Data is written to and read from a buffer by:

r2c.write(data)
data = r2c.read()

where data is allowed to be any object except None.

Optional parameters, which are set in the main script, are passed as a list (or a dictionary) through the pars argument.

See the template and example files in the Downloads section to get an idea of how to build your own function from the elements that are described above.

Creating a Main Script

The script main_*.py performs the following actions:

  • Import the three Python functions from the files in which they are defined.
  • Set 'global' parameters for the experiment.
  • Create an instance of Frame and pass the required functions and parameters to it.
  • Start the frame, i.e. start concurrent execution of the three functions.


See the template and example files in the Downloads section to see how to build your own main script.

Steps to set up an experiment

  • Step 1: Create your own chi model and compilate it.
  • Step 2: Download an example package with a main_*.py, run_*.py, calc_*.py and vis_*.py file, which is most suitable to your experiment.
  • Step 3: Create/adapt the three function files:
    • my_run_script.py
    • my_calc_script.py
    • my_vis_script.py
  • Step 4: Adapt main file: my_main_script.py. Make sure the functions called in this script are imported from the files created in step 3.
  • Step 5: Copy all files to your directory on the SE rack.
  • Step 6: To execute the experiment with python, type:
$ python my_main_script.py

When Plots are created with for instance Gnuplot, make sure Exceed is started first.

Downloads

From the table below, the Python files that are required to set up an experiment, can be downloaded. Users are encouraged to add there own function files to the list below, in order to get a more and more complete collection of function files in which all kind of functionality is implemented.

Python files: Description:
templates Templates for the main script and the function files.
Example 1: Multiple parameters Function files and main script of an example experiment in which simulations are run a fixed number of times with a chi-model that has multiple input and output parameters. Mean values of the simulation output are calculated and plotted in a graph. To view the plots from Gnuplot, first startup Exceed.
Example 2: Feedback Function files and main script of an example experiment in which the number of simulation runs is determined by the calculation process, based on the simulation output. To view the plots from Gnuplot, first startup Exceed.
frame.py With this file the framework is created for connecting the three processes run, calculation and visualization. This file will soon be installed on the SE rack.

List of other information presented on this Wiki page:

Information Description:
report Final report of the masters team project. Including a preceding survey of the performing simulation experiments within the SE Group, Conceptual design and implementation details of the final product, clarification of the two examples and recommendations.
presentation Presentation of the masters team project that was given at the SERR meeting on 3 May 2007.
documentation Python files Documentation of the defined classes and functions is created from the Python code using Epydoc.
structuring_experimenting/start.txt · Last modified: Tuesday, 15 May 2007 : 16:02:26 (external edit)