## Scan models

Scans are needed to construct simulations of types reflectometry, off-specular scattering, depth probe.

There are three types of scan:

- Alpha scans, for instruments that are mechanically scanning the grazing angle $\alpha_\text{i}$;
- Lambda scans, for instruments that are scanning the wavelength $\lambda$;
- Qz scans, for both angular-scanning or time-of-flight instruments.

#### Common properties

All scan types have `intensity`:

    scan.setIntensity(intensity)

Polarization and analyzer can be assigned to the scan when needed (for specular and off-specular simulations).

    scan.setPolarization(polarization) # for specular & off-specular
    scan.setAnalyzer(analyzer) # for specular

### Alpha scans

To specify a scan with `n` equidistant points in the grazing angle $\alpha_\text{i}$, use

    scan = ba.AlphaScan(n, alpha_start, alpha_stop)

Usage is demonstrated by most examples in Examples/specular .

For other sequences of $\alpha_\text{i}$ values, use the more generic

    alpha_list = ba.ListScan("alpha_i (rad)", [0*deg, 0.01*deg, ... 1.2*deg]) # all points
    scan = ba.AlphaScan(alpha_list)

After constructing a scan, set the wavelength and optionally the azimuthal angle and a constant offset $\delta\alpha_\text{i}$ using

    scan.setWavelength(lambda)
    scan.setAzimuthalAngle(phi)

    scan.setAlphaOffset(dalpha)

`alpha`, `lambda`, `phi` may also have distributions, then create them and assign to the scan:

    scan.setWavelengthDistribution(lambda_distr)
    scan.setGrazingAngleDistribution(alpha_distr)
    scan.setAzimuthalAngleDistribution(phi_distr)

Footprint can be assigned to the alpha scan (for specular and off-specular simulations).

    scan.setFootprint(footprint) # for specular & off-specular

### Lambda scans

To specify a scan with `n` equidistant points in the neutron/X-ray wavelength $\lambda$, use

    scan = ba.LambdaScan(n, lambda_start, lambda_stop)

To specify a scan with any other sequence of $\lambda$ values, use

    lambda_list = ba.ListScan("lambda (nm)", [0.6*nm, 0.61*nm, ... 0.7*nm]) # all points
    scan = ba.LambdaScan(lambda_list)

After constructing a scan, set the grazing angle and optionally the azimuthal angle using

    scan.setGrazingAngle(alpha)
    scan.setAzimuthalAngle(phi)

`alpha`, `lambda`, `phi` may also have distributions, then create them and assign to the scan:

    scan.setWavelengthDistribution(lambda_distr)
    scan.setGrazingAngleDistribution(alpha_distr)
    scan.setAzimuthalAngleDistribution(phi_distr)

Footprint can be assigned to the lambda scan (for specular and off-specular simulations).

    scan.setFootprint(footprint) # for specular & off-specular

Usage in off-specular scattering is demonstrated by Examples/specular/OffspecLambda.py .

See also the example page off-specular simulation.

### Qz scans

To specify a scan with `n` equidistant steps in the vertical wavenumber $q_z$, use

    scan = ba.QzScan(n, qz_start, qz_stop)

For other sequences of $q_z$ values, use the more generic

    qz_list = ba.ListScan("q_z (1/nm)", [0.01/nm, 0.02/nm, ... 1.2/nm]) # all points
    scan = ba.QzScan(qz_list)

A third alternative consists in passing a NumPy array,

    import numpy as np
    qz_vector = np.linspace(0.01, 1, n)
    scan = ba.QzScan(qz_vector)

After constructing a scan, a constant offset $\delta q_z$ can be set using

    scan.setOffset(dqz)

To specify q-resolution one needs at first create corresponding distribution `distr` but then there are three ways to specify a q-resolution.

1. Set absolute value of resolution, given in units of `1/nm`:

    scan.setAbsoluteQResolution(distr, dq)

2. Set relative value of resolution, given as fraction of $q_z$ value at each point of scan:

    scan.setRelativeQResolution(distr, dq_rel)

3. Set individual absolute value of resolution, given as vector of the same length `n`:

    dq_vector = 0.03*np.linspace(0.01, 1, n)  # dq-values in "1/nm"
    scan.setVectorResolution(distr, dq_vector)

As Qz scan does not contain full information about simulation geometry, it is incompatible with footprint.

`alpha`, `lambda`, `phi` and thair distributions cannot be set.

Usage is demonstrated in page time-of-flight reflectometry.

Handling of resolution will change soon. The current API is demonstrated in page time-of-flight reflectometry with resolution.

- Introduction
  - Functionality overview
  - Architectural overview

- Install or build
  - Install Python
    - Python on Linux
    - Python on Windows
    - Python on Mac
    - Python modules
  - Install BornAgain
    - Linux
    - Windows
    - MacOS
    - Development snapshot
  - Build BornAgain
    - Unix
      - Install third-party software
      - Get the source
      - Build and install BornAgain
      - Run a first simulation
    - Windows

