XML syntax - basic

XML Syntax

One strength of yanera is the easy XML syntax for expressing models. This page describes the basic syntax for making models.

Accompanying the XML file should be the reflect.dtd file, which should not need to be altered. It's required to describe the rules for the XML file, to verify that the number and order of records are valid.

General

The XML file begins with two header lines, that should always be the same. They specify the DTD file to look for.

<?xml version="1.0"?>
<!DOCTYPE yanera SYSTEM "yanera.dtd">

The root level of XML tag is also always the same, and every option described below appears between the <yanera\> tags.

The rest of the file is broken into three sections, one for models, another for the data to be fit, another for miscellaneous information.

Model Section

All data relating to models fall between the <model_section\> XML tags, as follows;

<model_section>
...
</model_section>

The <model_section\> tag has two children: <model_type\> and <model\>.

Model types

The type of model is set between <model_type\> XML tags. For example

<model_type>slab</model_type>

This tag is required. Possibilities for the value are:

These will be described in more detail in the description of how individual layers are specified.

Models

Every individual model is placed between <model/> tags.

<model data_idref="data1">
...
</model>

The "data_idref" property is required. It refers to the "data_id" of only one data file, and make the association that this is the model of that data set. See the section on <data/> XML tags, for more information. At least one <data/> tag, even empty must be present.

Every <model/> tag can have several children, described as follows.

Polarization

If any model is for polarized neutrons, and there is a magnetic layer with a magnetic scattering length density specified, include the direction of the polarization between <polarized\> tags. Options are "up" and "down", and it's for you to decide which is correct. In the "up" case, the scattering length density is the sum of the nuclear and magnetic parts; $\rho = \rho_{\mathrm{nuc}} + \rho_{\mathrm{mag}}$. For "down" it's the difference; $\rho = \rho_{\mathrm{nuc}} - \rho_{\mathrm{mag}}$

This may be omitted in general. For example;

<polarized>POLARIZED_UP</polarized>

The defualt value is POALRIZED_UNPOLARIZED.

Layers

We first outline the simplest type of model, that of homogenous slab-type layers with gaussian roughness. A general slab-type layer has five or six quantities, depending on whether polarization is included. The order of the tags is important.

   <layer>
      <name>Fe layer</name>
      <thik fix="NO">11.000</thik>
      <sigz fix="YES"> 1.000</sigz>
      <rsld fix="YES"> 8.230</rsld>
      <isld fix="NO"> 0.000</isld>
      <rmag fix="YES"> 4.200</rmag>
   </layer>

For a set of $N$ layers, that run from bulk ($i=0$) to substrate ($i=N+1$), the scattering length density profile can be given as

\begin{eqnarray*} \rho(z) &=& \textrm{rsld}_0 + \sum_{i=1}^{N+1} \frac{(\textrm{rsld}_i-\textrm{rsld}_{i-1})}{2} \left( 1+\mathrm{erf}\left(\frac{z-z_i}{\sqrt{2}\textrm{sigz}_i}\right) \right) \\ z_i &=& \sum_{j=1}^{i} \textrm{thik}_j \end{eqnarray*}

where $t_i$ is the thickness, $\rho_i$ is the real part of the scattering length density, $\sigma_i$ the roughness, each of layer $i$. The location of the error function, $z_i$, is calculated by a running total of the thicknesses.

Units are in $\textrm{\AA}$ for the thickness (<thik/>) and roughness (<sigz/>), and $10^{-6} \textrm{\AA}^2$ for the scattering length densities (SLD). The nuclear SLD is given by <rsld/>, and for the magnetic SLD as <rmag/>. The imaginary part of the nuclear SLD is optional, as is the name of the layer. The order of these parameters is important, since it's dictated by the DTD.

In order to hold a parameter fixed in the fit, set the fix attribute to YES, otherwise set to NO . This is ignored if just simulating and not fitting. The fix attribute is required.

End layers: Bulk and substrates

To make the layered structure easier to read in XML format, the bulk and substrate layers have their own tags, but follow the same parameters as any layer.

   <bulk>
   ...
   </bulk>
   <substrate>
   ...
   </substrate>

The layer that the neutrons go through first should be listed first, whether it's <substrate/> or <bulk/>. It's possible to use the text "n/a" in place of numbers for <sigz/> in the first layer, and for <thik/> in the first and last layers, since these quantities don't have meaning in these layers.

Repeating multilayers

Repeating groups of layers can be represented by enclosing the layers in a repeat tag. 
    <repeat num="3">
      <layer>
        ...
      </layer>
      <layer>
        ...
      </layer>
    </repeat>
In the above case, two distinct layers are repeated three times.

Component Layers

For a "MODEL_COMPONENT" model type, the <substrate/> and <bulk/> layers are still specified as in the slab model type, but in-between layers are a sum of Gaussian and box functions. An example of each is given here: 
    <layer>
      <type>box</type>
      <name>a box layer</name>
      <thik fix="YES">10.000</thik>
      <sigz fix="YES"> 0.500</sigz>
      <cntr fix="YES"> 5.000</cntr>
      <rsld fix="YES"> 1.000</rsld>
    </layer>
    <layer>
      <type>gaussian</type>
      <name>a gaussian layer</name>
      <sigz fix="YES"> 0.500</sigz>
      <cntr fix="YES"> 5.000</cntr>
      <rsld fix="YES"> 1.000</rsld>
    </layer>

