fsc2-Metadatei für Berlin

Die Idee beruht auf einer Diskussion mit den Berlinern und orientiert sich an ihren Bedürfnissen.

Grundidee: fsc2-Metadatei, in der zu einer Reihe von (zusammengehörigen) Messungen („scans“) Kalibrierungsparameter gespeichert werden.

Ziel: Einlesen der Datei in die trEPR-Toolbox führt dazu, daß die zugehörigen Spektren geladen werden und die in der Metadatei abgelegten Kalibrierungen automatisch in die Metadaten der Spektren übernommen werden.

Kriterien für das Dateiformat

maschinenlesbar und vom Menschen lesbar („human readable“)
Reintext (ASCII)
einfache Zuordnung der Parameter zu einzelnen Messungen („scans“)
eindeutige Identifizierbarkeit des Dateiformats
- durch eine Kennung in der ersten oder zweiten Zeile

Allgemeine Formatbeschreibung

Für Ungeduldige gibt's ein Beispiel der Umsetzung weiter unten. Hier folgt zunächst einmal die allgemeine Formatbeschreibung.

Format
- Das grundsätzliche Dateiformat ist ASCII (7-bit)
- Durch die Beschränkung auf die 7-bit-ASCII-Zeichentabelle wird die Kompatibilität über Betriebssystemgrenzen hinaus gewährleistet.
Dateiname und Endung
- Die Dateiendung ist „.meta“.
- Der Dateiname identisch mit dem Grundnamen der zugehörigen Datendateien.
Die Metadatei ist in Blöcke unterteilt
- Blöcke werden durch den Blocknamen in Großbuchstaben eingeleitet
- Blockbezeichnungen bisher
  - GENERAL
  - PARAMETERS
  - COMMENT
  - CALIBRATION DATA
  - TERMINATION
Alle Bezeichner und alle Beschriftungen innerhalb der Datei sind aus Gründen der Internationalität in englischer Sprache zu halten.
Die erste Zeile der Datei ist für eine Kennung reserviert.
- ermöglicht die eindeutige Erkennung des Dateiformates beim Parsen
- wird durch eine Leerzeile vom Rest der Datei abgetrennt
Alle Blöcke und Felder sind nicht optional, sondern obligatorisch.
- Gibt es zu einem Feld keine Werte, wird „N/A“ als Wert gesetzt.
zu den Blöcken:
- Jeder Block beginnt mit einer Überschrift (Blockbezeichner) in Großbuchstaben.
- Jeder Block wird durch eine Leerzeile vom vorangegangenen Inhalt der Datei abgetrennt.
- Innerhalb der Blöcke finden sich Schlüssel-Wert-Paare aus einem Feldbezeichner, gefolgt von einem entsprechenden Wert
Feldbezeichner
- Feldbezeichner dürfen Leerzeichen enthalten, aber keine Sonderzeichen und keinen Doppelpunkt¹⁾.
- Feldbezeichner müssen mit einem Buchstaben beginnen (keine Zahl!)
- Jeder Feldbezeichner wird durch einen Doppelpunkt beendet
Werte
- Werte stehen immer hinter einem Feldbezeichner
- Innerhalb eines Blockes werden die Werte alle soweit eingerückt, daß sie bündig miteinander abschließen. D.h. der längste Feldbezeichner definiert die Einrückung der Werte.
- Werte dürfen Sonderzeichen²⁾ und Doppelpunkte enthalten
zusätzliche Bezeichner
- Innerhalb des Blockes „CALIBRATION DATA“ gibt es noch Bezeichner für jeden einzelnen Scan.
- Diese Bezeichner werden nicht durch Doppelpunkt beendet, da es sich um keine Feldbezeichner handelt, denen ein Wert folgt.
Verwendung von Doppelpunkten
- Doppelpunkte dienen lediglich der Trennung von Feldbezeichnern und Werten
- An allen anderen Stellen (nach einem zusätzlichen Bezeichner, nach einer Blocküberschrift) sind Doppelpunkte verboten. Einzige Ausnahme (s.o.) sind Feldwerte.
- Doppelpunkte werden intern beim Parsen dazu verwendet, die entsprechenden Feldbezeichner und Werte voneinander zu trennen (in Matlab: regexp mit Option split).

