# Installation

## Operating system requirements

Ursa is regularly used on Mac OSX and native Linux. It is not expected to work on native Windows operating system because D-Claw will not run on native Windows. Installation is not reliable on Windows Subsystem for Linux (Ubuntu).

## Create environment 

Create environment with python 3.13 and a few dependencies better managed by conda rather than pip.

:::{Important}
The default configuration of ursa expects that the software was installed into an environment called `ursa-env`. Should you change the name of this environment, you **must** modify the {confval}`conda` configuration value. 
:::

We expect Ursa to work with python >= 3.11 and test that it builds with python 3.11, 3.12, and 3.13. We suggest that users create an environment with python 3.13 unless they have a specific reason to use a different python version. Finally, we install [ffpmeg](https://anaconda.org/conda-forge/ffmpeg) and [graphviz](https://anaconda.org/conda-forge/python-graphviz) here rather than with pip because we have found that the conda-forge distributions work better than those distributed by pip.

```bash
conda create -n ursa-env -c conda-forge python=3.13 python-graphviz ffmpeg
```

:::{note}
python-graphviz is used to make a snakemake diagnostic plot describing the ursa workflow and ffmpeg makes animations from the D-Claw simulations.
:::

## Get a fortran compiler
The only dependency that is not managed by this installation is a fortran compiler that works on your machine. On Mac OSX, one option is [Homebrew](https://brew.sh/).

```bash
brew install gcc
```

On native Linux or WSL this may be acomplished using [conda](https://anaconda.org/anaconda/conda), [apt-get](https://help.ubuntu.com/community/AptGet/Howto) or similar package management tools.

With conda:
```bash
conda install conda-forge::gcc
```

With apt-get:
```bash
apt-get install gcc
```

## Installation instructions

### Option 1: Pip installation from index url

:::{warning}
This method is not expected to work until the v1.0 release is finalized.
:::

To install directly from code.usgs.gov use the following command. This method does not require the user to have git installed on their computer.

```bash
pip install ursa --index-url  https://code.usgs.gov/api/v4/projects/10580/packages/pypi/simple
```

## Option 2: Poetry installation from source code

Clone the repository
```bash
git clone git@code.usgs.gov:ghsc/lhp/ursa.git
```

Next, activate the conda environment, install [poetry](https://python-poetry.org/docs/pyproject/), and install ursa

```bash
conda activate ursa-env
pip install poetry
cd ursa
poetry install
```

## Developer installation

If you anticipate modifing the ursa source code, follow [the developer guide](dev-guide). Most users will not fall in this category.

## Troubleshooting

Sometimes poetry/pip installation fails for some dependencies (or dependencies of dependencies) on WSL. If this occurs, usually installing the failed package with the following command and then returning to `poetry install` resolves the issue.

```bash
conda activate ursa-env
conda install <package-name>
```