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)[source]

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, roughness : float | Å
layer thickness and FWHM roughness
rho, irho : float, float | \(16 \pi \rho\), \(2\lambda\rho_i\)
complex scattering length density
mthickness, mroughness : float | Å
magnetic thickness and roughness
mrho : float | \(16 \pi \rho_M\)
magnetic scattering length density
mtheta : float | °
magnetic angle
sigma_roughness, sigma_mroughness : float | Å
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)[source]

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)[source]

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)[source]

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)[source]

Save the staj file

set(**kw)[source]
sigma_mroughness
sigma_roughness
thickness = None
wavelength = 1
wavelength_dispersion = 0.01
class refl1d.staj.MlayerModel(**kw)[source]

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, roughness : float | Å
layer thickness and FWHM roughness
rho, irho, incoh : float | 10-6-2
complex coherent \(\rho + j \rho_i\) and incoherent SLD

Computed attributes are provided for convenience:

sigma_roughness : float | Å
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)[source]

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)[source]

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)[source]

Load a staj file, returning an MlayerModel object

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)[source]

Save the staj file

set(**kw)[source]
sigma_roughness
split_sections()[source]

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