# Installation

(installation)=

We have rigorously designed the package to have a light dependency footprint to keep the package as portable as possible.
*sqsgenerator* can be used in three different ways

- **Web Assembly**: a multi-threaded web-assembly module of *sqsgenerator* with JS bindings.
  browser
- **Python package**: the python package comes with a command line interface (CLI) and a Python API
- **Native application**: a compiled binary that can be used on high-performance computing (HPC) where Python might not
  be available at all. This is the way to go if you want to use *sqsgenerator* in large scale using MPI. You can


## Web Assembly

Just open [sqsgen.gehringer.tech](https://sqsgen.gehringer.tech) in your browser and start using *sqsgenerator* right away.


## Python package
(python-installation)=

the python package comes with a command line interface (CLI) and a Python API. The python packages' API
can be used to analyse the output generated by the native application and web-application also.

### from `pip`
(pip-installation)=

You can install the latest release of *sqsgenerator* from [PyPI](https://pypi.org/project/sqsgenerator/) using `pip`:

```bash
pip install sqsgenerator
```

Pre-built wheels are available for Linux (x86-64, aarch64), MacOS (universal2), and Windows (amd64). Currently supported
Python versions are 3.9 - 3.13.

### from `conda`
(conda-installation)=
You can install *sqsgenerator* from the [conda-forge](https://anaconda.org/conda-forge/sqsgenerator) channel using `conda`:

```bash
conda install -c conda-forge sqsgenerator
```

On conda for version >= 0.4 we support Linux (x86-64), MacOS (x86-64, arm64), and Windows (amd64). Currently supported
Python versions are 3.9 - 3.13.

### from source
(source-python-installation)=


#### Python
A Python interpreter 3.9+ is required. To build the bindings

#### C++ toolchain
(cpp-toolchain)=

The core of *sqsgenerator* is written in C++. Therefore, a C++ compiler with support for C++20 standard is required.
We have tested compilation across different platforms with the following compilers:
vcpkg is used to manage the dependencies

- Git
- CMake (3.25+)
- C++20 compatible compiler
  - Linux
      - g++ (13+)
      - clang++ (19.0+)
  - MacOS
      - Apple clang++* (15.0+)
  - Windows
      - MSVC (19.29+)



#### Build instructions

If you want to install the package directly into your current Python environment, you can use the following commands

:::{code-block} bash
git clone --recursive https://github.com/dgehringer/sqsgenerator.git
cd sqsgenerator
pip install python/ -v
:::

to build a wheel file, use the following commands

:::{code-block} bash
git clone --recursive https://github.com/dgehringer/sqsgenerator.git
cd sqsgenerator
pip install build
python -m build python/ --wheel -v
:::

The wheel file can be found in the `python/dist` folder and can be installed using `pip install python/dist/sqsgenerator-*.whl`.


### shell completion

*sqsgenerator* uses [*pallets/click*](https://github.com/pallets/click) to implement its CLI. *click* supports
automatically generated shell completion. A guide on how to enable shell completion for your shell can be found
in the [click documentation](https://click.palletsprojects.com/en/stable/shell-completion/)


## Native application
(native-installation)=

Ensure you have installed the {ref}`C++ toolchain <cpp-toolchain>` as described above. For building the native application
no Python interpreter is required. Most likely you will want to use MPI when choosing the native application.

:::{code-block} bash
git clone --recursive https://github.com/dgehringer/sqsgenerator.git
cd sqsgenerator
./scripts/build-cli-mpi.sh build
:::

This will create a `build` folder containing the compiled binary `sqsgen` folder. Please run the script from the
root folder of the repository. You can specify a different build folder by changing the second argument of the script.
Feel free to modify the script to your needs e.g. to change the compiler CMake flags
(`DCMAKE_CXX_COMPILER` or `DCMAKE_C_COMPILER`) accordingly.