#### Setting Python environmental variables under Windows

With Python 3.10 in Conda or Pyenv platforms, the BornAgain GUI might crash when a Python script is imported. This problem is not observed with Python 3.11 or newer. Therefore, we recommend upgrading to a newer Python version `>= 3.11`.

If Python 3.10 is the preferred version, the Python-related environmental variables must be set manually before running the BornAgain GUI to avoid the crash.

To obtain the proper environmental variables, paste the following Python script into a file, say `ba_hint.py`:

    import os, sys

    SEP = '-' * 30
    py_exe = sys.executable
    py_root = os.path.realpath(os.path.dirname(py_exe))
    py_lib = os.path.realpath(os.path.dirname(os.__file__))

    print(SEP)
    print("* Python root: '{}'\n"
          "* Python exectuable: '{}'\n"
          "* Python lib dir: '{}'"
          .format(py_root, py_exe, py_lib))
    print(SEP)

    ba_msg = "* BornAgain %s installed in the current Python environment."
    try:
        import bornagain as ba
        print(ba_msg % "is")
    except Exception as ex:
        print(ba_msg % "is _not_")
        print(SEP)
        raise ex
    print(SEP)

    print("""\
    * Open a CMD.EXE shell and run the following commands before executing
      BornAgain GUI in the _same_ shell environment:
    """)

    print(f"""\
    set py_path={py_root:}
    set PATH=%py_path%;%PATH%
    set PYTHONPATH=%py_path%\Lib;%py_path%\DLLs;%py_path%\Lib\site-packages;%PYTHONPATH%
    """)
    print(SEP)

Open a `CMD.EXE` shell and run the script `ba_hint.py` with the preferred Python interpreter:

    python C:\path\to\ba_hint.py

The script finds the root path where the Python interpreter is installed and checks if BornAgain is installed as a Python package. If BornAgain is not installed, an error message will be displayed.

If BornAgain is installed in the Python environment, the scripts provides the correct environmental variables which must be set before executing the BornAgain GUI; for instance,

    ------------------------------
    * Python root: 'C:\conda\envs\py310'
    * Python exectuable: 'C:\conda\envs\py310\python.exe'
    * Python lib dir: 'C:\conda\envs\py310\Lib'
    ------------------------------
    * BornAgain is installed in the current Python environment.
    ------------------------------
    * Open a CMD.EXE shell and run the following commands before executing
      BornAgain GUI in the _same_ shell environment:

    set py_path=C:\conda\envs\py310
    set PATH=%py_path%;%PATH%
    set PYTHONPATH=%py_path%\Lib;%py_path%\DLLs;%py_path%\Lib\site-packages;%PYTHONPATH%

    ------------------------------

Notice that the paths might differ on each machine.

With the above instructions, BornAgain GUI can be executed via the following commands in a `CMD.EXE` shell; for instance:

    set py_path=C:\conda\envs\py310
    set PATH=%py_path%;%PATH%
    set PYTHONPATH=%py_path%\Lib;%py_path%\DLLs;%py_path%\Lib\site-packages;%PYTHONPATH%

    C:\path\to\BornAgain\bin\bornagain.exe

- 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