staj - Staj File

MlayerMagnetic	Model definition used by GJ2 program.
MlayerModel	Model definition used by MLayer program.

Read and write staj files

Staj files are the model files for the mlayer and gj2 programs, which are used as the calculation engine for the reflpak suite. Mlayer supports unpolarized beam with multilayer models, and has files ending in .staj. GJ2 supports polarized beam without multilayer models, and has files ending in .sta.

class refl1d.staj.MlayerMagnetic(**kw)

Bases: object

Model definition used by GJ2 program.

Attributes:

Q values and reflectivity come from a data file with Q, R, dR or from simulation with linear spacing from Qmin to Qmax in equal steps:

data_file

base name of the data file, or None if this is simulation only

active_xsec

active cross sections (usually ‘abcd’ for all cross sections)

Qmin, Qmax, num_Q

for simulation, Q sample points

Resolution is defined by wavelength and by incident angle:

wavelength, wavelength_dispersion, angular_divergence

resolution is calculated as \(\Delta Q/Q = \Delta\lambda/\lambda + \Delta\theta/\theta\)

Additional beam parameters correct for intensity, background and possibly guide field angle:

intensity, background

incident beam intensity and sample background

guide_angle

angle of the guide field

Unlike pure structural models, magnetic models are in one large section with no repeats. The single parameter is the number of layers, which is implicit in the length of the layer data and does not need to be an explicit attribute.

Interfaces are split into discrete steps according to a profile, either error function or hyperbolic tangent. For sharp interfaces which do not overlap within a layer, the interface is broken into a fixed number of slabs with slabs having different widths, but equal changes in height. For broad interfaces, the whole layer is split into the same fixed number of slabs, but with each slab having the same width. The following attributes are used:

roughness_steps

number of roughness steps (13 is coarse; 51 is fine)

roughness_profile

roughness profile is either ‘E’ for error function or ‘H’ for tanh

Layers have thickness, interface roughness and real and imaginary scattering length density (SLD). Roughness is stored in the file using full width at half maximum (FWHM) for the given profile type. For convenience, roughness can also be set or queried using a 1-\(\sigma\) equivalent roughness on an error function profile. Regardless, layer parameters are represented as vectors with one entry for each top, middle and bottom layer using the following attributes:

thickness, roughnessfloat | Å

layer thickness and FWHM roughness

rho, irhofloat, float | \(16 \pi \rho\), \(2\lambda\rho_i\)

complex scattering length density

mthickness, mroughnessfloat | Å

magnetic thickness and roughness

mrhofloat | \(16 \pi \rho_M\)

magnetic scattering length density

mthetafloat | °

magnetic angle

sigma_roughness, sigma_mroughnessfloat | Å

computed 1-\(\sigma\) equivalent roughness for erf profile

The conversion from stored \(16 \pi \rho\), \(2\lambda\rho_i\) to in memory \(10^6 \rho\), \(10^6 \rho_i\) happens automatically on read/write.

The layers are ordered from surface to substrate.

Additional attributes are as follows:

fitpars

individual fit parameter numbers

constraints

constraints between layers

output_file

name of the output file

These can be safely ignored, except perhaps if you want to try to compile the constraints into something that can be used by your system.

Methods:

model = MlayerMagnetic(attribute=value, …)

Construct a new MLayer model with the given attributes set.

model = MlayerMagnetic.load(filename)

Construct a new MLayer model from a sta file.

model.set(attribute=value, …)

Replace a set of attribute values.

model.fit_resolution(Q, dQ)

Choose the best resolution parameters to match the given Q, dQ resolution. Returns the object so that calls can be chained.

model.resolution(Q)

Return the resolution at Q for the current resolution parameters.

model.save(filename)

Write the model to the given named file. Raises ValueError if the model is invalid.

Constructing new files:

