webdoc: bundle Py installation instructions (#707)

hugo/content/installation/_index.md

@@ -7,10 +7,13 @@ weight = 20
 
 BornAgain is supported under the operating systems Linux, Windows, and Mac OS X.
 
+BornAgain (unless specially build for GUI only)
+requires Python3 and a number of Python modules. See the [Install Python](py) section.
+
 For each of these, we provide self-contained binary installers,
-as described in the [Install](install) section.
+as described in the [Install BornAgain](install) section.
 
 For Linux, it may be even more convenient to use the Debian/Ubuntu package
 provided by external maintainers at https://tracker.debian.org/pkg/bornagain.
 
-See the [Build](building) section to compile BornAgain from source.
+See the [BuildnAgain](building) section to compile BornAgain from source.

hugo/content/installation/building/_index.md

 +++
-title = "Build"
+title = "Build BornAgain"
 weight = 20
 +++
 

hugo/content/installation/building/unix/third-party.md

@@ -5,7 +5,12 @@ weight = 10
 
 ## Install third-party software
 
-Required software:
+As a prerequisite, Python and some Python modules must be installed.
+For the recommended installation under pyenv, see
+* [Python on Linux](/installation/py/linux).
+* [Python on Mac](/installation/py/mac).
+
+Further required software:
 
 * Compiler with basic C++-20 support (`gcc` or `clang`)
 * `cmake >= 3.20`
@@ -13,23 +18,14 @@ Required software:
 * `fftw3 >= 3.3.1` (fast Fourier transform)
 * `libtiff >= 4.0.2` (TIFF image loader)
 * `libcerf >= 2.0` (complex error function) [1]
-* `python3 >= 3.8`
-* `python3-dev`
-* `python3-pip` (to be removed, https://jugit.fz-juelich.de/mlz/bornagain/-/issues/682)
-* `python3-numpy` [2]
-* `python3-matplotlib` [2]
-* `python3-lmfit` (optional, for some fit scripts) [2]
-* `boost >= 1.65` [3]
+* `boost >= 1.65` [2]
 * `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] Python modules may be installed either as Linux distribution
-packages or through the Python package manager `pip3`.
-
-[3] From libboost, we need the library components `iostreams` and `program_options`.
+[2] From libboost, we need the library components `iostreams` and `program_options`.
 Internally, the CMake command to find `boost::iostreams` may add a dependence
 on `boost::regex`. Furthermore, we need a number of header-only components,
 including `algorithm/string`, `bimap`, `geometry`, `numeric/interval`, `polymorphic_cast`.

hugo/content/installation/building/windows/index.md

@@ -39,19 +39,8 @@ Download the **Windows x64 Installer** from the official website [cmake.org/down
 
 #### Python + Packages
 
-Next up, download Python 3.9. For that, go to [python.org/downloads/](https://www.python.org/downloads), look for **Python 3.9.x** and download the **Windows installer (64-bit)**. Follow the setup and make sure to add Python to `PATH`.
-
-Once Python is set up correctly, install `numpy`. Therefore open a PowerShell and type the command:
-
-```
-py -m pip install numpy
-```
-
-Analogously install `matplotlib` with
-
-```
-py -m pip install matplotlib
-```
+Python and some Python modules must be installed, as described in
+[Python on Windows](/installation/py/win).
 
 #### NSIS (for packaging only)
 

hugo/content/installation/install/_index.md

 +++
-title = "Install"
+title = "Install BornAgain"
 weight = 10
 +++
 

hugo/content/installation/install/linux.md

@@ -10,21 +10,17 @@ weight = 30
 ##### Python
 
 As a prerequisite, Python must be installed.
-Check the version with `python3 --version`.
-Which versions are compatible with BornAgain
-can be inferred from the available installers at {{% files-versioned %}}/linux_x64.
-
-In the following, we assume that `python` is an alias for `python3`.
+For the recommended installation under pyenv, see [Python on Linux](/installation/py/linux).
 
 ##### glibc
 
 Our BornAgain binaries (pip package and installer) are built on Debian 11 and require [glibc](https://www.gnu.org/software/libc) version 2.31 or higher.
 
-To see which glibc version is available on your system, run 
+To see which glibc version is available on your system, run
 ```
 $ ldd --version
 ```
-Versions for other Linux distributions can be seen at 
+Versions for other Linux distributions can be seen at
 https://repology.org/project/glibc/versions
 
 ### Installation methods

hugo/content/installation/install/macos.md

@@ -7,23 +7,7 @@ weight = 70
 
 #### Prequisite: Python
 
-As a prerequisite, Python must be installed.
-
-Note that pre-installed Python on MacOS may be outdated.
-Check the installed version with `python3 --version`.
-Which versions are compatible with BornAgain
-can be inferred from the available installers at
-  * {{% files-versioned %}}/mac_arm or
-  * {{% files-versioned %}}/mac_x64.
-
-The official Python installers can be downloaded from https://www.python.org/downloads.
-
-Or use Homebrew:
-```
-$ brew install python3
-```
-
-In the following, we assume that `python` is an alias for `python3`.
+As a prerequisite, Python must be installed, see [Python on Mac](/installation/py/mac).
 
 #### Install BornAgain as Python-only package
 

hugo/content/installation/install/windows/python-troubleshooting/index.md → hugo/content/installation/install/windows.md

 +++
-title = "Python troubleshooting"
-weight = 30
+title = "Windows"
+weight = 50
 +++
 
-## Python troubleshooting
+## Install on Windows
 
-The following checklist can be useful to tackle possible causes of the problem.
+#### Install Python environment
+
+As a prerequisite, Python must be installed, see [Python on Windows](/installation/py/win).
+
+#### Install BornAgain as a Python package
+
+To install BornAgain as a pure Python package (for scripting only, no GUI),
+download and install the latest BornAgain Python wheel from the [PyPI](https://pypi.org) repository:
+```
+$ python -m pip install bornagain
+```
+
+#### Install full BornAgain (GUI and scripting)
+
+To install full BornAgain (GUI app and Python module),
+download an installer from {{% files-versioned %}}.
+The installer should be chosen accordingly to the Python minor version installed on the
+destination machine, for example `{{% recommended-wininstaller %}}`.
+
+After downloading the installer,
+double click the `.exe` file and follow the instructions on the screen.
+
+{{< figscg src="/img/bornagainapp_32.png" class="float-left">}}
+
+Use the BornAgain icon located on the desktop to start the GUI.
+Refer to [Using graphical user interface]({{% relref "gui" %}})
+section for a basic overview of GUI functionality.
+
+### Troubleshooting
+
+Frequent problems include the following:
 
 * [BornAgain.exe cannot start]({{% relref "#dll-not-found" %}})
 * [How many Python distributions are installed on the system?]({{% relref "#how-many-python" %}})
 * [Does the Python interpreter version matches the BornAgain installation?]({{% relref "#does-interpreter-match" %}})
 
-<hr>
-
 #### BornAgain.exe cannot start
 {{% anchor "dll-not-found" %}}
 
-{{< figscg src="dll_not_found.png" class="center" width="450px">}}
+{{< figscg src="/img/win_dll_not_found.png" class="center" width="450px">}}
 
 This message appears on running `BornAgain.exe` if BornAgain cannot find Python libraries.
 
@@ -25,15 +53,13 @@ If Python is correctly installed on the system according to [Install Python envi
 $ python
 ```
 If Python interpreter has not started, then its installation directory is not in system `PATH`.
-Open 
+Open
 
-`Edit the system environment variables` -> `Environment variables` -> `System variables` -> `Path` -> `Edit` 
+`Edit the system environment variables` -> `Environment variables` -> `System variables` -> `Path` -> `Edit`
 
 and add Python installation directory to the end
 
-{{< figscg src="path.png" class="center" width="450px">}}
-
-<hr>
+{{< figscg src="/img/win_path.png" class="center" width="450px">}}
 
 #### How many Pythons are installed on the system?
 {{% anchor "how-many-python" %}}
@@ -42,13 +68,11 @@ Having more than one Python interpreter installed on the system may cause subtle
 Managing their co-existence is possible, but may require special skills.
 It may be preferable to uninstall all Python versions but one.
 
-<hr>
-
-#### Does the Python interpreter version matches the BornAgain installation?
+#### Does the Python interpreter version match the BornAgain installation?
 {{% anchor "does-interpreter-match" %}}
 
 BornAgain is a `64-bit` application and requires a `64-bit` Python3 installed on the system.
 
-The Python version number, indicated in the BornAgain installer name
+The Python version number (major.minor), indicated in the BornAgain installer name
 (e.g. `{{% recommended-wininstaller %}}`) must
 match the Python installation on your system.

hugo/content/installation/install/windows/_index.md

-+++
-title = "Windows"
-weight = 50
-+++
-
-## Install on Windows
-
-BornAgain GUI application for Windows is provided as 64-bit installer; it requires Python libraries to be installed on the system for being run.
-
-BornAgain Python package is available in PyPI repository and can be installed with `pip`. This package is required for running scripts or importing them into the GUI application.
-
-To install and run BornAgain for the first time proceed with the following steps:
-
-- [Install Python environment](#install-python-environment)
-- [Install BornAgain Python package](#install-bornagain-python-package)
-- [Install BornAgain GUI application](#install-bornagain-gui-application)
-- [Troubleshooting](#troubleshooting)
-
-### Install Python environment
-
-{{< alert theme="info" >}}
-If Python environment is already installed and set up, this block can be skipped.
-{{< /alert >}}
-
-Python environment is needed for running both GUI application and example scripts.
-The installer for appropriate version of Python can be downloaded from https://www.python.org/downloads.
-
-BornAgain supports Python versions from 3.8 to 3.11.
-
-Run the installer and follow the steps.
-
-To use BornAgain GUI application, the installation directory should be added to the system `PATH`:
-
-{{< figscg src="add_to_PATH.png" class="center" width="450px">}}
-
-Ensure that `pip` package manager is checked for installation. Command
-```
-$ python -m ensurepip
-```
-will install `pip` if it is missing.
-
-#### BornAgain with Anaconda
-
-With Anaconda Python the requirements for versions 3.8 and 3.9 are more restrictive:
-
-compatibility is confirmed for Python 3.8.x>=3.8.15 and for 3.9.x>=3.9.15
-
-### Install BornAgain Python package
-
-{{< alert theme="info" >}}
-For using BornAgain as GUI application only, this block can be skipped.
-{{< /alert >}}
-
-BornAgain Python package in available in the public repository and can be installed with `pip`:
-```
-$ python -m pip install bornagain
-```
-
-### Install BornAgain GUI application
-
-{{< alert theme="info" >}}
-For using BornAgain in scripts only, this block can be skipped.
-{{< /alert >}}
-
-BornAgain installation package can be downloaded from
-{{% files-versioned %}}.
-The installer should be chosen accordingly to the Python version installed on the
-destination machine, for example `{{% recommended-wininstaller %}}`.
-
-After downloading the installer,
-double click the `.exe` file and follow the instructions on the screen.
-
-{{< figscg src="/img/bornagainapp_32.png" class="float-left">}}
-
-Use the BornAgain icon located on the desktop to start the GUI.
-Please refer to [Using graphical user interface]({{% relref "gui" %}})
-section for a basic overview of GUI functionality.
-
-### Troubleshooting
-
-If you are experiencing problems while running BornAgain Python scripts please refer to the following tutorial.
-
-+ [Python troubleshooting]({{% relref "installation/install/windows/python-troubleshooting" %}}).

hugo/content/installation/py/_index.md

++++
+title = "Install Python"
+weight = 5
++++
+
+## Install Python and Python modules
+
+BornAgain requires Python3 and a number of Python modules.
+
+The only exception is if BornAgain has been specially built
+with the flag `BORNAGAIN_PYTHON=OFF`, which results in a GUI app
+that has no support for import or export of Python scripts.
+
+Therefore, before [installing](/installation/install) or [building](/installation/building)
+BornAgain, install Python following these operating-system specific instructions:
+
+  * [Python on Linux](linux)
+  * [Python on Windows](win)
+  * [Python on Mac](mac)
+
+Then, install the
+  * [Python modules](modules)
+required by BornAgain.

hugo/content/installation/py/linux.md

++++
+title = "Python on Linux"
+weight = 10
++++
+
+## Install Python on Linux
+
+Any Linux distribution (Debian/Ubuntu, Fedora, etc) provides packages
+for Python and for many Python modules. This approach, however, runs into
+difficulties if one needs Python modules that are _not_ available in the
+distribution. Installing them using the Python package manager Pip can
+cause inconsistencies and break the system. Therefore, distributions at
+some point (e.g. Debian 12) disabled Pip, which terminates with
+`error: externally-managed-environment`. While this behavior can be
+overridden by a special flag, we advise against.
+
+Rather, we recommend escaping from Python version hell by using the
+Python version manager [pyenv](https://github.com/pyenv/pyenv).
+
+Prepare the shell by adding
+```
+export PYENV_ROOT="$HOME/.pyenv"
+command -v pyenv >/dev/null || export PATH="$PYENV_ROOT/bin:$PATH"
+eval "$(pyenv init -)"
+```
+to `~/.bashrc` (or whatever startup configuration file), and
+restart the shell.
+
+Then:
+```bash
+# install pyenv
+curl https://pyenv.run | bash
+
+#install Python
+pyenv install {{% recommended-python %}}
+pyenv global {{% recommended-python %}}
+which python # shows path in virtual environment
+
+#install Python modules
+pip install numpy
+```
+etc.
+For the full list of modules required by BornAgain, see the [modules](modules) page.

hugo/content/installation/py/mac.md

++++
+title = "Python on Mac"
+weight = 30
++++
+
+## Install Python on Mac
+
+The pre-installed Python on MacOS may be outdated,
+and may be in conflict with external module requirements.
+Therefore we strongly recommend to install Python and the Python module manager Pip
+from scratch.
+
+The preferred installation method is using Conda.
+
+If there is a need to switch between different Python versions,
+the Python version manager [pyenv](https://github.com/pyenv/pyenv)
+may be preferred (see [Python on Linux](/installation/py/linux)).
+
+#### Conda
+
+....

hugo/content/installation/py/modules.md

++++
+title = "Python modules"
+weight = 80
++++
+
+## Python modules required by BornAgain
+
+
+The BornAgain GUI (unless specially built without Python support)
+requires the Python module
+  * numpy
+
+All BornAgain Python scripting examples require
+* matplotlib
+
+Furthermore, a small number of fit script examples require the Python modules
+  * corner
+  * emcee
+  * lmfit
+  * scipy
+  * tqdm
+These are not required for _installing_ and _running_ most of BornAgain.
+However, they should be present when _building_ BornAgain
+lest some tests will fail.

hugo/content/installation/py/win.md

++++
+title = "Python on Windows"
+weight = 20
++++
+
+## Install Python on Windows
+
+Currently, BornAgain requires Python version between 3.8 and 3.11.
+
+Run the installer and follow the steps.
+
+To use BornAgain GUI application, the installation directory should be added to the system `PATH`:
+
+{{< figscg src="/img/win_add_to_PATH.png" class="center" width="450px">}}
+
+Ensure that `pip` package manager is checked for installation. Command
+```
+$ python -m ensurepip
+```
+will install `pip` if it is missing.
+
+#### BornAgain with Anaconda
+
+With Anaconda Python the requirements for versions 3.8 and 3.9 are more restrictive:
+
+compatibility is confirmed for Python 3.8.x>=3.8.15 and for 3.9.x>=3.9.15

hugo/hugo.toml

@@ -25,6 +25,7 @@ PygmentsStyle = "vs"
 
   recommended_python_major = "3"
   recommended_python_minor = "11"
+  recommended_python_patch = "2"
 
   # for links to source repository
   url_blob = "https://jugit.fz-juelich.de/mlz/bornagain/-/blob/v21.0"

hugo/layouts/shortcodes/recommended-python.html

-{{.Site.Params.recommended_python_major}}.{{.Site.Params.recommended_python_minor}}
+{{.Site.Params.recommended_python_major}}.{{.Site.Params.recommended_python_minor}}.{{.Site.Params.recommended_python_patch}}{{- print "" -}}