Tutorials:Archive

From ALPS
Jump to: navigation, search

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 .

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 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 . 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: . The output in xmgrace is:

File:TutorialsArchivePlot.png

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: , , , , . This options will be described in the next chapter. The config file is alway located in .

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.



Allowed options:
Generic options:
  --version             $nbsp;: print version string
  -v [ --verbose ]      $nbsp;: Prints what's done
  -h [ --help ]         $nbsp;: produce help message
Configuration:
  -d [ --db-file ] arg     $nbsp;: database file
  -x [ --xml-path ] arg    $nbsp;: sourcefile path
  -p [ --plot-file ] arg   $nbsp;: plotfile
  -o [ --output-path ] arg $nbsp;: output path
  -i [ --pattern-file ] arg$nbsp;: index file, only used by 
         installation and if compiled with -DUSEPATTERN
  -l [ --full-list ] arg   $nbsp;: plots the whole list
Commands:
  -c [ --command ] arg (=plot)$nbsp;: possible commands: 
         'help(h)', 'install(i)', 'plot'(p), 'append'(a), 
         'rebuilt'(r), 'list'(l)


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:


Constraints

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


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:

File:TutorialsArchiveRebuildKb.png File:TutorialsArchiveRebuildTuple.png

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.

File:TutorialsArchiveBrowse.png

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.

File:TutorialsArchiveExtract.png

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