Staj files can be constructed directly. The MlayerModel constructor can accept all data attributes as key word arguments. Models require at least data_file, wavelength, thickness, roughness and rho. Resolution parameters can be set using model.fit_resolution(Q, dQ). Everything else has reasonable defaults.

FWHMresolution(Q)

Return the resolution at Q for mlayer with the current settings for wavelength, wavelength divergence and angular divergence.

Resolution is full-width at half maximum (FWHM), not 1-\(\sigma\).

Qmax = 0.5

Qmin = 0

active_xsec = 'abcd'

angular_divergence = 0.001

background = 0

constraints = ''

data_file = ''

fit_FWHMresolution(Q, dQ, weight=1)

Choose the best dL and dT to match the resolution dQ.

Given that mlayer uses the following resolution function:

\[\Delta Q_k = (|Q_k| \Delta\lambda + 4 \pi \Delta\theta)/\lambda_k\]

we can use a linear system solver to find the optimal \(\Delta \lambda\) and \(\Delta \theta\) across our dataset from the over-determined system:

\[[|Q_k|/\lambda_k, 4\pi/\lambda_k][\Delta\lambda, \Delta\theta]^T = \Delta Q_k\]

If weights are provided (e.g., \(\Delta R_k/R_k\)), then weigh each point during the fit.

Given that the experiment is often run with fixed slits at the start and end, you may choose to match the resolution across the entire \(Q\) range, or instead restrict it to just the region where the slits are opening. You will generally want to get the resolution correct at the critical edge since that’s where it will have the largest effect on the fit.

Returns the object so that operations can be chained.

fitpars = []

guide_angle = 270

intensity = 1

irho = None

classmethod load(filename)

Load a staj file, returning an MlayerModel object

mrho = None

mroughness = None

mtheta = None

mthickness = None

num_Q = 200

output_file = ''

rho = None

roughness = None

roughness_profile = 'E'

roughness_steps = 13

save(filename)

Save the staj file

set(**kw)

property sigma_mroughness

property sigma_roughness

thickness = None

wavelength = 1

wavelength_dispersion = 0.01

class refl1d.staj.MlayerModel(**kw)

Bases: object

Model definition used by MLayer program.

Attributes:

Q values and reflectivity come from a data file with Q, R, dR or from simulation with linear spacing from Qmin to Qmax in equal steps:

data_file

name of the data file, or None if this is simulation only

Qmin, Qmax, num_Q

for simulation, Q sample points

Resolution is defined by wavelength and by incident angle:

wavelength, wavelength_dispersion, angular_divergence

resolution is calculated as \(\Delta Q/Q = \Delta\lambda/\lambda + \Delta\theta/\theta\)

Additional beam parameters correct for intensity, background and possibly sample alignment:

intensity, background

incident beam intensity and sample background

theta_offset

alignment angle correction

The model is defined in terms of layers, with three sections. The top and bottom section correspond to the fixed layers at the surface and the substrate. The middle section layers can be repeated an arbitrary number of times, as defined by the number of repeats attribute. The attributes defining the sections are:

num_top num_middle num_bottom

section sizes

num_repeats

number of times middle section repeats

Interfaces are split into discrete steps according to a profile, either error function or hyperbolic tangent. For sharp interfaces which do not overlap within a layer, the interface is broken into a fixed number of slabs with slabs having different widths, but equal changes in height. For broad interfaces, the whole layer is split into the same fixed number of slabs, but with each slab having the same width. The following attributes are used:

roughness_steps

number of roughness steps (13 is coarse; 51 is fine)

roughness_profile

roughness profile is either ‘E’ for error function or ‘H’ for tanh

Layers have thickness, interface roughness and real and imaginary scattering length density (SLD). Roughness is stored in the file using full width at half maximum (FWHM) for the given profile type. For convenience, roughness can also be set or queried using a 1-\(\sigma\) equivalent roughness on an error function profile. Regardless, layer parameters are represented as vectors with one entry for each top, middle and bottom layer using the following attributes:

