polytope-python

Concept • Installation • Example • Testing • Documentation

Polytope is a library for extracting complex data from datacubes. It provides an API for non-orthogonal access to data, where the stencil used to extract data from the datacube can be any arbitrary n-dimensional polygon (called a polytope). This can be used to efficiently extract complex features from a datacube, such as polygon regions or spatio-temporal paths.

Polytope is designed to extend different datacube backends:

XArray dataarrays
FDB object stores (through the GribJump software)

Polytope supports datacubes which have branching, non-uniform indexing, and even cyclic axes. If the datacube backend supports byte-addressability and efficient random access (either in-memory or direct from storage), Polytope can be used to dramatically decrease overall I/O load.

[!IMPORTANT] This software is Incubating and subject to ECMWF's guidelines on Software Maturity.

Concept

Polytope is designed to enable extraction of arbitrary extraction of data from a datacube. Instead of the typical range-based bounding-box approach, Polytope can extract any shape of data from a datacube using a "polytope" (n-dimensional polygon) stencil.

Polytope Concept

The Polytope algorithm can for example be used to extract:

2D cut-outs, such as country cut-outs, from a datacube
timeseries from a datacube
more complicated spatio-temporal paths, such as flight paths, from a datacube
and many more high-dimensional shapes in arbitrary dimensions...

For more information about the Polytope algorithm, refer to our paper. If this project is useful for your work, please consider citing this paper.

Installation

Install the polytope software with Python 3 (>=3.7) from GitHub directly with the command

python3 -m pip install git+ssh://git@github.com/ecmwf/polytope.git@develop

or from PyPI with the command

python3 -m pip install polytope-python

Example

Here is a step-by-step example of how to use this software.

In this example, we first specify the data which will be in our Xarray datacube. Note that the data here comes from the GRIB file called "winds.grib", which is 3-dimensional with dimensions: step, latitude and longitude.
```
    import xarray as xr

    array = xr.open_dataset("winds.grib", engine="cfgrib")
```
We then construct the Polytope object, passing in some additional metadata describing properties of the longitude axis.
```
    options = {"longitude": {"cyclic": [0, 360.0]}}

    from polytope_feature.polytope import Polytope

    p = Polytope(datacube=array, axis_options=options)
```

Next, we create a request shape to extract from the datacube.
In this example, we want to extract a simple 2D box in latitude and longitude at step 0. We thus create the two relevant shapes we need to build this 3-dimensional object,

    import numpy as np
    from polytope_feature.shapes import Box, Select

    box = Box(["latitude", "longitude"], [0, 0], [1, 1])
    step_point = Select("step", [np.timedelta64(0, "s")])

which we then incorporate into a Polytope request.

    from polytope_feature.polytope import Request

    request = Request(box, step_point)

Finally, extract the request from the datacube.

    result = p.retrieve(request)

The result is stored as an IndexTree containing the retrieved data organised hierarchically with axis indices for each point.

    result.pprint()
    

    Output IndexTree: 

        ↳root=None
            ↳step=0 days 00:00:00
                    ↳latitude=0.0
                            ↳longitude=0.0
                            ↳longitude=1.0
                    ↳latitude=1.0
                            ↳longitude=0.0
                            ↳longitude=1.0

Testing

Additional Dependencies

The Polytope tests and examples require additional Python packages compared to the main Polytope algorithm. The additional dependencies are provided in the requirements_test.txt and requirements_examples.txt files, which can respectively be found in the tests and examples folders. Moreover, Polytope's tests and examples also require the installation of eccodes and GDAL. It is possible to install both of these dependencies using either a package manager or manually.

Contributing

The main repository is hosted on GitHub; testing, bug reports and contributions are highly welcomed and appreciated. Please see the Contributing document for the best way to help.

Main contributors:

Mathilde Leuridan - ECMWF
James Hawkes - ECMWF
Simon Smart - ECMWF
Emanuele Danovaro - ECMWF
Tiago Quintino - ECMWF

