Jochen Stahn, Artur Glavic, Paul Scherrer Institut, Switzerland
Brian Maranville, NIST, USA
2022-03-14


simplified model description for .ort files

A joint project by the file formats and the data analysis working groups.

Based on slack discussions and online meetings, Artur and Jochen suggest the following approach for a simple and flexible way to define a first step sample model.

This document is not free of uncertainties or contradictions! We will correct this according to the state of the discussion.

All previous suggestions and variants are removed in order to avoid confusion.

aims

experiment planning

The model might be used to estimate counting times, statistics and experimental settings already before and during the experiments.

completeness of reflectivity file

The reflectivity file can be related to a sample model without the external connection sample name - stack (in the best case this can be found in the log-book, else in the manufactorers lab journal….)

data analysis

The standadisation allows the analysis software to automatically create a starting model which is not too far from the real one.

indexing of data and analysis

A standadised model might be used for indexing and filing of the data - within the lab or on a more general scale. This might be used to train AI algorithms.

structure

The model description has the following structure:

sample:
    model:
        origin:       string    optional
        stack:        string    mandatory
        sub_stacks:   dict      optional
        layers:       dict      optional
        compositions: dict      optional
        materials:    dict      optional
        globals:      dict      optional
        reference:    string    optional
        schema:       string    optional

The information is organised according to YAML rules but for the stack string(s). The reason is to make it simple and less error-prone to enter this information by hand.

origin

A string to declare where the model parameters come from.

Example:

    origin: thicknesses based on XR mesurements, nominal compositions

stack

The simplified model description is given in one line. This allows for a very compact notation, but restricts the content to the absolute minimum.

