Tutorials:Archive

From ALPSWiki

Contents 1 Installation 1.1 SQLite Database 1.2 Preprocessor Options 1.2.1 USEPATTERN 1.2.2 DEBUG 2 HowTo 2.1 Create Database 2.2 Fill In The Database 2.3 Generate The List 2.4 Generate The Output 3 The Config File 3.1 Example of a config file: 4 Options 5 Plotfile 5.1 Plot-Tag 5.2 For-Each-Tag 5.3 Achsen 5.4 Constraints 6 Performance 6.1 -c rebuild 6.2 -c list 6.3 -c plot

Installation

The installation ist done by the automake script of the Alps-Libary. A short description of the steps to generate plots out of simulation datas is given in Chapter 2

SQLite Database

Why has SQLite been choosen?

SQLite is easy to install. The whole database is only a C-Libary, which is included in the source of this application. There is no need to install any other components. A database only constist of a single file. Since the program is a singleuserapplication it is a big advantage. The database can easily be shared with other users by copiing the file. SQLite is in the public domain licence, which is compatible with the ALPS-Licence. The performance is discussed in chapter 6

There is no need to create the database by hand. It will be created automaticlly by using the option --command=install.

Preprocessor Options

The following options are avalable:

USEPATTERN

In normal use every parameter and measurement is stored in the database. So the database can grow large and the output can take some time. With the compiler option -DUSEPATTERN the parameter and mesurements are filtered. There is no speedup in writing data into the database, but extracting data is improved.

The patternfile specifies the parameter and measurements written in the database. The patternfile is written in a XML like format to specify the possible parameters and measurements. A example is written below.

The structure of the database depends on this preprocessoroption. That means that a database cannot be shared by a programm compiled with this option and one compiled without it!

Example of a plotfile:

 <PATTERN>
   <PARAMETERS>
     <PARAMETER>L</PARAMETER>
     <PARAMETER>J</PARAMETER>
     <PARAMETER>J'</PARAMETER>
     <PARAMETER>T</PARAMETER>
   </PARAMETERS>
   <MESUREMENTS>
     <MESUREMENT>Energy</MESUREMENT>
     <MESUREMENT>Magnetization</MESUREMENT>
     <MESUREMENT>Green's Function</MESUREMENT>
   </MESUREMENTS>
 </PATTERN>

DEBUG

This preprocessor option improves the program option --verbose. This option has no influence on the databasestructure, the portability is preserved. Normally there will be no need of this option.

HowTo

In this chapter we will see how to generate output out of some simulationfiles. All options can be found in the folder 'test'. The commands given below can be used in the rootdirectory of the index. The options used here are described precisely in chapter 3.

Create Database

 ./plot --verbose --command=install --db-file=db/test.db

The option install creates an empty database ready to fill in data.

Fill In The Database

 ./plot --verbose --command=rebuild --db-file=db/test.db --xml-path=test/data/parm3d.task576.out.xml
 ./plot --verbose --command=append --db-file=db/test.db --xml-path=test/data/part1
 ./plot --verbose --command=append --db-file=db/test.db --xml-path=test/data

To fill data into the database, two options are available: rebuild and append. rebuild empties the database first, then calls the program with the option append. Append reads in datas given by the parameter xml-path. xml-path can be the name of a file or a directory. If a directory is indicated all files with the extention .xml from the directory and all subdirectories will be read. If a file is alreay indexed in the database, it will be skipped. If the file has been changed, the program with the option rebuild must be called!

Generate The List

 ./plot --verbose --command=list --db-file=db/test.db 
 ./plot --verbose --full-list --command=list --db-file=db/test.db

To get an overview over the parameters and mesurements in the database, the parameter list generates a summary of the datas in the database. This is usefull to define the constraints.

Generate The Output

 ./plot --verbose --command=plot --db-file=db/test.db --output-path=test/out --plot-file=test/plottext.xml
 ./plot --verbose --command=plot --db-file=db/test.db --output-path=test/out --plot-file=test/plotxmgr.xml
 ./plot --verbose --command=plot --db-file=db/test.db --output-path=test/out --plot-file=test/plothtml.xml

The major task of this program is to generate an output out of the database. The structure of the the plot file is described in chapter 5. The tree commands above generate three times the same output in different formats: text, HTML, xmgrace. The output in xmgrace is:

The Config File

Some options will remain the same every time the programm is called. These options can be moved to a config file. The options in the config file are overwritten by the commandline options. This means that the config file defines default values, which can be overwritten by the commandline. The following options can be given in the configfile: db-file, pattern-file, xml-path, plot-file, output-path. This options will be described in the next chapter. The config file is alway located in conf/index.cfg.

Example of a config file:

 db-file = db/index.db
 pattern-file = conf/pattern.xml
 xml-path = xml
 plot-file = plot.xml
 output-path = out

Options

Options are passed to the application by the config file or the commandline. The options in the commandline overwrite the options in the config file. The config file is described in chapter 3.

-h, --help

Alias for --command=help.

-v, --verbose

Lists the number of paresed files used in the commands append or rebuild, else it shows the number of queries.

--version

Prints the versionnumber of the program.

-d, --db-file

Relative path to the databasefile. The SQLite database is stored in a file. If no database with the given name exists, an error will be thrown. To create a new database use the option --command=install.

-x, --xml-path

Path to the XML-Files. xml-path can be the name of a file or a directory. If a directory is indicated all files with the extention .xml from the directory and all subdirectories will be read.

-p, --plot-file

