.. highlight:: shell

.. _app_installation:

************
Installation
************

Generating hexagon shapefiles is a requirement to generate spatial networks by SHoBNetPy and involves
an `QGIS <https://www.qgis.org/>`_ installation. QGIS is not needed in case hexagon shapefiles have already
been produced for the simulation are and are available for network generation.
 

Stable release (not yet supported)
==================================

To install SHoBNetPy, run this command in your terminal:

.. code-block:: console

    $ pip install shobnetpy

This is the preferred method to install SHoBNetPy, as it will always install the most recent stable release.

If you don't have `pip`_ installed, this `Python installation guide`_ can guide
you through the process.

.. _pip: https://pip.pypa.io
.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/


Install most recent version from Gitlab
=======================================

You may also install the latest development of SHoBNetPy from the gitlab directly:

.. code-block:: console

    $ pip install git+https://gitlab.uni-kassel.de/ines/shobnetpy.git
    


From sources
============

The sources for SHoBNetPy can be downloaded from the `Gitlab repo`_.

You can either clone the public repository:

.. code-block:: console

    $ git clone https://gitlab.uni-kassel.de/ines/shobnetpy


Once you have a copy of the source, you can install it with:

.. code-block:: console

	$ cd <path to shobnetpy git project>
	$ python setup.py install
    
or alternatively

.. code-block:: console

	$ cd <path to shobnetpy git project>
	$ pip install -e .

.. _Gitlab repo: https://gitlab.uni-kassel.de/ines/shobnetpy

.. _app_configuration:

**********************
Configuration
**********************

To make same basic settings and specify important path, editing a configuration `toml` file is necessary.
Switch to the directory your model resides in, or you want SHoBNetPy files for the model to be. Then 
start the python interpreter:

.. code-block:: sh
	python
	
A template and an appropriate file structure can be obtained by executing the following python code:

.. code-block:: python

	import shobnetpy as sn
	sn.prepare(<working directory>)
	
Passing the `<working directory>` is optional. If not present, `shobnetpy` will install the files in the
subfolder `shobnetpy` within the user's home directory.

Then navigate to `<working directory>/input` and edit `settings.toml`:

.. code-block:: toml

	[main]
	output_dir = "shobnetpy/output"
	project = "Example"
	task = "TaskA"
	scenario_id = 1
	runid = 0
	input_path = "@none"
	output_path =  "@format {this.main.output_dir}/{this.main.project}"
	qgis = "@none"
	qt5 = "@none"

See inside `settings.toml` or :ref:`app_concepts_configuration_settings` for explanations about settings.

Settings `qgis` and `qt5` are required for hexagon creation and need to specify the path to
according python packages. Examples for two operating systems:

========= ===================================================================== ==========
\         Windows   													        Linux
========= ===================================================================== ==========
`qgis`    `C:\\Program Files\\QGIS 3.36.2\\apps\\qgis\\python`  				`/usr/lib/python3/dist-packages`
`qt5`     `C:\\Program Files\\QGIS 3.36.2\\apps\\Python312\\Lib\\site-packages`	`/usr/lib/python3/dist-packages` 
========= ===================================================================== ==========

The lcoation of `settings.toml` can also be assigned to the 
environmental variable `SN_SETTINGS_FILE_FOR_DYNACONF`.

In `./input` you also find a file `config_logging.conf` to control logging of SHoBNetPy.


**********************
Test the configuration
**********************

You can use one of the :ref:`app_examples` to check whether the plugin works at your machine.