Beschreibung der einzelnen Blöcke

Nachfolgend werden die einzelnen Blöcke einer Meta-Datei beschrieben. Ein Beispiel der Umsetzung folgt weiter unten.

Neben der Kennung gibt es aktuell folgende Blöcke:

GENERAL
PARAMETERS
COMMENT
CALIBRATION DATA
TERMINATION

Kennung

Die Kennung besteht aus einer einzelnen Zeile mit einer eineindeutigen Zeichenkette, die Matlab, genauer gesagt der trEPRload-Routine der trEPR-Toolbox, erlaubt, das Dateiformat der fsc2-trEPR-Metadatei eindeutig zu erkennen.

Wie die Erkennung funktioniert, wird in Grundzügen bei der Dokumentation der zur trEPRload-Funktion gehörenden trEPRload-Ini-Datei beschrieben.

GENERAL

Der Block „GENERAL“ besteht aus einigen Grundinformationen zur Meßserie.³⁾

Die Felder im Einzelnen:

Feldname	Beschreibung
Measurement start	Datum und Uhrzeit Beispiel: Mon Sep 12, 2011; 15:39:30
Measurement type	Art der Messung Werte: Normal/OPO
Number of scans (per direction)	Zahl der Einzelmessungen pro Richtung Beispiel: 10
Number of scans (total)	Zahl der Einzelmessungen insgesamt Beispiel: 20
Scan direction	Feldzyklen, in denen aufgenommen wurde Werte: up/down/updown/downup

Anmerkungen

Parser-Verhalten in Abhängigkeit vom Wert des Feldes „Measurement type“
- Wenn „Measurement type“ auf eine „Wellenlängen-Serie“ hinweist, dann findet sich im Block „CALIBRATION DATA“ ein zusätzliches Feld „OPO wavelength“ und das Feld „Laser wavelength“ fehlt im Block „PARAMETERS“.

PARAMETERS

Im Block „PARAMETERS“ finden sich all die Parameter wieder, die auch bislang (und nach wie vor) zu jedem einzelnen Datensatz in der zugehörigen Datendatei abgelegt werden.

Die Felder im Einzelnen:

Feldname	Beschreibung
Number of runs	Zahl der Einzelmessungen (pro Richtung) Beispiel: 10
Field start	Feldwert, bei dem die Messung begonnen wurde Beispiel: 3500.00000 G
Field end	Feldwert, bei dem die Messung beendet wurde Beispiel: 3700.00000 G
Field step	Feldschrittweite Beispiel: 5.00000000 G
Sensitivity	Empfindlichkeit des Transientenrekorders (Oszilloskops) Beispiel: 100.000000 mV/div
Number of averages	Zahl der Mittelungen (im Transientenrekorder) Beispiel: 10
Time base	Zeitbasis des Transientenrekorders Beispiel: 5.00000000 us/div
Number of points	Zahl der Punkte einer Zeitkurve Beispiel: 500
Trigger position	Triggerposition innerhalb der Zeitkurve (in Punkten) Beispiel: 50
Slice length	Länge einer Zeitkurve (in Mikrosekunden) Beispiel: 50.0000000 us
Oscilloscope coupling type	Art der Kopplung des Oszilloskops/Transientenrekorders Werte: AC/DC/GND
Oscilloscope impedance	Eingangsimpedanz des Oszilloskops/Transientenrekorders Beispiel: 1 MOhm
Oscilloscope bandwidth	Bandbreite des Oszilloskops/Transientenrekorders Beispiel: 20 MHz
MW frequency	Mikrowellenfrequenz, bei der gemessen wurde Beispiel: 9.74000000 GHz
Attenuation	Dämpfung, bei der gemessen wurde Beispiel: 20.0000000 dB
Temperature	Temperatur, bei der gemessen wurde Beispiel: 80.0000000 K
Laser wavelength	Laserwellenlänge, bei der gemessen wurde Beispiel: 460.000000 nm Hinweis: Fehlt, wenn ein Wellenlängenscan gefahren wurde
Wavelength setup	Einstellung der Wellenlänge Werte: manual/opo
Laser repetition rate	Laserschußfrequenz, mit der gemessen wurde Beispiel: 1.25000000 Hz
MW bridge	Modellbezeichnung der verwendeten Mikrowellenbrücke Beispiel: Bruker ER 046 XK-T
Calibration	Schalter für die ausgewählten Kalibrierungen Werte: none/field/frequency/fieldfrequency
Digitizer model	Modellbezeichnung des verwendeten Oszilloskops/Transientenrekorders Beispiel: TDS520A
Field controller model	Modellbezeichung der verwendeten Feldsteuerung Beispiel: BH15_FC
Gaussmeter model	Modellbezeichnung des verwendeten Gaussmeters Beispiel: ER035M_SAS
Frequency counter model	Modellbezeichnung des verwendeten MW-Frequenzzählers Beispiel: N/A
Laser model	Modellbezeichnung des verwendeten OPOs Beispiel: Spectra Physics GCR-11
OPO model	Modellbezeichnung des verwendeten OPOs Beispiel: OPTA BBO-355-vis/IR