- Graphical user interface
  - Quick Start
  - GUI overview
  - Fitting in the GUI

- Python scripting
  - Run a script
  - Understand the syntax
  - Fitting
  - Upgrading

- Reference
  - Simulation model
    - Simulation classes
      - Specular
        - Example
      - Scattering
        - Examples
          - GISAS
          - without DWBA terms
          - with specular peak
          - SAS
          - Polarized SANS
          - Monte-Carlo
      - Off-specular
        - Off-specular
      - Depth probe
        - Examples
          - Thin film
          - Transmitted modulus
          - Resonator
    - Common settings
      - Background
      - Options
        - Monte-Carlo
        - # threads
        - Average materials
        - Include specular
      - Progress monitor
  - Instrument model
    - Beam
      - Footprint
      - Beam divergence
    - Scan
      - TOF reflectometry
      - TOF resolution
      - Beam Angular Spread
      - Beam Wavelength Spread
    - Detectors
      - SphericalDetector
      - 2d detector resolution
      - Offspec detector
    - Neutron polarization
      - Spin asymmetry example
    - Examples
      - 2D detector resolution
      - Neutron polarization
        - Magnetic layer
        - Ditto, realistic instrument
        - Polarized scattering
  - Sample model
    - Materials
      - Magnetization
    - Sample
      - Layer
      - LayerStack
      - Layout
    - Roughness
      - Interface model
      - Transient
      - Cross-correlation
      - Examples
        - GISAS
        - Reflectivity
    - Particles
      - Form factor
        - Hard particles
          - Bipyramid4
          - Box
          - CantellatedCube
          - Cone
          - Cylinder
          - Dodecahedron
          - EllipsoidalCylinder
          - HemiEllipsoid
          - HorizontalCylinder
          - Icosahedron
          - PlatonicOctahedron
          - PlatonicTetrahedron
          - Prism3
          - Prism6
          - Pyramid2
          - Pyramid3
          - Pyramid4
          - Pyramid6
          - Sphere
          - SphericalSegment
          - Spheroid
          - SpheroidalSegment
          - TruncatedCube
        - Ripples
          - Bar ripple
          - Cosine ripple
          - Sawtooth ripple
        - Soft particles
          - FuzzySphere
          - Gauss
        - Custom formfactor
      - Composite particles
        - Core and shell
        - Compound particle
        - Mesocrystal
      - Examples
        - Compound particle
        - Core and shell
        - Crossing an interface
        - Mesocrystal
        - Rotation example
        - Dense cylinders
        - Dense hemispheres
        - Uncorrelated mixture
        - Polydispersity
    - Particle assemblies
      - Grating
        - 1D lattice
        - Cosine ripples in a lattice
        - Triangular ripples in a lattice
      - 2D lattice
        - Square lattice
        - Lattice orientation distribution
        - Finite square lattice
        - Lattice with basis
        - Multi-layer lattice
        - Position variance
      - Radial paracrystal
      - 2D paracrystal
      - Others
        - Size-distribution model: decoupling approximation
        - Size-distribution model: local monodisperse approximation
        - Size-distribution model: size-spacing coupling approximation
  - Model modifiers
    - Rotation
    - Distributions
  - Data types
    - Class Datafield
      - Export
      - Find intensity peaks
    - SLD profile
      - SLD profile with rough interfaces
      - SLD profile with a sliced particle layer
  - Plotting
    - Functions
    - Configuration
    - Heat map
    - LaTeX markup
    - Export
    - Plot axes in different units
  - Fitting
    - Data import
      - TIFF
    - Minimizer settings
    - Multiple datasets
    - Examples
      - Fitting with masks
      - Custom objective function
      - Fitting along slices
      - GISAS 2D fits
      - Experiment at GALAXI
      - Find background
      - Minimizer settings
      - Bayesian Sampling
      - Consecutive fitting
      - Considering uncertainties
      - External minimizer
      - External minimizer: plotting
      - Simultaneous fit of two datasets
      - Spin asymmetry fit example
      - Reflectometry: Fit Pt layer
      - Reflectometry: Fit honeycomb

- Literature
  - Babonneau2010
  - Babonneau2013
  - Croset2021
  - Lazzari2002
  - Lazzari2006
  - Pospelov2020
  - Renaud2009
  - Sears1992
  - Wuttke2021

- How to
  - Get announcements
  - Solve known problems
    - Set Python environmental variables under Windows
  - Request help or report bugs
  - Cite BornAgain

- Developers' corner
  - Configure
    - Build
    - Pyenv
  - Develop
    - Manual checks
    - Debug
    - Webdoc
    - Code analyses
  - Release
    - Manual GUI test