Path to the plot file. The Structure of the plot file is described in chapter 5.

-o, --output-path

Relative path to the directory where the output should be saved.

-i, --pattern-file

Relative path to the pattern file. The pattern file is described in chapter 1.2.1.

-l, --full-list

Descriebes if all values of the parameters are plotted or only the first and last five.

-c, --command

This command describes the action of the application. It is also possible to pass the command as argument in the commandline. The following options are possible:

h, help: The option displays a quick overview over the options:

 Allowed options:

 Generic options:
   --version              : print version string
   -v [ --verbose ]       : Prints what's done
   -h [ --help ]          : produce help message

 Configuration:
   -d [ --db-file ] arg      : database file
   -x [ --xml-path ] arg     : sourcefile path
   -p [ --plot-file ] arg    : plotfile
   -o [ --output-path ] arg  : output path
   -i [ --pattern-file ] arg : index file, only used by 
          installation and if compiled with -DUSEPATTERN
   -l [ --full-list ] arg    : plots the whole list

 Commands:
   -c [ --command ] arg (=plot) : possible commands: 
          'help(h)', 'install(i)', 'plot'(p), 'append'(a), 
          'rebuilt'(r), 'list'(l)

i, install: Required options: --db-file Creates a database with the required tables. If the database already exists, an error will be thrown.

p, plot: Required options: --db-file, --plot-file, --output-path The database generates the plot out of the plot file. The structure of the plot file is described in Chapter 5. The plot is saved in the path specified in the output-path option. The generated file gets the name <name_of_the_plotfile>.<output_format>.
E.g. if the application is called with the option --plot-file=plot.xml, the generated file gets the name plot.xml.text.

a, append: Required options: --db-file, --xml-path More files are added to the database. If a file is already indexed in the database it will be skiped. The option xml-path can either be a file or a directory. If a directory is passed to the option, all subdirectories will be read and every file with the extention .xml will be indexed.

r, rebuild: Required options: --db-file, --xml-path This option empties the database and calles the application with the option --command=append.

l, list: Required options: --db-file Generates a list of all values indexed in the database. If the option full-list is set, all values are prited out, else only the first five and last five are prited out.
The list has the follwing structure: The output is partitioned in two parts. The upper part contains all parameters, the lower all measurements. Every entry contains the name of the parameter or measurement and the nummer of its occurance. In the upper section also the values from the database are printed.

 Parameters {Values(Occurrence)*}
     99 J {1(99)}
     99 L {12(24), 16(41), 20(24), 4(10)}
     99 T {0.05(3), 0.1(2), 0.15(2), 0.2(2), 0.25(2), ..., 
           1.8(2), 1.85(2), 1.9(2), 1.95(2), 2.0(2)}
     99 local_S {1/2(99)}

 Measurements
     99 J
     99 L
     99 MEASURE[Correlations]
     99 MEASURE[Green Function]
     99 T
     99 local_S

Plotfile

The plot file specifies the plot generated out of the database. The plotfile is an xml-document and contains all data needed to generate the output.

Example of a plotfile:

 <?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plot SYSTEM "conf/plot.dtd">
 <plot name="Energy versus temperature" output="xmgr">
     <for-each name="L">
         <xaxis name="T" type="parameter" />
         <yaxis name="Spin Correlations" type="mean" error="true" index="( 0 ) -- ( 0 )" />
         <constraint name="Energy" type="mean" operator="lessThan" value="0" />
         <constraint name="Energy" type="error" operator="lessThan" value="0.1" />
         <constraint name="L" type="parameter" operator="lessThan" value="20" />
     </for-each>
 </plot>

Plot-Tag

The plot-tag contains all information to generate a plot. The title of the output is passed in the attribute name, the output format is passed in the attribute output. The output format can be one of the formats: text- (text), xmgrace- (xmgr) or html-file (html).

For-Each-Tag

The for-each-tag loops over a parameter. The name of the parameter is set in the attribute name. An arbitrary amount of for-each-tags can be nested.

Achsen

The tags xaxis and yasis describes the x- and y-axis. The following attributes are possible:

name, required

Name of the parameter or measurement that should be plotted.

type, required

The type of the ploted value. The following values are possible: parameter, count, mean, error, variance, autocorr, index.

error, optional

If a error bar should be displayed, set the value to true.

index, optional

If vectoraverages are outputed, it is possible to fix the index of the average to a specific position.

Constraints

In this tag the constraints are passed to the application. All outputdates satisfies the constraints. The tag can have the following parameters:

name, required

Name of the parameter or measurement to be constrainted.

type, required

Type of the outputed value. The following values are possible: parameter, count, mean, error, variance, autocorr, index.

operator, required

Operator to apply on the data. The following values are defiend: lessthan, lessorequalthan, greaterthan, greaterorequalthan, notequal and equal. It the values of the measurements are no numerical values, only the operators notequal and equal shold be used.

value, required

Values to compare to those values of the parameters or measurements.

Performance

Some benchmarks are provided. The benchmarks are done on a Pentium M 1.7 GHz with 512 MB Ram with Windows. To compile g++ 3.4.4 with Cygwin was used. The folloing commands were measured:

-c rebuild

As it can be easily seen, the import of date ist linear in respect to the numbers of tupel and the filesize. In the system mentioned above ist is possible to read 225 KB or 200 Tupel per second.

-c list

To generate a list ist nearly linear in respect of the filesize. In an extrapolation to one second, one million tupels can be listed per second.

-c plot

The output of a plot is linear in repect of the filesize. The performance can vary from file to file.