COMMENT

Der Block „COMMENT“ enthält den über die fsc2-GUI vor der Messung eingebbaren Freitextkommentar des Nutzers. Dieser Kommentar ist insbesondere nützlich für eine etwas detailliertere Beschreibung der Probe, so man das nicht alles über den Dateinamen machen kann (und/oder möchte).

Hinweis: Offensichtlich fügt fsc2 vor und nach dem Kommentar selbständig jeweils eine Leerzeile ein. Demzufolge beginnt und endet der vom Nutzer angegebene Kommentar dann mit einer Leerzeile (die sich beim Parsen entsprechend abfangen und eliminieren ließe).

zusätzliche Parameter

Es gibt eine Reihe zusätzlicher Parameter, die sowohl in den Subblöcken „Required Parameters“ als auch „Additional Parameters“ auftauchen können.

Momentan werden die folgenden zusätzlichen Parameter vom Parser (trEPRfsc2MetaLoad) erkannt und verarbeitet:

Feldname	Beschreibung
Laser pulse energy	Pulsenergie des Lasers (hinter dem OPO) Beispiel: 6 mJ
Resonator	Resonatormodell Beispiel: Bruker ER 4118X-MS2
Resonator coupling	Kopplung des Resonators Werte: critical/overcoupled
MW detection	Detektionsweise der Brücke (Diode/Mischer) Werte: mixer/diode

CALIBRATION DATA

Der Block „CALIBRATION DATA“ ist, historisch betrachtet, der Grund für die fsc2-Metadatei. Hier werden zu jedem einzelnen gemessenen Datensatz („scan“), so vorhanden, Kalibrationswerte für Feld (via NMR-Gaussmeter) und Frequenz (via MW-Frequenzzähler) abgelegt.

Der Block ist in Subblöcke für jeden Datensatz unterteilt, und zwar so viele Subblöcke, wie auch real Datensätze gemessen wurden.⁴⁾

Jeder Subblock wird durch eine Blocküberschrift eingeleitet: „Scan #“, wobei „#“ für die Nummer der Einzelmessung in der Serie steht.

Jeder Subblock hat eine Reihe von Feldern:

Feldname	Beschreibung
Filename	Dateiname der Einzelmessung Name mit komplettem Pfad
Field start	Kalibrationswert für das Feld bei Beginn der Messung Beispiel: 3495.33000 G Wenn nicht gemessen: N/A
Field end	Kalibrationswert für das Feld am Ende der Messung Beispiel: 3695.06000 G Wenn nicht gemessen: N/A
Field step	neu berechnete Schrittweite der Magnetfeldachse Beispiel: 4.99325000 G Wenn nicht gemessen: N/A
Frequency start	Kalibrationswert für die MW-Frequenz bei Beginn der Messung Beispiel: 9.70730500 GHz Wenn nicht gemessen: N/A
Frequency end	Kalibrationswert für die MW-Frequenz am Ende der Messung Beispiel: 9.70730000 GHz Wenn nicht gemessen: N/A
Laser wavelength	Wellenlänge des Lasers Beispiel: 532.000000 nm Hinweis: Wird nur im Fall eines Wellenlängenscans geschrieben

TERMINATION

Der Block „TERMINATION“ gibt Auskunft darüber, ob die Messung vorzeitig abgebrochen wurde.