thickness, roughnessfloat | Å

layer thickness and FWHM roughness

rho, irho, incohfloat | 10^-6Å^-2

complex coherent \(\rho + j \rho_i\) and incoherent SLD

Computed attributes are provided for convenience:

sigma_roughnessfloat | Å

1-\(\sigma\) equivalent roughness for erf profile

mu

absorption cross section (2*wavelength*irho + incoh)

Note

The staj files store SLD as \(16\pi\rho\), \(2\lambda\rho_i\) with an additional column of 0 for magnetic SLD. This conversion happens automatically on read/write. The incoherent cross section is assumed to be zero.

The layers are ordered from surface to substrate.

Additional attributes are as follows:

fitpars

individual fit parameter numbers

constraints

constraints between layers

output_file

name of the output file

These can be safely ignored, except perhaps if you want to try to compile the constraints into something that can be used by your system.

Methods:

model = MlayerModel(attribute=value, …)

Construct a new MLayer model with the given attributes set.

model = MlayerModel.load(filename)

Construct a new MLayer model from a staj file.

model.set(attribute=value, …)

Replace a set of attribute values.

model.fit_resolution(Q, dQ)

Choose the best resolution parameters to match the given Q, dQ resolution. Returns the object so that calls can be chained.

model.resolution(Q)

Return the resolution at Q for the current resolution parameters.

model.split_sections()

Assign top, middle, bottom and repeats to distribute the layers across sections. Returns the object so that calls can be chained.

model.save(filename)

Write the model to the given named file. Raises ValueError if the model is invalid.

Constructing new files:

Staj files can be constructed directly. The MlayerModel constructor can accept all data attributes as key word arguments. Models require at least data_file, wavelength, thickness, roughness and rho. Resolution parameters can be set using model.fit_resolution(Q, dQ). Section sizes can be set using model.split_sections(). Everything else has reasonable defaults.

FWHMresolution(Q)

Return the resolution at Q for mlayer with the current settings for wavelength, wavelength divergence and angular divergence.

Resolution is full-width at half maximum (FWHM), not 1-\(\sigma\).

Qmax = 0.5

Qmin = 0

angular_divergence = 0.001

background = 0

constraints = ''

data_file = ''

fit_FWHMresolution(Q, dQ, weight=1)

Choose the best dL and dT to match the resolution dQ.

Given that mlayer uses the following resolution function:

\[\Delta Q_k = (|Q_k| \Delta\lambda + 4 \pi \Delta\theta)/\lambda_k\]

we can use a linear system solver to find the optimal \(\Delta \lambda\) and \(\Delta \theta\) across our dataset from the over-determined system:

\[[|Q_k|/\lambda_k, 4\pi/\lambda_k][\Delta\lambda, \Delta\theta]^T = \Delta Q_k\]

If weights are provided (e.g., \(\Delta R_k/R_k\)), then weigh each point during the fit.

Given that the experiment is often run with fixed slits at the start and end, you may choose to match the resolution across the entire \(Q\) range, or instead restrict it to just the region where the slits are opening. You will generally want to get the resolution correct at the critical edge since that’s where it will have the largest effect on the fit.

Returns the object so that operations can be chained.

fitpars = []

incoh = 0

intensity = 1

irho = 0

classmethod load(filename)

Load a staj file, returning an MlayerModel object

property mu

num_Q = 200

num_bottom = 0

num_middle = 0

num_repeats = 1

num_top = 0

output_file = ''

rho = None

roughness = None

roughness_profile = 'E'

roughness_steps = 13

save(filename)

Save the staj file

set(**kw)

property sigma_roughness

split_sections()

Split the given set of layers into sections, putting as many layers as possible into the middle section, then the bottom and finally the top.

Returns the object so that operations can be chained.

theta_offset = 0

thickness = None

wavelength = 1

wavelength_dispersion = 0.01