See also the contributors for a more complete list.

License

Copyright 2021 European Centre for Medium-Range Weather Forecasts (ECMWF)

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0).

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

In applying this licence, ECMWF does not waive the privileges and immunities
granted to it by virtue of its status as an intergovernmental organisation nor
does it submit to any jurisdiction.

Citing

If this software is useful in your work, please consider citing our paper as

Leuridan, M., Hawkes, J., Smart, S., Danovaro, E., & Quintino, T. (2025, November). Polytope: An Algorithm for Efficient Feature Extraction on Hypercubes. In Journal of Big Data (pp. 1-25).

Other papers include:

Leuridan, M., Bradley, C., Hawkes, J., Quintino, T., & Schultz, M. (2025, June). Performance Analysis of an Efficient Algorithm for Feature Extraction from Large Scale Meteorological Data Stores. In Proceedings of the Platform for Advanced Scientific Computing Conference (pp. 1-9).

Acknowledgements

Past and current funding and support for Polytope is listed in the adjoining Acknowledgements.

Metadata

Release files for polytope-python 2.1.20

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for polytope-python 2.1.20
File	Size	Uploaded
polytope_python-2.1.20.tar.gz	14.3 MB	Sep 22, 2026	Details

Built distributions (wheels)

Table of built distributions (wheels) for polytope-python 2.1.20
File	Interpreter	ABI	Platform	Reset
polytope_python-2.1.20-cp312-cp312-manylinux_2_28_x86_64.whl 572.0 kB Sep 22, 2026	CPython 3.12	CPython 3.12	Linux glibc 2.28+ x86-64	Details
polytope_python-2.1.20-cp312-cp312-macosx_11_0_arm64.whl 519.8 kB Sep 22, 2026	CPython 3.12	CPython 3.12	macOS 11.0+ ARM64	Details
polytope_python-2.1.20-cp311-cp311-manylinux_2_28_x86_64.whl 576.2 kB Sep 22, 2026	CPython 3.11	CPython 3.11	Linux glibc 2.28+ x86-64	Details
polytope_python-2.1.20-cp311-cp311-macosx_11_0_arm64.whl 523.6 kB Sep 22, 2026	CPython 3.11	CPython 3.11	macOS 11.0+ ARM64	Details
polytope_python-2.1.20-cp310-cp310-manylinux_2_28_x86_64.whl 576.6 kB Sep 22, 2026	CPython 3.10	CPython 3.10	Linux glibc 2.28+ x86-64	Details
polytope_python-2.1.20-cp310-cp310-macosx_11_0_arm64.whl 523.7 kB Sep 22, 2026	CPython 3.10	CPython 3.10	macOS 11.0+ ARM64	Details
polytope_python-2.1.20-cp39-cp39-manylinux_2_28_x86_64.whl 579.9 kB Sep 22, 2026	CPython 3.9	CPython 3.9	Linux glibc 2.28+ x86-64	Details
polytope_python-2.1.20-cp39-cp39-macosx_11_0_arm64.whl 526.2 kB Sep 22, 2026	CPython 3.9	CPython 3.9	macOS 11.0+ ARM64	Details

Total release size: 18.7 MB

Release files / polytope_python-2.1.20.tar.gz

Download URL	polytope_python-2.1.20.tar.gz
Size	14.3 MB
Tags	Source
SHA-256 checksum How to use checksums	`6cf4784acf4bbfe29b09b15b3cb357baccf8f1e1d8e54555222102e0dcb658a9`
BLAKE2b-256 checksum How to use checksums	`496647a79e7b0ceced0a58bc2f9c787677b82dbd7db0630b15b577766d26871e`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp312-cp312-manylinux_2_28_x86_64.whl