Die Felder im Einzelnen:

Feldname	Beschreibung
Status	„exit state“ des Programms 0 - reguläre Beendigung, keine Fehler >0 - das Programm wurde abgebrochen
Message	Details zum Programmstatus nach dem Ende Für Details vgl. untenstehende Tabelle

Das Feld „Message“ hat in Abhängigkeit vom Rückgabestatus den folgenden Inhalt:

Status	Statusmeldung
0	Measurement successful.
1	Measurement was aborted by user after # scans.
2	Measurement was aborted by user after completion of wavelength #/#.

Beispiel

Da es zwei verschiedene Meßmodi gibt („Normal“ und „OPO“), nachfolgend auch zwei Beispieldateien.

Normalscan

metadata fsc2 program trEPR_henryk3_2 2011/10/31

GENERAL
Measurement start:               Mon Oct 31, 2011; 13:51:34
Measurement type:                Normal
Number of scans (per direction): 3
Number of scans (total):         3
Scan direction:                  up

PARAMETERS
Number of runs:             3
Field start:                2000.00000 G
Field end:                  2100.00000 G
Field step:                 5.00000000 G
Sensitivity:                100.000000 mV/div
Number of averages:         5
Time base:                  5.00000000 us/div
Number of points:           500
Trigger position:           50
Slice length:               50.0000000 us
Oscilloscope coupling type: AC
Oscilloscope impedance:     1 MOhm
Oscilloscope bandwidth:     20 MHz
MW frequency:               9.62378800 GHz
Attenuation:                25.0000000 dB
Temperature:                300.000000 K
Laser wavelength:           532.000000 nm
Wavelength setup:           manual
Laser repetition rate:      10.0000000 Hz
MW Bridge:                  Bruker ER 046 XK-T
Calibration:                field
Digitizer model:            TDS520A
Field controller model:     BH15_FC
Gaussmeter model:           ER035M_SAS
Frequency counter model:    N/A
Laser model:                Spectra Physics GCR-11
OPO model:                  OPTA BBO-355-vis/IR

COMMENT

Please enter additional parameters below, it is highly recommended to keep the structure.

Sample description (multi line)
Luft im Resonator
(sollte kein Signal geben)

Required parameters
Laser pulse energy:            nix

Additional parameters
parameter:                     value

Free text comment (multi line)
Physics is fun!


CALIBRATION DATA
Scan 1
File name:        /home/kalbe/fsc2/version3-test/output111031.s001up.dat
Field start:      1997.40000 G
Field end:        2097.21000 G
Field step:       4.99050000 G
Frequency start:  N/A
Frequency end:    N/A
Scan 2
File name:        /home/kalbe/fsc2/version3-test/output111031.s002up.dat
Field start:      1997.41000 G
Field end:        2097.22000 G
Field step:       4.99050000 G
Frequency start:  N/A
Frequency end:    N/A
Scan 3
File name:        /home/kalbe/fsc2/version3-test/output111031.s003up.dat
Field start:      1997.40000 G
Field end:        2097.22000 G
Field step:       4.99100000 G
Frequency start:  N/A
Frequency end:    N/A

TERMINATION
Status:  0
Message: Measurement successful.

OPO-Scan

<note important>Die Beispieldatei für den OPO-Modus befindet sich noch in der aktiveren Entwicklung.</note>

metadata fsc2 program trEPR-opo-gui 2011/09/22

GENERAL
Measurement start:                Fri Sep 23, 2011; 14:08:41
Measurement type:                 Normal
Number of scans (per direction):  3
Number of scans (per wavelength): 3
Number of scans (total):          9
Scan direction:                   down

PARAMETERS
Number of runs:         3
Start field:            2020.00000 G
End field:              2000.00000 G
Field step width:       -5.00000000 G
Sensitivity:            50.0000000 mV/div
Number of averages:     1
Time base:              5.00000000 us/div
Number of points:       500
Trigger position:       50
Slice length:           50.0000000 us
Oscilloscope coupling:  AC/1MOhm
Oscilloscope bandwidth: 500 MHz
MW Bridge:              Bruker ER 046 XK-T
Calibration:            field

COMMENT

