-[Testing the Installation](#testing-the-installation)
-[Installing Jupyter](#installing-jupyter)
-[Original Jupyter](#original-jupyter)
-[Alternative: Visual Studio Code](#alternative-visual-studio-code)
-[Notes on Third-party libraries](#notes-on-third-party-libraries)
## Introduction
**Note that you also need a working installation if you want to compile BoSSS from the C# sources yourself. BoSSS requires a set of prerequisites (e.g., Microsoft .NET or Mono, MPI, certain _native libraries_) on a machine, which are set up by the installation procedure outlined below.**
* (If links fail, please take a look at https://kummer.pages.rwth-aachen.de/bosss-public/ and search for `*.exe` or `*.run` - files)
We briefly outline the steps required to get started with using and/or developing BoSSS applications. **In any case**, the [installation](#installation) of the pre-compiled version of BoSSS should be the first step. Upon finishing this step, you can either use [BoSSSpad](/Getting-Started/BoSSSpad) to run pre-compiled applications as well as -- or -- you can start [working with the source code](/Getting-Started/Working-with-BoSSS-as-a-Developer).
## Installation
The advantage of C#, resp. .NET is that _the executable is platform-independent_. This implies e.g. that an executable compiled on a Windows/Mac laptop can be copied to a Linux/Unix HPC system and executed there without re-compilation. As discussed in the [Core Concepts](/Getting-Started/Core-concepts#c-Sharp,-.net-and-mono), this obviously requires some _middleware_ and some libraries to be present on the target computer. In the following, we will thus summarize some best practices for the installation of the [pre-compiled BoSSS binaries](#notes-on-third-party-libraries) on different operating systems.
~~is installed The BoSSS Installer checks whether these components are in place and installs them, if required. In the case of some problem, one can also download and install these items manually.~~
### Linux
The BoSSS group maintains basic packages of the [native libraries](#notes-on-third-party-libraries) listed in for Linux. These are compiled against recent versions of the Open MPI and the Intel MKL library and should provide compatibility and decent performance on a variety of systems. However, compatibility this can not guaranteed for any Linux distribution -- binary platform independence in Linux not possible in general; since we use Ubuntu, all Debian derivatives might most likely work. Note further, high-performance computers typically provide specifically optimized versions of BLAS and LAPACK, so for the ultimate performance on a certain system, you'll need to build your own version of the BoSSS native libraries.
The steps for installing BoSSS on Linux are:
1. Install .NET (`dotnet`), see at extensive [notes on the installation of
.NET](./NET6-Upgrade#installation-of-net-6-in-linux); In short: Download and install [.NET6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0), see also <https://docs.microsoft.com/de-de/dotnet/core/install/linux> for the most recent versions and best practices for your system.
[here](https://kummer.pages.rwth-aachen.de/bosss-public/ and search
`*.run` - files).
This installser will unpack the native libraries,
naemly the files `libBoSSSnative_seq.so`, `libBoSSSnative_omp.so` and `libBoSSSnative_mpi.so`.
4. Set the `BOSSS_INSTALL` environment variable to point to the directory
created in the prvious step.
The files `libBoSSSnative*.so` should be in the directory
`$BOSSS_INSTALL/bin/native/linux/amd64-openmpi`.
Note on Native libraries: If these pre-build libraries are not compatible with your system (we do our best, but binary compatibility across distributions is quite difficult on Linux), you will need to compile them yourself, the source code can be found at <https://github.com/FDYdarmstadt/BoSSS-native>, resp. <https://git.rwth-aachen.de/kummer/BoSSS-native>
### Mac OS X
Since Mac OS X is a Unix system, most things should work similar to Linux.
There has been, however, no interest so far for running BoSSS on Apple Computers, therefore we do not provide official guidelines.
**For any new Apple computer using an Apple Silicone chip
(M1, M2, i.e. some ARM-Mac)
one major obstacle for running BoSSS is that no PARDISO solver is available.
PARDISO is non-free software and its source code is not available;
binaries are, however available for older Macs (x86_64 architecture).**
The first step would be to compile the [Native Libraries](#notes-on-third-party-libraries). For this, we recommend that users should try either Mac Ports (<https://www.macports.org/>) or Homebrew (<https://brew.sh/>) to have a system which close to Linux (i.e. has `gcc`, `gfortran`, etc.). Using only Mac OS tools might be even harder. After you have compiled the library, you can proceed analogously to the procedure under Linux.
## Testing the Installation
Execute, after the installation the command
```plaintext
dotnet BoSSSpad.dll --check
```
or
```plaintext
BoSSSpad.exe --check
```
to verify that the installation works and the native libraries are in place. Furthermore, check that the environment variable `$BOSSS_INSTALL` is defined. The native libraries should be in the following location
* On Windows: `$BOSSS_INSTALL/bin/native/win/amd64`
* On Linux: `$BOSSS_INSTALL/bin/native/linux/amd64-openmpi`
If something fails one should first test that `dotnet` is working
For both components (runtime and SDK) at least some version 5.* is required.
## Installing Jupyter
To the time of writing, two alternatives for working with Jupyter notebook are available;
1. Using the original [**Jupyter Notebook **](https://jupyter.org/)(aka. Jupiterlab, Jupyter-Notebkook, etc.),
which runs in a web browser and requires a bunch of installation steps, [see below](#original-jupyter)
2. Using the respective plugins for [**Visual Studio Code**](https://code.visualstudio.com/),
which provides a [respective plugins](#alternative-visual-studio-code); this is maybe a bit easier,
but less mature.
### Original Jupyter
In order to use BoSSS properly, a working installation of [**Jupyter**](https://jupyter.org/)(aka. Jupiterlab, Jupyter-Notebkook, etc.) **with support for**[**dotnet-interactive**](https://github.com/dotnet/interactive) is required. Prior to the migration to .NET5, BoSSS used its own custom notebook format (`bws`, for BoSSS work sheet) and featured a notebook/worksheet editor embedded in [BoSSSpad](/Getting-Started/BoSSSpad). Since Mid-2020, [dotnet-interactive](https://github.com/dotnet/interactive) is supported by Jupyter and reached a level of maturity so that it can replace the custom BoSSSpad solution. Although a dependency on an additional software component is a drawback (e.g. the user has to install and configure it) the advantages of a widely-used of-the-shelf solution with a large user-basis such as Jupyter outweigh the disadvantages.
1. Ensure that a recent Python 3 distribution is installed on your system
- On Linux, one typically wants to use the package which ships with the
Linux distribution (e.g. `sudo apt-get install python3` on
[Debian](https://www.debian.org/) and derivatives like [Ubuntu](https://ubuntu.com/)
- For Windows, a a [Python 3 Installer](https://www.python.org/downloads/windows/)
is available.
- An alternative to the manual installation is the use of
You should also install [Papermill](https://papermill.readthedocs.io/en/latest/)
which is used to execute Jupyter notebooks in batch mode using
```
pip install papermill
```
(again, you might have to use `pip3` instead of `pip`)
3. The available kernels can be listed by `jupyter kernelspec list` in a python-aware terminal, e.g. Anaconda Prompt:
```plaintext
flori@Stormbreaker:~$ jupyter kernelspec list
Available kernels:
python3 /usr/local/share/jupyter/kernels/python3
```
4. Next, as non-elevated user (**not**`root`), `dotnet interactive` must be installed. Preferably (?) the [latest release](https://www.nuget.org/packages/Microsoft.dotnet-interactive/) via:
Especially if you installed `dotnet` in your local user account, e.g. if you are not using root/superuser priviliges, you might have to modify the path set the `DOTNET_ROOT`correctly in your in your `.bashrc`, where `xxxxxxx\` is the name of your home directory:
Navigate to the extension pane (left) and install two plugins; this can be done directly in VScode, (look for text field "Search Extensions in Marketplace"):
Thats all; Afterwards, you might try to use the **command palette** (`Ctrl+Shift+P`)
to execute the command "Jupyter: Create New Jupyter Notebook"
in order to try a simple Hello-World-example (e.g. `Console.WriteLine("Hello World!"`).
## Notes on Third-party libraries
The pre-compiled native library package already contains the following components:
* required BLAS and LAPACK functionality (from Intel MKL)
* Metis graph partitioning
* Direct sparse solver PARDISO (from Intel MKL)
* Direct sparse solver MUMPS
* Iterative sparse solver HYPRE
* Tecplot IO
* etc. (This list might not be complete and also might change)
-[Introduction](#introduction)
-[Installation](#installation)
-[Windows](#windows)
-[Linux](#linux)
-[Mac OS X](#mac-os-x)
-[Testing the Installation](#testing-the-installation)
-[Installing Jupyter](#installing-jupyter)
-[Original Jupyter](#original-jupyter)
-[Alternative: Visual Studio Code](#alternative-visual-studio-code)
-[Notes on Third-party libraries](#notes-on-third-party-libraries)
## Introduction
**Note that you also need a working installation if you want to compile BoSSS from the C# sources yourself. BoSSS requires a set of prerequisites (e.g., Microsoft .NET or Mono, MPI, certain _native libraries_) on a machine, which are set up by the installation procedure outlined below.**
* (If links fail, please take a look at https://kummer.pages.rwth-aachen.de/bosss-public/ and search for `*.exe` or `*.run` - files)
We briefly outline the steps required to get started with using and/or developing BoSSS applications. **In any case**, the [installation](#installation) of the pre-compiled version of BoSSS should be the first step. Upon finishing this step, you can either use [BoSSSpad](/Getting-Started/BoSSSpad) to run pre-compiled applications as well as -- or -- you can start [working with the source code](/Getting-Started/Working-with-BoSSS-as-a-Developer).
## Installation
The advantage of C#, resp. .NET is that _the executable is platform-independent_. This implies e.g. that an executable compiled on a Windows/Mac laptop can be copied to a Linux/Unix HPC system and executed there without re-compilation. As discussed in the [Core Concepts](/Getting-Started/Core-concepts#c-Sharp,-.net-and-mono), this obviously requires some _middleware_ and some libraries to be present on the target computer. In the following, we will thus summarize some best practices for the installation of the [pre-compiled BoSSS binaries](#notes-on-third-party-libraries) on different operating systems.
~~is installed The BoSSS Installer checks whether these components are in place and installs them, if required. In the case of some problem, one can also download and install these items manually.~~
### Linux
The BoSSS group maintains basic packages of the [native libraries](#notes-on-third-party-libraries) listed in for Linux. These are compiled against recent versions of the Open MPI and the Intel MKL library and should provide compatibility and decent performance on a variety of systems. However, compatibility this can not guaranteed for any Linux distribution -- binary platform independence in Linux not possible in general; since we use Ubuntu, all Debian derivatives might most likely work. Note further, high-performance computers typically provide specifically optimized versions of BLAS and LAPACK, so for the ultimate performance on a certain system, you'll need to build your own version of the BoSSS native libraries.
The steps for installing BoSSS on Linux are:
1. Install .NET (`dotnet`), see at extensive [notes on the installation of
.NET](./NET6-Upgrade#installation-of-net-6-in-linux); In short: Download and install [.NET6 SDK](https://dotnet.microsoft.com/download/dotnet/6.0), see also <https://docs.microsoft.com/de-de/dotnet/core/install/linux> for the most recent versions and best practices for your system.
[here](https://kummer.pages.rwth-aachen.de/bosss-public/ and search
`*.run` - files).
This installser will unpack the native libraries,
naemly the files `libBoSSSnative_seq.so`, `libBoSSSnative_omp.so` and `libBoSSSnative_mpi.so`.
4. Set the `BOSSS_INSTALL` environment variable to point to the directory
created in the prvious step.
The files `libBoSSSnative*.so` should be in the directory
`$BOSSS_INSTALL/bin/native/linux/amd64-openmpi`.
Note on Native libraries: If these pre-build libraries are not compatible with your system (we do our best, but binary compatibility across distributions is quite difficult on Linux), you will need to compile them yourself, the source code can be found at <https://github.com/FDYdarmstadt/BoSSS-native>, resp. <https://git.rwth-aachen.de/kummer/BoSSS-native>
### Mac OS X
Since Mac OS X is a Unix system, most things should work similar to Linux.
There has been, however, no interest so far for running BoSSS on Apple Computers, therefore we do not provide official guidelines.
**For any new Apple computer using an Apple Silicone chip
(M1, M2, i.e. some ARM-Mac)
one major obstacle for running BoSSS is that no PARDISO solver is available.
PARDISO is non-free software and its source code is not available;
binaries are, however available for older Macs (x86_64 architecture).**
The first step would be to compile the [Native Libraries](#notes-on-third-party-libraries). For this, we recommend that users should try either Mac Ports (<https://www.macports.org/>) or Homebrew (<https://brew.sh/>) to have a system which close to Linux (i.e. has `gcc`, `gfortran`, etc.). Using only Mac OS tools might be even harder. After you have compiled the library, you can proceed analogously to the procedure under Linux.
## Testing the Installation
Execute, after the installation the command
```plaintext
dotnet BoSSSpad.dll --check
```
or
```plaintext
BoSSSpad.exe --check
```
to verify that the installation works and the native libraries are in place. Furthermore, check that the environment variable `$BOSSS_INSTALL` is defined. The native libraries should be in the following location
* On Windows: `$BOSSS_INSTALL/bin/native/win/amd64`
* On Linux: `$BOSSS_INSTALL/bin/native/linux/amd64-openmpi`
If something fails one should first test that `dotnet` is working
For both components (runtime and SDK) at least some version 6.* is required.
## Installing Jupyter
To the time of writing, two alternatives for working with Jupyter notebook are available;
1. Using the original [**Jupyter Notebook **](https://jupyter.org/)(aka. Jupiterlab, Jupyter-Notebkook, etc.),
which runs in a web browser and requires a bunch of installation steps, [see below](#original-jupyter)
2. Using the respective plugins for [**Visual Studio Code**](https://code.visualstudio.com/),
which provides a [respective plugins](#alternative-visual-studio-code); this is maybe a bit easier,
but less mature.
### Original Jupyter
In order to use BoSSS properly, a working installation of [**Jupyter**](https://jupyter.org/)(aka. Jupiterlab, Jupyter-Notebkook, etc.) **with support for**[**dotnet-interactive**](https://github.com/dotnet/interactive) is required. Prior to the migration to .NET5, BoSSS used its own custom notebook format (`bws`, for BoSSS work sheet) and featured a notebook/worksheet editor embedded in [BoSSSpad](/Getting-Started/BoSSSpad). Since Mid-2020, [dotnet-interactive](https://github.com/dotnet/interactive) is supported by Jupyter and reached a level of maturity so that it can replace the custom BoSSSpad solution. Although a dependency on an additional software component is a drawback (e.g. the user has to install and configure it) the advantages of a widely-used of-the-shelf solution with a large user-basis such as Jupyter outweigh the disadvantages.
1. Ensure that a recent Python 3 distribution is installed on your system
- On Linux, one typically wants to use the package which ships with the
Linux distribution (e.g. `sudo apt-get install python3` on
[Debian](https://www.debian.org/) and derivatives like [Ubuntu](https://ubuntu.com/)
- For Windows, a a [Python 3 Installer](https://www.python.org/downloads/windows/)
is available.
- An alternative to the manual installation is the use of
You should also install [Papermill](https://papermill.readthedocs.io/en/latest/)
which is used to execute Jupyter notebooks in batch mode using
```
pip install papermill
```
(again, you might have to use `pip3` instead of `pip`)
3. The available kernels can be listed by `jupyter kernelspec list` in a python-aware terminal, e.g. Anaconda Prompt:
```plaintext
flori@Stormbreaker:~$ jupyter kernelspec list
Available kernels:
python3 /usr/local/share/jupyter/kernels/python3
```
4. Next, as non-elevated user (**not**`root`), `dotnet interactive` must be installed. Preferably (?) the [latest release](https://www.nuget.org/packages/Microsoft.dotnet-interactive/) via:
Especially if you installed `dotnet` in your local user account, e.g. if you are not using root/superuser priviliges, you might have to modify the path set the `DOTNET_ROOT`correctly in your in your `.bashrc`, where `xxxxxxx\` is the name of your home directory:
Navigate to the extension pane (left) and install two plugins; this can be done directly in VScode, (look for text field "Search Extensions in Marketplace"):
Thats all; Afterwards, you might try to use the **command palette** (`Ctrl+Shift+P`)
to execute the command "Jupyter: Create New Jupyter Notebook"
in order to try a simple Hello-World-example (e.g. `Console.WriteLine("Hello World!"`).
## Notes on Third-party libraries
The pre-compiled native library package already contains the following components:
* required BLAS and LAPACK functionality (from Intel MKL)
* Metis graph partitioning
* Direct sparse solver PARDISO (from Intel MKL)
* Direct sparse solver MUMPS
* Iterative sparse solver HYPRE
* Tecplot IO
* etc. (This list might not be complete and also might change)
Of course, you can compile the third-party libraries yourself, e.g. to replace the Intel MKL by some other BLAS/LAPACK distribution. But be aware that it is a tedious process! The source of those native libraries which are open source can be found at <https://github.com/FDYdarmstadt/BoSSS-native> resp. <https://git.rwth-aachen.de/kummer/BoSSS-native>. If you want to use other versions of certain libraries from their original maintainers, be aware that sometimes the API of those might change, which usually yields to a segmentation fault.
