## Install third-party software

As a prerequisite, Python and some Python modules must be installed. For the recommended installation under pyenv, see

- Python on Linux.
- Python on Mac.

Further required software:

- Compiler with basic C++-20 support (`gcc` or `clang`)
- `cmake >= 3.20`
- `gsl >= 1.15` (GNU scientific library)
- `fftw3 >= 3.3.1` (fast Fourier transform)
- `libtiff >= 4.0.2` (TIFF image loader)
- `libcerf >= 3` (complex error function) [1]
- `boost >= 1.74` [2]
- `zlib1g-dev >= 1.2.11` (zlib compression library)
- `bzip2 >= 1.0.8` (bzip2 compression library)
- `Qt6`

[1] The library `libcerf` happens to be maintained by our own group. Nonetheless it is treated as an external dependency because packages are provided by all major Linux distributions (see https://pkgs.org).

[2] From `libboost`, we only need three header-only components, `format`, `bimap`, and `geometry`.

Recommended software:

- For generating a man page:
  - `perl`
- For MatPlotLib usetex mode:
  - `texlive-latex-extra` (and dependencies)
  - `dvipng`
  - `cm-super-minimal`

All these can be easily installed on most Linux distributions using the system’s package manager. Below are a few examples for several selected operating systems. Note that other distributions (Fedora, Mint, etc) may have different commands for invoking the package manager and slightly different names of packages (like `boost` instead of `libboost` etc). Besides that, the installation should be very similar.

### Debian / Ubuntu / …

Install required packages:

    $ sudo apt-get install build-essential git cmake \
      libgsl-dev libfftw3-dev libtiff5-dev \
      libboost-dev \
      libcerf-dev qt6-base-dev qt6-svg-dev mesa-common-dev

If CMake fails with “Could NOT find OpenGL”, then install `libgl1-mesa-dev`. If it fails with “Could NOT find OpenGL (missing: EGL)”, then install `libegl1-mesa-dev`.

We assume that Python is installed under pyenv; otherwise we also need the packages

      python3 python3-dev python3-pip python3-numpy python3-matplotlib python3-lmfit

Note: Normally we should also depend on `libcerf-dev`, which however is presently outdated. Therefore Debian users should install libcerf from source, https://jugit.fz-juelich.de/mlz/libcerf.

### OpenSuse

Install required packages:

    $ sudo zypper install gcc-c++ git-core cmake gsl-devel \
      libboost_*-devel fftw3-devel libcerf-devel libtiff-devel \
      libqt6-qtbase-devel libqt6-qttools-devel libqt6-qtsvg-devel

We assume that Python is installed under pyenv; otherwise we also need the packages

      python3-devel python3-pip \
      python3-numpy-devel python3-matplotlib python3-lmfit

### MacOS

To install third-party dependencies on MacOS, we recommend using the package manager Homebrew:

    brew install git cmake fftw gsl libcerf python boost libtiff zlib bzip2 qt6
    pip3 install matplotlib numpy

By default, Homebrew installs packages to `/opt/homebrew` or `/usr/local`, depending on the architecture and MacOS version. The Homebrew installation directory can be obtained via the command:

    $ brew --prefix

Possibly, this path has to be passed to CMake using the argument `-DCMAKE_PREFIX_PATH` (see the build instructions.

Add Qt to your path environment variable:

    export PATH=/usr/local/opt/qt6/bin/:$PATH

- 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