The installation ist done by the automake script of the Alps-Libary. A short description of the steps to generate plots out of simmulations datas is given in Chapter 2
Why has SQLite been taken?
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. Becase the program is a singleuserapplication this is a big advantage. The database can easily be shared with other users by copiing the file. SQLite is in the public domain licence, the is compatible with the ALPS-Licende. The Performance is discussed in chapter 6.
There is no need to create the database by hand. It will be created automaticly by using the option --command=install.
The following options are avalable:
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 writeing data to the database, but extracting data is improved.
The Patterfile 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 depents 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>
This preprocessor option improves the progrm option --verbose. This option has no influence to the databasescructure, the portability is preserved. Normaly there will be no need of this option.
In this chapter we will see how to generate output out of somme simmulationfiles. All options can be found in the folger 'test'. The commands given below can be used in the rootdirectory of the index. The options are described precisely in chapter 3.
archive --verbose --command=install --db-file=db/test.db
The option install creates an empty database ready to fill in data.
archive --verbose --command=rebuild --db-file=db/test.db --xml-path=test/data/parm3d.task576.out.xml archive --verbose --command=append --db-file=db/test.db --xml-path=test/data/part1 archive --verbose --command=append --db-file=db/test.db --xml-path=test/data
To fill data into the database, to options are avalable: rebuild and append. rebuild empty 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 passed all files with the extention .xml from the directory and all subdirectories will be read. If a file is alreay index in the database, it will be skipt. If the file has changed, the program must be called with the option rebuild!
archive --verbose --command=list --db-file=db/test.db archive --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.
archive --verbose --command=plot --db-file=db/test.db --output-path=test/out --plot-file=test/plottext.xml archive --verbose --command=plot --db-file=db/test.db --output-path=test/out --plot-file=test/plotxmgr.xml archive --verbose --command=plot --db-file=db/test.db --output-path=test/out --plot-file=test/plothtml.xml
The mayor task of this program is to generate output out of the database. The structure of the the plot file is described in chapter 5. The tree commands above generates three times the same output in different formats: text, HTML, xmgrace. The output in xmgrace is:
Somme options will rest 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 value, 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 wie described in the next chapter. The config file is alway located 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 are passed to the appication by the config file or the command line. The options in the commandline overwrites the options in the config file. The Configfile is described in chapter 3.
-h, --help | Alias for --command=help. | |
-v, --verbose | Lists the nuber of paresed files in the commans 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 exist, a 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 passed 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 to save the output. | |
-i, --pattern-file | Relative path to the pattern file. The patternfile is described in chapter 1.2.1. | |
-l, --full-list | Specifies if all values of the prameters are plotted or only the first and last five. | |
-c, --command | This command specifies 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 Erstellt eine neue Datenbank mit den erforderlichen Tabellen. Falls die Datenbank bereits existiert, wird ein Fehler ausgegeben. | |
p, plot | Verlangte Optionen: --db-file, --plot-file, --output-path Die Datenbank generiert die, im Plotfile beschriebene, Grafik und speichert sie in dem, in output-path ergebenen, Pfad. Die Ausgabedatei hat den Namen <name_des_plotfiles>.<ausgabetype>. D.h. Falls die Applikation mit --plot-file=plot.xml aufgerufen wurde, wird eine Datei Namens plot.xml.text erzeugt. | |
a, append | Verlangte Optionen: --db-file, --xml-path Der Datenbank werden zusçÕzliche Dateien hinzugeft. Dateien, die bereits in der Datanbank indexiert sind, werden ersprungen. Als xml-path kann entweder eine Datei oder ein Verzeichnis angegeben werden. Falls ein Verzeichnis ergeben wurde, werden alle Dateien die sich im Verzeichnis oder in Unterverzeichnissen befinden und die Endung .xml besizen eingelesen. | |
r, rebuild | Verlangte Optionen: --db-file, --xml-path Die gesamte Datenbank wird gelcht, anschliessend wird die Applikation mit der option --command=append ausgefrt. | |
l, list | Verlangte Optionen: --db-file Generiert eine Liste aller Daten der Datenbank. Falls der Parameter full-list gesetzt wurde, werden alle Werte der Parameter ausgegeben, sonst werden nur die ersten und die letzten ff ausgegeben. Die Liste hat folgenden Aufbau. Die Ausgabe ist in zwei Abschnitte aufgeteilt. Oben werden alle Parameter ausgegeben, unten die Messwerte. Bei jedem Eintrag wird die Anzahl des Auftretens des Parameters oder des Messwertes in der Datenbank ausgegeben, wobei Vektoraverages nur einmal gezçÉlt werden. Anschliessend kommt der Name. Bei Parametern wird angegeben, welche Werte wie oft in der Datenbank vorkommen. 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 |
Die Plotdatei bestimmt welche Daten aus der Datenbank gelesen und ausgegeben werden. Die Plotdatei ist ein XML-Dokument und enthçÍt alle Daten, die zum Erstellen der Ausgabe nig sind.
Beispiel einer Plotdatei
<?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>
Der Plot Tag umschliesst die Informationen, die zum Erstellen des Plots nig sind und bestimmt den Titel und das Ausgabeformat. Der Titel wird mit dem Attribut Name festgelegt, das Ausgabeformat wird im Attribut output ergeben. Die Ausgabe kann ein Text- (text), ein Xmgrace- (xmgr) oder ein HTML-Dokument (html) sein.
Der For-Each-Tag erstellt eine Schleife er die Werte eines Parameters. Der Name des Parameters wird dem Attribut Name ergeben. Es knen beliebig viele For-Each-Tags innenander verschachtelt werden.
Die x- und y-Achse werden durch die Tags xaxis bzw. yaxis angesprochen. Mliche Attribute der Achsen sind:
name | obligatorisch | Name des Parameters oder des Messwertes, der ausgegeben werden soll. |
type | obligatorisch | Typ des ausgegebenen Wertes. Folgende Werte sind mlich: parameter, count, mean, error, variance, autocorr, index. |
error | optional | Wenn ein Fehlerbalken ausgegeben werden soll, muss das Attribut den Wert true annehmen. |
index | optional | Bei der Ausgabe von Vectoraverages ist es mlich zu bestimmen welcher Index der jeweiligen Messung ausgegeben werden soll. |
Die Bedingungen an die Ausgabe werden mit dem constraint Tag ergeben. Die mit diesem Tag gemachten EinschrçÏkungen werden von allen ausgegebenen Daten erflt. Der Tag hat folgende Parameter:
name | obligatorisch | Name des Parameters oder des Messwertes, der eingeschrçÏkt werden soll |
type | obligatorisch | Typ des ausgegebenen Wertes. Folgende Werte sind mlich: parameter, count, mean, error, variance, autocorr, index. |
operator | obligatorisch | Operator, der auf die Daten angewendet werden soll. Folgende Werte sind erlaubt. lessthan, lessorequalthan, greaterthan, greaterorequalthan, notequal und equal. Falls es sich bei den Werten der Messung nicht um numerische Werte handelt, knen nur die Operatoren notequal und equal verwendet werden. |
value | obligatorisch | Wert, mit dem der Parameter oder die Messung verglichen wird. |
Es wurden einige kleine Benchmarks durchgefrt. Zur Messung wurde ein Pentium M 1.7 GHz mit 512 MB Ram unter Windwos verwendet. Als Compiler diente der g++ 3.4.4 unter Cygwin. Gemessen wurden die Kommandos der folgenden Optionen:
Wie man anhand der beiden Grafiken leicht sehen kann, ist das Einlesen der Daten linear bezlich der Anzahl eingelesener Tupel und der Datengrse. Auf dem oben genannten System ist es mlich 225 KB oder 200 Tupel pro Sekunde einzulesen.
Das Augeben einer Liste ist annçÉernd linear bezlich der Dateigrse. Bei einer Extrapolation auf eine Sekunde ist ersichtlich, dass eine Liste von etwa 1 Million Tupel in dieser Zeit ausgegeben werden kann.
Das Erstellen eines Plots ist linear bezlich der Datengröóse. Geschwindigkeiten köînen von Datei zu Datei variieren.
copyright (c) 2007-2010 by Lukas Gamper
Distributed under the Boost Software License, Version 1.0. (See http://www.boost.org/LICENSE_1_0.txt)