Please enter additional parameters below, it is highly recommended to keep the structure.

Sample description (multi line)
x

Microwave frequency:           x
Microwave attenuation:         x
Temperature:                   x
Laser repetition rate:         x
Laser pulse energy:            x

Additional parameters
parameter:                     value

Free text comment (multi line)
Physics is fun!


CALIBRATION DATA
Scan 1
File name:        /home/kalbe/fsc2/testpaket/opo.w01s001down.dat
Field start:      2017.39000 G
Field end:        1997.46000 G
Field step:       -4.98250000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 532.000000 nm
Scan 2
File name:        /home/kalbe/fsc2/testpaket/opo.w01s002down.dat
Field start:      2017.40000 G
Field end:        1997.46000 G
Field step:       -4.98500000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 532.000000 nm
Scan 3
File name:        /home/kalbe/fsc2/testpaket/opo.w01s003down.dat
Field start:      2017.40000 G
Field end:        1997.46000 G
Field step:       -4.98500000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 532.000000 nm
Scan 4
File name:        /home/kalbe/fsc2/testpaket/opo.w02s001down.dat
Field start:      2017.40000 G
Field end:        1997.46000 G
Field step:       -4.98500000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 533.000000 nm
Scan 5
File name:        /home/kalbe/fsc2/testpaket/opo.w02s002down.dat
Field start:      2017.41000 G
Field end:        1997.46000 G
Field step:       -4.98750000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 533.000000 nm
Scan 6
File name:        /home/kalbe/fsc2/testpaket/opo.w02s003down.dat
Field start:      2017.41000 G
Field end:        1997.47000 G
Field step:       -4.98500000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 533.000000 nm
Scan 7
File name:        /home/kalbe/fsc2/testpaket/opo.w03s001down.dat
Field start:      2017.40000 G
Field end:        1997.47000 G
Field step:       -4.98250000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 534.000000 nm
Scan 8
File name:        /home/kalbe/fsc2/testpaket/opo.w03s002down.dat
Field start:      2017.41000 G
Field end:        1997.47000 G
Field step:       -4.98500000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 534.000000 nm
Scan 9
File name:        /home/kalbe/fsc2/testpaket/opo.w03s003down.dat
Field start:      2017.42000 G
Field end:        1997.48000 G
Field step:       -4.98500000 G
Frequency start:  N/A
Frequency end:    N/A
Laser wavelength: 534.000000 nm

TERMINATION
Status:  0
Message: N/A

¹⁾

Einzige Ausnahme sind momentan runde Klammern. Kommen noch einzelne weitere Ausnahmen hinzu, ließe sich das auch noch nachbauen. Hintergrund der Beschränkung ist, daß die Feldbezeichner als Feldnamen intern in Matlab-Strukturen (struct) verwendet werden.

²⁾

Grundsätzlich ist von der Verwendung von Sonderzeichen aber abzuraten, da sie häufig der unterschiedlichen Zeichensatzkodierung zum Opfer fallen. Umlaute etc. sind, obwohl vermutlich eh unnötig, da die Inhalte möglichst in englischer Sprache formuliert werden sollen, definitiv keine gute Idee, da Matlab mit unterschiedlichen Zeichensatzkodierungen auf den unterschiedlichen Betriebssystemen arbeitet.

³⁾

Meist, aber nicht notwendigerweise, handelt es sich bei Messungen, zu denen eine Meta-Datei gehört, um eine Meßserie.

⁴⁾

Konkret bedeutet das: Wurde die Messung vorzeitig abgebrochen, sind die Felder „Number of runs“ im Block „GENERAL“ nicht identisch mit den tatsächlich durchgeführten Einzelmessungen. Die Zahl der Subblöcke bei den Kalibrationsdaten ist aber immer identisch mit der Zahl der tatsächlich durchgeführten Einzelmessungen.

till-biskup.de

Table of Contents

fsc2-Metadatei für Berlin

Kriterien für das Dateiformat

Allgemeine Formatbeschreibung

Beschreibung der einzelnen Blöcke

Kennung

GENERAL

Anmerkungen

PARAMETERS

COMMENT

zusätzliche Parameter

CALIBRATION DATA

TERMINATION

Beispiel

Normalscan

OPO-Scan