For both function types, we require a new parameter, the center of the layer in $z$ direction, given by <cntr/> tag.

For a Gaussian function, the <sigz/> tag becomes the width of the gaussian, given by

\[ \rho(z) = \textrm{rsld}\times e^{-(z-\textrm{cntr})/\textrm{sigz}^2} \]

A box function is a box of total width <thik/>, convoluted with a Gaussian of width <sigz/>:

\[ \rho(z) = \textrm{rsld}\times\left[ \mathrm{erf}\left(\frac{z-(\textrm{cntr}-\textrm{thik}/2)} {\sqrt{2}\cdot\textrm{sigz}}\right) - \mathrm{erf}\left(\frac{z-(\textrm{cntr}+\textrm{thik}/2)} {\sqrt{2}\cdot\textrm{sigz}}\right) \right] \]

If <sigz/> is zero, then it becomes a Heavyside step function.

Use a roughness parameter for both bulk and substrate. For a component-type model, these are modeled as error functions. The last, bulk layer will also need a center parameter, that sets the total thickness of the model.

Repeating layers do not work with components. This will result in undefined behaviour, and likely crashes. Use common components, described in the next section.

Common components.

It may be that several component layers are identical in some regard, SLD, thickness, etc. In this case we want to share parameters across a few layers.

This is done by a special <layer/> tag: <component/>. Put these tags just before the first <model/>, and not in it. A common component looks like a <layer/> tag: 

    <component component_id="id1">
      <type>box</type>
      <name>repeating layer type 1</name>
      <thik fix="YES">10.000</thik>
      <sigz fix="YES"> 0.500</sigz>
      <rsld fix="YES"> 0.000</rsld>
    </component>

Each common component should have a unique "component_id" identifier, which is an unique alpha-numeric string, which is also different from any "layer_id". Use this identifier to associate layers in the model with these parameters, i.e.:

      <layer component_idref="id1">
        <cntr fix="YES">15.000</cntr>
      </layer>
      <layer component_idref="id1">
        <cntr fix="YES">25.000</cntr>
      </layer>

In this example, two layers are box functions with different centers, but share all other parameters in common. Any layer specified like that above shares the <thik/>, <sigz/>, and <rsld/> parameters. Keep in mind that since the <component/> tags are processed last, they will overwrite any data in the layers. So place only shared parameters into <component/> tags. Any number of common components can be specified, and any layer can share these values.

Function Layer

The third model type is "function" layer type. In this case, we start with a slab model, as described above. If any slab is not homogeneous in SLD, the user can supply a function that describes the SLD inside that slab.

  <layer>
    <type>function</type>
    <name>inhomogeneous layer</name>
    <func>a*cos(21.991148578*(z-b)/c)</func>
    <parm name="a" fix="YES">0.500</parm>
    <parm name="b" fix="NO">10.000</parm>
    <parm name="c" fix="YES">50.000</parm>
    <thik fix="NO"> 50.000</thik>
    <sigz fix="YES">1.2</sigz>
  </layer>

For a layer of given thickness <thik/>, the <func/> tab gives a analytic expression for the SLD of that layer. The ordinate $z$ is given by z, and several variables can appear as a, b, c, etc. Mathematical functions recognised are absolute value (abs), sin, cos, tan, exponential (exp), and natural logarithm (log). Powers are expressed by "a^2". Use parentheses liberally, to make sure the expression is evaluated correctly.

Variables in the function must be placed in a <parm/> tag, only once regardless how many times they appear in the expression. Use the "name" property to associate the value with that parameter. Use the fix property as usual.

Any number of layers, except for the bulk layers, can be of function type.

Finally, include <sigz/> tag, just as a normal homogenous layer, to indicate the smoothness of the transition from the functional layer to the regular layers surrounding it.

Repeating layers may not work with function layers. Typically if a function is translated by $z$ some distance to work correctly, it will not repeat correctly. (This can be done in a later version, by adding a feature to set some zero point based on the current thickness of the sum total of the layers.)

Background

Last in the model section is the required background, in units of $10^{-6} \textrm{\AA}^2$. 
    <background fix="YES"> 0.000</background>

word

This table shows what tags and information regarding layers and layer types are required and which are optional.


 MODEL_SLAB


MODEL_COMPONENT



MODEL_FUNCTION



top bulk layer bottom bulk
top bulk box layer gaussian layer bottom bulk
top bulk layer function layer bottom bulk
<type/>




x x



x
<name/> o o o
o o o o
o o o o
<func/>










x
<parm/>










x
<thik/>
x


x



x x
<sigz/>
x x
x x x x

x x x
<cntr/>




x x x




<rsld/> x x x
x x x x
x x
x
<isld/> o o o
o o o o
o o
o
<rmag/> o o o
o o o o
o o
o

o = optional












x = required











Generated on Thu May 29 10:56:34 2008 by  doxygen 1.5.5