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 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 and graphviz here rather than with pip because we have found that the conda-forge distributions work better than those distributed by pip.

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.

brew install gcc

On native Linux or WSL this may be acomplished using conda, apt-get or similar package management tools.

With conda:

conda install conda-forge::gcc

With apt-get:

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.

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

git clone git@code.usgs.gov:ghsc/lhp/ursa.git

Next, activate the conda environment, install poetry, and install ursa

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. 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.

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