Rules:

  1. According to the first axiom of optics, the beam enters from the left. I.e. the backing medium is the last entry in the `stack.
  2. Entries in the stack are separated by the pipe symbol |.
  3. Repeating sub_stacks are marked with <number> ( ... ).
  4. Each entry has a name and probably an assosiated thickness. These are separated by one or more spaces.
  5. The default thickness unit is nm.

Examples:

  • The standard 1000 angstrom Ni film to check the resolution:

        stack: air | Ni 100 | SiO2 0.5 | Si
    
  • A polarising multilayer with 25 repetitions of 70 angstrom Fe and 70 angstrom Si:

        stack: air | 25 ( Si 7 | Fe 7 ) | Si
    

    No information about the magnetic induction is given on this level.

  • A lipid multilayer in a solid-liquid cell:

        stack: Si | SiO2 0.5 | lipid_multilayer | water
    

    No details about the organic film are given on this level. To allow for automated processing, further information must be provided in the sub_stack section or in a data base.

sub_stacks

Each substack is made up of one or several layers. It has a unique name which is used to relate the substack to an entry in the stack. The purpose of this dictionary is to enable a simple stack for complicated models and to provide multy-layer building blocks in data bases.

    sub_stacks:
      <name>: 
        repititions: 
                        int   optional  (default: 1) defines how ofteh the substack
                        is repeated. A negaive value means an inversion of the order.
        stack:       
                        str   optional  Same rules as for the top-level stack apply.
        sequence:         
                        list  optional  Instead of an other stack, the layers and their 
                        sequence are defined.  

Examples:

  • expansion of the physical (chemical) unit lipid multilayer into a sequence of layers:

        sub_stacks:
          lipid_multilayer:
            repetitions: 4
            stack: head | tail | tail | head    
    
  • the same layer sequence, but assembled hirarchically stating with chemical units:

        sub_stacks:
          lipid:
            sequence:
              - material: headstuff
                thickness: 0.5  
              - matrial: tailstuff
                thickness: 2.2  
          lipid_inverse:
            repetitions: -1
            stack: lipid
          lipid_bilayer:
            stack: lipid | lipid_inverse
          lipid_multilayer:
            repetitions: 4
            stack: lipid_bilayer
    

layers

If information about a layer besides its chemical composition (and thus the density form a data base) and its thickness is needed, this has to be defined here. A layer has homogeneous properties. I.e. no density gradients (might be a future option) or separation into sub-layers (that is covered by sub_stack).

    layers:
      <name>:
                      Each layer from the layers list has a unique name which 
                      relates it to an entry in one of the stacks. 
                      Layers defined in a sub_stack list are only used once 
                      and do not require naming.
        thickness:
                      This overwrites the thickness given in the stack
        roughness:
        material:
                      Either a name of a material or dictionary with 
                      material parameters. See below.

material examples:

  • simple case, reference to the materials list or a data base

        layers:
          iron:
            material: Fe
    
  • a bit more detailed, therefor no internal reference

        layers:
          iron:
            material: {formula: Fe, magnetic_moment: 2.4, mass_density: 6.8}
    
  • reduced density (voids, coverage, …)

        layers:
          nickel:
            material:
              composition:
                 Ni: 0.95
            thickness: 7.5     
    

composits

A composit behaves like a material, but is made up from (on or) several materials with respective relative densities.

    compositis:
      <name>:
        <material 1>: <rel. density 1>
        <material 2>: <rel. density 2>

Example:

    composits:
      solvent:
         cyclohexane: 0.6
         toluene: 0.4

materials

Each material has a unique name which relates it to an layer.composition entry or referenced in a stack.

    materials:
      <name>:
        formula:
        sld: 
                            The scattering length density for the radiation that was 
                            used in this experiment. 
                            (neutron or x-ray for given energy)
        mass_density:
        number_density:
        magnetic_moment:
        rel_density: 
                            The density is taken from tabulated bulk values and 
                            multiplied with this parameter.
        deuteration:
                            For materials containing hydrogen this parameter allows
                            to tune the deuteration level while keeping the number
                            density constant. 
                            Details have to be figured out....

Examples:

  • magnetic moment for iron

        materials:
          Fe
            magnetic_moment: 2.2
    
  • clear names for solvents where the formula might be ambiguous:

       materials:
         cyclohexane
           formula: C6H12
           mass_density: 0.778
         toluene
           formula: C7H8
           mass_density: 0.87
    

globals

The globals section allows to (re-)define model parameters or units which apply to the full stack and if applicable also to the following sections sub_stacks, layers and materials.

Unless overwritten, the following default values are used:

    globals:
        length_unit: nm
        mass_density_unit: g/cm^3
        number_density_unit: 1/nm^3
        sld_unit: 1/angstrom^2
        magnetic_moment_unit: muB
        roughness: 0.5

reference

A string defining the model language and version to be used to interpret the data.

Example:

    reference: ORSO model language | 1.0 | https://www.reflectometry.org/projects/simple_model

schema:

    schema: <URL>

arguments

  • This structure allows to enter the same (or contradicting) information at various levels. E.g. the thickness can be defined in the stack and the layer. This is not nice for programming and might be a source of errors, but on the oter side it allows for a very compact and human readable notation.
  • The composit enables an easy way to define mixtures (solvents, interdiffusion, absorption).

vocabulary

There is a wide variety of meanings associated with key words such as layer or material. It will be quite complicated to find an agreement here, because most of us will have to accept an absurd choice at some point.

  • sample already defined
  • model
  • origin provides some informaton about how trustworthy the model is (guess vs. based on XRD)
  • stack
  • layer
  • material
  • composit material mixture
  • roghness sigma of the errorfunction describing the density variation at an ‘interface’
  • composition
  • density (which one?)
  • mass_density
  • SLD, sld
  • origin
  • magnitude
  • unit
  • schema
  • CAS Chemical Abstracts Service number

examples

    sample:
        model:
            origin: guess based on preparation
            stack: air | 10 ( Si 7 | Fe 7 ) | Si

extended version (with more information) on the level of the starting model for data analysis:

    sample:
        model:
            origin: guess based on preparation / XRR
            stack: air | 10 ( Si 70 | Fe 70 ) | Si
            materials:          
              Fe
                magnetic_moment: 2.2 
                sld: 5.02e-6
              Si
                formula: SiN0.01
                rel_density: 0.95
           globals:
              length_unit: angstrom
              m_moment_unit: muB
              roughness: 5
              sld_unit: 1/angstrom^2
           reference: ORSO model language | 1.0 | http://bla.bli

or a quite complicated model to illustrate what is possible:

sample:
    model:
        origin: guess by J. Stahn
        stack: substrate | film | water
        sub_stacks:
          substrate:
            sequence: 
               - material: Si
                 sigma: 2
               - material: SiO2
                 thickness: 5
                 sigma: 3
          film:
            repetitions: 5
            stack: head_group 4 | tail | tail | head_group 4
        layers:
          tail
            material: tailstuff
            thickness: 22.
        compoisits:
          water: 
              H2O: 0.3
              D2O: 0.7   
        materials:       
          head_group:
            sld: 0.2e6
          tailstuff:
            formula: CH2
            mass_density: 1.2
          SiO2:
            formula: SiO2
          Si:
            formula: Si
        globals:
          sigma: {magnitude: 5, unit: angstrom}
          length_units: angstrom
          mass_density_units: g/cm^3
          sld_unit: 1/angstrom^2
        reference: ORSO model language | 1.0 | https://www.reflectometry.org/projects/simple_model

Here film referes to a stack with 5 repetitions of some organic bilayer, which in turn consists of 4 sublayers. These are defined either again as layer (here for the tails) or directly with a thickness and a material. The materials section allows to define the materials used above. When missing, the name is taken as the chemical formula (e.g. Si or SiO2) or as a pre-defined material (water, air) and the corresponding values are taken from a data base.

These examples show how a model might be declared. There are various ways to do so for exactely the same model, and the choice depends mainly on the human readability and on logical units (like POPC). For automated writing (e.g. as an output from the data analysis software), we will have to find a reasonable and programmable approach….