Download URL	polytope_python-2.1.20-cp312-cp312-manylinux_2_28_x86_64.whl
Size	572.0 kB
Tags	CPython 3.12 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`4a7bd8a127ce2e03ca839039929f81dffa3f6d80541c9fb8838e1ddf6cd25af8`
BLAKE2b-256 checksum How to use checksums	`fcaed7b4e6169b8973fb2ff380530d72df6b69126efa4783945a27febea2c253`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp312-cp312-macosx_11_0_arm64.whl

Download URL	polytope_python-2.1.20-cp312-cp312-macosx_11_0_arm64.whl
Size	519.8 kB
Tags	CPython 3.12 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`da4b58e027a0a3b50db939a3c9f34f89c58e866e40187a9e6f83f9137e81d0c7`
BLAKE2b-256 checksum How to use checksums	`0b92900229f0e69594d0d40019d9b686173dbfd24d31b751584ca4cd14195709`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp311-cp311-manylinux_2_28_x86_64.whl

Download URL	polytope_python-2.1.20-cp311-cp311-manylinux_2_28_x86_64.whl
Size	576.2 kB
Tags	CPython 3.11 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`3f5d4935f8dd79739c6950d67e5aceb0801da38f4b44548b94b762f146aa828c`
BLAKE2b-256 checksum How to use checksums	`7ebdd697206ef4deacfd064849246a80d8361476bfdc12e39922ae08f3dd2dd3`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp311-cp311-macosx_11_0_arm64.whl

Download URL	polytope_python-2.1.20-cp311-cp311-macosx_11_0_arm64.whl
Size	523.6 kB
Tags	CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`a31003076ccd1729b28b79fa8c17c780c15f911eeb9c590f179b8736e4508caf`
BLAKE2b-256 checksum How to use checksums	`004a3de6c6166f0740c88ed335e7b38788f87a4103ed6aecc0082c05ff321cbf`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp310-cp310-manylinux_2_28_x86_64.whl

Download URL	polytope_python-2.1.20-cp310-cp310-manylinux_2_28_x86_64.whl
Size	576.6 kB
Tags	CPython 3.10 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`1e42c8fdea82b528347d889346e8927640da66886a9475e1112279c62dc6b093`
BLAKE2b-256 checksum How to use checksums	`bf35b4bcf4afc9c53a61d299fec1b761198196ac7fa68ab4c93090ed1f646c60`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp310-cp310-macosx_11_0_arm64.whl

Download URL	polytope_python-2.1.20-cp310-cp310-macosx_11_0_arm64.whl
Size	523.7 kB
Tags	CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`8088c01ab7a04a8802f4a2333a8a2154b665327fc88b917690b66351b29abc17`
BLAKE2b-256 checksum How to use checksums	`3de3e61a49f3783d2366cdbf6e8e4c44abf05b05a4f4d502dc07e12c58face93`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp39-cp39-manylinux_2_28_x86_64.whl

Download URL	polytope_python-2.1.20-cp39-cp39-manylinux_2_28_x86_64.whl
Size	579.9 kB
Tags	CPython 3.9 Linux glibc 2.28+ x86-64
SHA-256 checksum How to use checksums	`6f9bda437747363e50afabc62ad29025960b7da441a5387f2039b7fddca5d868`
BLAKE2b-256 checksum How to use checksums	`18170563777bcca777946782bce87fc67be525b536a64dc2eb77c90c8ae78e8d`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`

Release files / polytope_python-2.1.20-cp39-cp39-macosx_11_0_arm64.whl

Download URL	polytope_python-2.1.20-cp39-cp39-macosx_11_0_arm64.whl
Size	526.2 kB
Tags	CPython 3.9 macOS 11.0+ ARM64
SHA-256 checksum How to use checksums	`89bef3533255cc13cdd1b891bee562953596197212bad418ebe2f9e7a95b92e0`
BLAKE2b-256 checksum How to use checksums	`8092eebe52aa6eb6457b43801c319e65004e91864578e7ee282bf9c08f5a538c`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.14.7`