diff --git a/web/content/docs/userguide/basics/introduction/index.md b/web/content/docs/userguide/basics/introduction/index.md index f4bd3797dee..bb027a773b4 100644 --- a/web/content/docs/userguide/basics/introduction/index.md +++ b/web/content/docs/userguide/basics/introduction/index.md @@ -19,100 +19,88 @@ category = "Beginner" ## Installation -There are various ways to obtain a running version of OpenGeoSys (OGS) on your machine. You can have OGS for different -operating systems including Windows, Linux, and macOS. Most of the functionality is available for all operating systems, -however, for parallel execution of OGS we recommend to set up OGS either under Linux or macOS. It is your choice, if you just -want to use prebuild version of OGS for easy use (or just to get started), or if you would like to customize your OGS-build for -your specific application, or even become an active development member. However, all kinds of installation will provide you -with a modelling platform including all physical processes available in OGS. +There are various ways to obtain a (pre-built) running version of OpenGeoSys (OGS) on your machine. You can have OGS for different +operating systems including Windows, Linux, and macOS. The basic modelling platform is available for all operating systems. +The different operating systems and installation methods give you the feature matrix: -
- -One easy way to obtain your running version is -to just download the latest stable or development release of OpenGeoSys from the [Releases](/releases)-page. Be sure to pick -the correct file for your operating system. - -By downloading from the release page you will get a bunch of folders and files. However, OGS itself will come as a simple -executable file, which you will find in the `bin` sub-folder. You can put the executable wherever you like. For convenience you -may put it into a location which is in your `PATH`-environment variable which allows you to start the executable without -specifying its full file path just calling `ogs` from the terminal of your machine. +| Operating system / Installation method | [Processes](/docs/userguide/blocks/processes/) | [MFront](/docs/userguide/features/mfront/) | [PETSc]({{< ref "parallel_computing_mpi" >}}) +| ---------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------: | :----------------------------------------: | :-------------------------------------------: +| Windows / [pip](#install-via-pip) & [binary download](#alternative-install-via-binary-downloads) | `TH2M` disabled, [see issue](https://gitlab.opengeosys.org/ogs/ogs/-/issues/3197) | ❌ | ❌ +| macOS / [pip](#install-via-pip) | All | ✅ | ❌ +| Linux / [pip](#install-via-pip) & [Serial Container]({{< ref "container.md" >}}) | All | ✅ | ❌ +| Linux / [PETSc Container]({{< ref "container.md" >}}) | All | ✅ | ✅
-### Alternative: Install via `pip` +### Using Linux binaries on other operating systems -Currently, we are actively developing a Python-interface for manipulating OGS-models, which greatly speeds up the modelling -workflow using OGS. Following this spirit, you can also install OGS via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/): +Please note that you can use Linux binaries installed via `pip` or in the form of a container also on other operating systems. -```bash -pip install ogs -``` +For Windows we recommend the [Windows Subsystem for Linux (WSL)]({{< ref "wsl" >}}). -We recommend using Python within a [virtual environment](https://docs.python.org/3/library/venv.html) to keep possible -conflicts of different Python-packages localised. If you use `pip` for installation of OGS in a virtual environment and you -activate the virtual environment, then OGS and its tools are automatically also in the `PATH`. If the virtual environment is -not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder of the -virtual environment, or add this path to your `PATH`-environment. Moreover, `pip` may print instructions which directory needs -to be added to the `PATH`. - -
+On macOS you can use either a virtual machine (e.g. via [UTM](https://docs.getutm.app/installation/macos/)) or run a [Docker container]({{< ref "container.md#with-docker" >}}).
-
+## Install via pip -A straightforward way of installing a running build of OGS is via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/): +A straightforward way of installing OGS is via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/): ```bash +# Optional: create a Python virtual environment, see below +python -m venv .venv # or `python3 -m venv .venv` +source .venv/bin/activate # Linux / macOS; for Windows: .\venv\Scripts\activate + +# Install ogs' pip package pip install ogs ``` +Please note that this requires a Python installation (version 3.8 - 3.11) with the `pip`-tool. + We recommend using Python within a [virtual environment](https://docs.python.org/3/library/venv.html) to keep possible conflicts of different Python-packages localised. If you use `pip` for installation of OGS in a virtual environment and you activate the virtual environment, then OGS and its tools are automatically also in the `PATH`. If the virtual environment is -not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder of the +not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder (or `Scripts` folder on Windows) of the virtual environment, or add this path to your `PATH`-environment. Moreover, `pip` may print instructions which directory needs to be added to the `PATH`. You could also use [`pipx`](https://pypa.github.io/pipx/) for installation into an isolated environment. -
+
-
+### Get current development version with `pip` -A straightforward way of installing a running build of OGS is via Python's [`pip`-tool](https://packaging.python.org/en/latest/tutorials/installing-packages/): +The following command will download the latest development version: ```bash -pip install ogs +pip install --pre --index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple ogs ``` -We recommend using Python within a [virtual environment](https://docs.python.org/3/library/venv.html) to keep possible -conflicts of different Python-packages localised. If you use `pip` for installation of OGS in a virtual environment and you -activate the virtual environment, then OGS and its tools are automatically also in the `PATH`. If the virtual environment is -not activated you may still use OGS, but either have to give the full path to `ogs` being located in the `bin` folder of the -virtual environment, or add this path to your `PATH`-environment. Moreover, `pip` may print instructions which directory needs -to be added to the `PATH`. - -You could also use [`pipx`](https://pypa.github.io/pipx/) for installation into an isolated environment. -
+
+
-### Get current development version with `pip` +### Alternative: Install via binary downloads -The following command will download the latest development version: +Another way to obtain a running version is +to just download the latest stable or development release of OpenGeoSys from the [Releases](/releases)-page. -```bash -pip install --index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple ogs -``` +By downloading from the release page you will get a bunch of folders and files. However, OGS itself will come as a simple +executable file, which you will find in the `bin` sub-folder. You can put the executable wherever you like. For convenience you +may put it into a location which is in your `PATH`-environment variable which allows you to start the executable without +specifying its full file path just calling `ogs` from the terminal of your machine. + +
-### Limitations of the `pip`-based installation +
+ +
-- Please note that via the `pip`-based installation only the serial configuration is available! For parallel execution of the -source code, PETSc is required. For PETSc-support please use a [Singularity container]({{< relref "container" >}}). -- A Python (3.8 - 3.11) installation with `pip` is required. +
+ +
diff --git a/web/content/releases/6.4.4.md b/web/content/releases/6.4.4.md index de3df9237c4..242eb720dbf 100644 --- a/web/content/releases/6.4.4.md +++ b/web/content/releases/6.4.4.md @@ -16,6 +16,7 @@ container = [ "serial.sif", "openmpi-4.0.5.sif", ] +pip = true note = """ **Note:** When using Python bindings make sure to have Python installed on your system: diff --git a/web/content/releases/_index.md b/web/content/releases/_index.md index 96592b16cc0..77b8336166e 100644 --- a/web/content/releases/_index.md +++ b/web/content/releases/_index.md @@ -7,6 +7,12 @@ weight = 1 aliases = ["/downloads", "/download"] # Redirect for Hydrology II tutorial +[[head_downloads]] +name = "Latest pip-installable package" +url = "/docs/userguide/basics/introduction#installation" +note = "All platforms: `pip install --pre --index-url https://gitlab.opengeosys.org/api/v4/projects/120/packages/pypi/simple ogs`" +icon = "far fa-arrow-right" + # url encode job name, https://www.w3schools.com/tags/ref_urlencode.ASP [[head_downloads]] name = "Latest Windows CLI with Utilities" diff --git a/web/layouts/partials/releases/single.html b/web/layouts/partials/releases/single.html index 35bf11c4be2..b193c95d6f5 100644 --- a/web/layouts/partials/releases/single.html +++ b/web/layouts/partials/releases/single.html @@ -2,6 +2,7 @@ {{ $gh_download := print "https://github.com/ufz/ogs/releases/download/" .Params.tag }} {{ $benchmarks_url := print "https://github.com/ufz/ogs-data/archive/" .Params.tag ".zip" }} {{ $type := "GitHub"}} +{{ $pypi_url := print "https://pypi.org/project/ogs/" .Params.tag }} {{/* comparison only works for two version parts, strip out 6. */}} {{ if gt (slicestr .Params.tag 2) "3.1" }} {{ $gh_release = print "https://gitlab.opengeosys.org/ogs/ogs/-/releases/" .Params.tag }} @@ -43,6 +44,24 @@

Downloads

+ {{ if .Params.downloads.pip }} + + All + OpenGeoSys + Utilities (Release on + PyPI)
Note: Recommended install + method for + users on all platforms. + + + Python bindings + + + PyPI release page + + + {{ end }} {{ range .Params.downloads.binary }} diff --git a/web/layouts/releases/list.html b/web/layouts/releases/list.html index a3942351edd..c8305200ff7 100644 --- a/web/layouts/releases/list.html +++ b/web/layouts/releases/list.html @@ -58,7 +58,7 @@

Current release with bug-fixes: {{ .Params.tag }}

Downloads