Verified Commit b28f26ae authored by Lars Bilke's avatar Lars Bilke
Browse files

[web] Added docs on pip install usage and wheel development.

parent eec595de
date = "2022-02-09T11:00:13+01:00"
title = "Python wheel development"
author = "Lars Bilke"
weight = 1068
parent = "advanced"
## Local setup
Python wheel builds are driven by [scikit-build]( which basically is a `setuptools`-wrapper for CMake-based projects.
The entrypoint is `` in the root directory. It uses the `wheel` CMake preset (or `wheel-win` on Windows).
You can locally develop and test with the following setup:
# Create a virtual environment inside your source directory
python3 -m venv .venv
# Activate the environment
source .venv/bin/activate
# Install (build) the local Python project
pip install -v .[test]
Successfully installed ogs-6.4.2.dev1207
The `pip install`-step starts a new CMake-based ogs build in `_skbuild`-subdirectory (inside the source code) using the `wheel`-preset. When the CMake build is done it installs the wheel into the activated virtual environment and you can interact with it, e.g.:
# Run python tests
============================================== test session starts ===============================================
platform darwin -- Python 3.10.6, pytest-7.1.3, pluggy-1.0.0
rootdir: ~/code/ogs/ogs, configfile: pyproject.toml, testpaths: Tests
collected 2 items
Tests/Python/ . [ 50%]
Tests/Python/ . [100%]
=============================================== 2 passed in 0.55s ================================================
# Start the python interpreter
>>> import ogs.simulator as sim
>>> sim.initialize(["", "--help"])
If you make modifications you need to run `pip install .[test]` again (or for temporary modifications you can directly edit inside the virtual environment, e.g. in `.venv/lib/python3.10/site-packages/ogs`).
The contents of `_skbuild/[platform-specific]/cmake-install` will make up the wheel.
## CI
For generating the various wheels for different Python versions and platforms [`cibuildwheel`]( is used.
You can test it locally with, e.g. only building for Python 3.10:
CIBW_BUILD="cp310*" pipx run cibuildwheel
Please note that on Linux `cibuildwheel` runs the builds inside [manylinux]( Docker containers. On other platforms the build happens with native tools. See the [cibuildwheel docs]( for more information.
Wheels are generated in the `wheelhouse/`-folder.
`cibuildwheel` is configured in `pyproject.toml`:
......@@ -15,14 +15,60 @@ weight = 1
post = "Download, install and run an OGS benchmark in 5 minutes! No development setup required."
## Download
## Installation
Download the latest release of OpenGeoSys from the [Releases](/releases)-page. Be sure to pick the correct file for your operating system.
<div class='win'>
## Installation
Download the latest release of OpenGeoSys from the [Releases](/releases)-page. Be sure to pick the correct file for your operating system.
OGS itself is a simple executable file so you can put it anywhere you like. For convenience you may put into a location which is in your `PATH`-environment variable which allows you to start the executable without specifying its full file path.
<div class="note">
### Alternative: Install via `pip`
You can also install ogs via Python's [`pip`-tool](
pip install ogs
If you install into an activated [virtual environment]( then ogs and its tools are automatically also in the `PATH`. Otherwise `pip` will print instructions which directory needs to be added to the `PATH`.
<div class='linux'>
Install via Python's [`pip`-tool](
pip install ogs
You may want to set up and activate a [virtual environment]( before.
You could also use [`pipx`]( to install into an isolated environment.
<div class='mac'>
See Linux tab!
<div class="note">
### Limitations of the `pip`-based installation
- Serial config only! For PETSc-support please use a [Singularity container]({{< relref "container" >}}).
- No embedded Python interpreter, i.e. no Python boundary conditions!
- A Python (3.8 - 3.11) installation with `pip` is required.
## Download benchmarks
You can download the latest benchmark files from GitLab:
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment