Installation (Checked: D)
=============================

.. toctree::
   :maxdepth: 1

Quick installation
------------------

It is recommended to install the package inside a dedicated Python
environment (for example a Conda or a Mamba environment) rather than in
the base system environment.

The minimal installation can be performed using ``pip``:

.. code-block:: bash

   (hofavenv) $ pip install hofa

This installs the HoFa package together with its required runtime
dependencies.

**Requirements:**

The package requires:

- Python >= 3.12

Core runtime dependencies include:

- NumPy >= 2.0
- SciPy >= 1.13

**Example using Conda:**

For a minimal installation with Conda, we first create a new virtual environment:

.. code-block:: bash

   (base) $ conda create -n hofavenv python=3.14
   (base) $ conda activate hofavenv

To install the core package dependencies:

.. code-block:: bash

   (hofavenv) $ pip install numpy scipy

To install the ``HoFa`` package:

.. code-block:: bash

   (hofavenv) $ pip install hofa

Optional: To install notebook-related dependencies:

.. code-block:: bash

   (hofavenv) $ pip install jupyterlab matplotlib moviepy

Optional: To install documentation dependencies:

.. code-block:: bash

   (hofavenv) $ pip install sphinx pydata-sphinx-theme sphinx-design sphinx-autoapi myst-nb

Installation from source
------------------------

Clone the repository:

.. code-block:: bash

   $ git clone https://github.com/dglez91/hofa
   $ cd hofa

Install the package in editable mode (assuming we have already acitvated a virtual environment ``hofavenv``):

.. code-block:: bash

   (hofavenv) $ pip install -e .


**Reproducible environment**

A reproducible Conda environment is provided through the
``full-environment.yml`` file.

Create the environment with:

.. code-block:: bash

   (base) $ conda env create -f full-environment.yml -n hofavenv

Activate the environment:

.. code-block:: bash

   (base) $ conda activate hofavenv

The environment includes:

- Runtime dependencies,
- Jupyter notebook support, and
- documentation dependencies.


**Jupyter notebooks**

HoFa includes example notebooks and user guides written in
Jupyter format. You can find them directly in this website using 
the following links:

- :doc:`first_tutorial`,
- :doc:`../user_guide/tutorial_denoising`, and
- :doc:`../user_guide/tutorial_high_order_characters`

or cloning the ``HoFa`` repository from Github as explained above. 
In the latter case, they are located in ``docs/source/tutorials``.

Additional notebook-related dependencies include:

- JupyterLab
- ipykernel

If the full Conda environment is installed as explained above, notebook support is already
included.

Launch JupyterLab with:

.. code-block:: bash

   (hofavenv) $ jupyter lab


**Building the documentation**

The documentation is built using Sphinx together with MyST-NB.

To build the HTML documentation:

.. code-block:: bash

   (hofavenv) $ cd docs
   (hofavenv) /docs$ make html

The generated HTML pages will appear in:

.. code-block:: text

   docs/build/html/