Beginner Installation guide#

Installing Python with Miniconda#

To use HoFa, you first need to install Python, the programming language it is built on. Python relies on libraries (also called “packages”), which are like toolboxes containing pre-written code for specific tasks (e.g., math, data analysis, or visualization).

Managing these libraries can be complex, especially if you work on multiple projects. Miniconda is a tool that helps you create isolated environments (like separate workspaces) for your projects. Each environment can have its own set of libraries, making it easy to switch between projects without conflicts.

To install Miniconda, follow the official installation guide from Anaconda:

  1. Go to the Anaconda installation page.

  2. Select your operating system (Windows, macOS, or Linux).

  3. Download and install Miniconda (not Anaconda) using the provided instructions.

After installation, verify that Miniconda is working:

  • Windows: Click the Windows Start button (or press the Windows key), scroll to the Anaconda (Miniconda3) folder in the program list, and open the Anaconda Prompt. Then run:

(base) C:\some\url> conda --version

  • macOS/Linux: Open Terminal and run:

your@user:~$ conda --version

In either case, if the command returns a version number (e.g., conda 24.x.x), Miniconda is installed correctly.

Creating a Python Environment for HoFa#

Now that you have Miniconda installed, let’s set up a dedicated workspace (called an environment) for HoFa. Think of this workspace as a clean, isolated desk where you can organize all the toolboxes (libraries) you need for your project, without affecting other projects.

Step 1: Create a New Environment#

We will create a new environment named hofavenv with Python 3.14 (or the latest stable version). This is like setting up a new desk for your project. Execute the following commands (in either Windows/Linux/macOS) to create a new environment.

conda create -n hofavenv python=3.14

  • conda create -n hofavenv: Creates a new environment named hofavenv. You may choose any name here except base, which is reserved.

  • python=3.14: Specifies the Python version to use (in this case, we have fixed 3.14).

Now we need to activate the environment, which will allow us to work with it. To do so, execute the following line (in either Windows/Linux/macOS):

conda activate hofavenv

Note that now you will see a (hofavenv) at the beginning of your terminal command line. This means that the environment is correctly activated and we can start working with it.

Step 2: Install Core Dependencies#

Important

Verify that the virtual environment hofavenv is activated, i.e. you see at the beginning of your terminal (hofavenv). Otherwise, go back to the previous steps.

Now, let us add the essential toolboxes (libraries) required for HoFa to work. These are like the basic tools you need on your desk. To install them, execute:

pip install numpy scipy

  • numpy and scipy: Libraries for numerical and scientific computing.

Step 3: Install HoFa#

Now, install the HoFa package itself, which is the main tool you’ll be using.

pip install hofa

Optional Steps#

For Notebook Users#

If you plan to use Jupyter Notebooks (interactive coding environments), install these additional toolboxes. Jupyter Notebooks are interactive coding environments that allow you to write and execute code in a web browser, making it easy to experiment, visualize results, and document your work.

pip install jupyterlab matplotlib moviepy

  • jupyterlab: An interactive environment for coding.

  • matplotlib: A library for creating plots and visualizations.

  • moviepy: A library for video editing and processing.

From the HoFa website, you can download example notebooks to test the capabilities of HoFa and explore its features interactively.

To launch JupyterLab execute the following:

jupyter lab

This will open a new tab in your default web browser. From there, you can:

  1. Navigate to the folder where your notebooks are stored.

  2. Click on a notebook file (e.g., .ipynb) to open it.

  3. Start coding in the interactive cells!

For Documentation Builders#

If you want to build or contribute to the documentation, install these toolboxes:

pip install sphinx pydata-sphinx-theme sphinx-design sphinx-autoapi myst-nb

These libraries help generate and style the documentation.

To compile the documentation locally:

  1. Navigate to the docs folder in your HoFa repository.

  2. Run the following command:

    make html

This will generate the documentation in HTML format, which you can view in your browser.

Useful Resources#