From ee39a0feeb95743eb9e0456654f326e0de088438 Mon Sep 17 00:00:00 2001 From: TimoDiepers Date: Thu, 20 Feb 2025 08:16:14 +0100 Subject: [PATCH] update installation instructions --- docs/content/installation.md | 75 ++++++++++++++++++++++++++++++------ 1 file changed, 63 insertions(+), 12 deletions(-) diff --git a/docs/content/installation.md b/docs/content/installation.md index 5da5919..c788376 100644 --- a/docs/content/installation.md +++ b/docs/content/installation.md @@ -1,17 +1,16 @@ # Installation -`bw_timex` is a Python software package. It's available via [`pip`](https://pypi.org/project/pip/) or [`conda`](https://docs.conda.io/en/latest/) / [`mamba`](https://mamba.readthedocs.io/en/latest/). +`bw_timex` is a Python software package. It's available via [`conda`](https://docs.conda.io/en/latest/) / [`mamba`](https://mamba.readthedocs.io/en/latest/) and [`pip`](https://pypi.org/project/pip/). ```{note} -1) We recommend installation via `conda` or `mamba`. -2) bw_timex depends on Brightway25, and will install bw25-compatible versions of the bw packages. This means that it cannot be added to existing virtual environments that are based on Brightway2, e.g., environments containing [Activity Browser](https://github.com/LCA-ActivityBrowser/activity-browser). Please install bw_timex in a separate environment following the instructions below. +`bw_timex` depends on Brightway25, and will install bw25-compatible versions of the bw packages. This means that it cannot be added to existing environments that are based on Brightway2, e.g., environments containing [Activity Browser](https://github.com/LCA-ActivityBrowser/activity-browser). ``` ## Installing `bw_timex` using `conda` or `mamba` ```{admonition} Prerequisites :class: important -1. A working installation of `conda` or `mamba`. If you are using `conda`, we recommend installing the [libmamba solver](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community). +1. A working installation of [`conda`](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) or [`mamba`](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html). If you are using `conda`, we recommend installing the [libmamba solver](https://www.anaconda.com/blog/a-faster-conda-for-a-growing-community). 2. Basic knowledge of [Conda environments](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html) ``` @@ -22,7 +21,7 @@ 1. Create a new Conda environment (in this example named `timex`): ```console -conda create -n timex -c conda-forge -c cmutel -c diepers brightway25 bw_timex +conda create -n timex -c conda-forge -c cmutel -c diepers bw_timex ``` 2. Activate the environment: @@ -48,7 +47,7 @@ Brightway runs on the new Apple Silicon ARM architecture. However, the super-fas 1. Create a new Conda environment (in this example named `timex`): ``` -conda create -n timex -c conda-forge -c cmutel -c diepers brightway25_nosolver scikit-umfpack bw_timex +conda create -n timex -c conda-forge -c cmutel -c diepers bw_timex brightway25_nosolver scikit-umfpack numpy"<1.25" ``` 2. Activate the environment: @@ -65,14 +64,66 @@ conda install -c conda-forge jupyterlab :::: -## Updating `bw_timex` +## Installing `bw_timex` using `pip` -`bw_timex` is being actively developed, with frequent new releases. To update bw_timex using `conda` or `mamba`, activate your environment, and run: +::::{tab-set} + +:::{tab-item} Linux, Windows, or MacOS (x64) + +1. Install `python` from [the website](https://www.python.org/downloads/), your system package manager, or [Homebrew](https://docs.brew.sh/Homebrew-and-Python). + +2. Create a directory for your virtual environments, such as `C:/Users/me/virtualenvs/`. + +3. In a console or terminal window, create a new virtual environment: + +```console +python -m venv C:/Users/me/virtualenvs/timex +``` + +4. Activate the virtual environment. The exact syntax depends on your operating system; it will look something like: + +```console +source C:/Users/me/virtualenvs/timex/bin/activate +``` + +5. Install `bw_timex`: + +```console +pip install bw_timex pypardiso +``` + +You can also use pip to install useful libraries like `jupyterlab`. -``` bash -conda update -c diepers bw_timex +::: + +:::{tab-item} MacOS (Apple Silicon/ARM) + +```{note} +Due to [an upstream bug](https://github.com/scikit-umfpack/scikit-umfpack/issues/98), there is currently no reliable way to install the fast sparse library `umfpack` on Apple Silicon using `pip`, and the `pypardiso` library is only for x64 systems. If you are doing computationally-intensive workflows, we recommend installing Brightway using `conda` or `mamba` for now. If you are doing fewer calculations or software development installation via `pip` is fine. +``` + +1. Install `python` from [the website](https://www.python.org/downloads/), your system package manager, or [Homebrew](https://docs.brew.sh/Homebrew-and-Python). + +2. In a terminal window, create a directory for your virtual environments. This can be anywhere; we will use the home directory here as an example: + +```console +cd +mkdir virtualenvs ``` -```{warning} -Newer versions of `bw_timex` can introduce breaking changes, see [Changelog](changelog.md). We recommend to create a new environment for each project, and only update `bw_timex` when you are ready to update your project. +3. Create and activate a virtualenv: + +```console +python -m venv virtualenvs/timex +source virtualenvs/timex/bin/activate ``` + +4. Install `bw_timex`: + +```console +pip install bw_timex +``` + +You can also use pip to install useful libraries like `jupyterlab`. + +::::