> ## Documentation Index
> Fetch the complete documentation index at: https://spec2vec.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Install Spec2Vec and Set Up Your Python Environment

> Step-by-step guide to installing Spec2Vec's Python dependencies using conda or pip. Includes optional jax/jwave for acoustic modeling.

The recommended approach is to install Spec2Vec inside a dedicated conda virtual environment running Python 3.10. This keeps Spec2Vec's dependencies isolated from your system Python and from other projects, preventing version conflicts with packages like `numpy`, `numba`, or `jax`. The full installation takes around 3-5 minutes on a standard internet connection.

> [!WARNING]
>
> Always create and activate a fresh virtual environment before running any installation commands. Installing Spec2Vec's dependencies into your system Python or an existing environment can cause version conflicts that are difficult to diagnose and resolve.

## Alternative 1: Install using Requirements File

**1. Clone the repository**

Download the Spec2Vec source code to your local machine using Git.

```bash theme={null}
git clone https://github.com/URseismology/SPEC2VEC.git
cd Spec2Vec
```

\*\*2. Create a conda environment and install the related packages \*\*

Create a new conda environment named e.g. `spec2vec_env` with Python 3.10 (or above) and the core scientific stack. Then step by execute the following commands to build the environment for the Spec2Vec algorithm. 

```bash theme={null}
conda create -n spec2vec_env python=3.10.19
conda activate spec2vec_env
pip install numpy==2.2.5
pip install pyfastnoisesimd==0.4.2 --no-build-isolation
pip install -r software_requirements/spec2vec_requirements_hard.txt
pip install pyradiomics==3.0.1 --no-build-isolation
```

The [spec2vec\_requirements\_hard.txt](https://github.com/URseismology/Spec2Vec/blob/main/software_requirements/spec2vec_requirements_hard.txt) file contains pinned versions for every dependency, which guarantees a reproducible environment identical to the one used during development.

## Alternative 2: Install with [setup.sh](https://spec2vec.mintlify.site/installation.md#alternative-2-install-with-setup-sh-file) file (Recommended)

After cloning the Spec2Vec GitHub repository locally, you can run the provided [setup.sh](https://github.com/URseismology/Spec2Vec/blob/main/setup.sh) file to install the environment.

```bash setup.sh theme={null}
bash setup.sh
conda activate spec2vec_env
```

Note: Please update the environment name (as per your choice) and the hard requirements file path inside the bash script before proceeding.

## Alternative 3: Google Colab

Installing Spec2VEC in Google Colab provides a fast-track solution, allowing users to utilize its features immediately.

**1. Clone the repo in your google drive. (You might need to use a notebook)**

```text Colab Notebook theme={null}
from google.colab import drive
drive.mount('/content/drive')
%cd /content/drive/MyDrive/
!git clone https://github.com/URseismology/SPEC2VEC.git
```

**2. Open the notebook you want to work with and copy the following code block at the beginning of the file and run it. Please ignore any pip dependency resolver related warnings and restart session prompts.**

```text Colab Notebook theme={null}
# mount the google drive first
%cd /content/drive/MyDrive/
!pip install -r SPEC2VEC/software_requirements/spec2vec_requirements_google_colab.txt
!pip install git+https://github.com/Radiomics/pyradiomics
```

> [!WARNING]
>
> Note: While running the notebooks/scripts in google colab make sure to change the path variables as per google drive paths (e.g. /content/drive/MyDrive/SPEC2VEC/...) for seamless execution.
>
> Also note that the results may vary in google colab due library version differences.

## Verify Your Installation

Once the environment is active and dependencies are installed, confirm that the core pipeline class imports correctly.

```python theme={null}
from SPEC2VEC.utils.gisqa_compute_updated import GISQAPipeline
print("Spec2Vec ready")
```

If you see `Spec2Vec ready` printed without errors, your environment is set up correctly and you are ready to start extracting signal fingerprint features.

> [!NOTE]
>
> Always launch Jupyter or run Python scripts from the repository root directory (the `Spec2Vec/` folder you cloned). Spec2Vec uses package-relative imports such as `from SPEC2VEC.utils...`, and these resolve only when the repository root is present on your Python path. Launching from a subdirectory will produce `ModuleNotFoundError`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.