OPTIMADE Python tools¶

Latest release	Build status	Activity

The aim of OPTIMADE is to develop a common API, compliant with the JSON API 1.0 specification. This is to enable interoperability among databases that contain calculated properties of existing and hypothetical materials.

This repository contains a library of tools for implementing and consuming OPTIMADE APIs using Python. It also contains a server validator tool, which may be called from the shell or used as a GitHub Action from optimade-validator-action.

Disclaimer: While the package supports elasticsearch-dsl v6 & v7 and django v2 & v3, all tests are performed with the latest supported version. If you experience any issues with the older versions, you are most welcome to contribute to the repository (see below under Contributing).

Status¶

Whilst v1.0 of the OPTIMADE specification has been released, this repository is under development. Outstanding features required for compliance with OPTIMADE v1.0 can be tracked with the OPTIMADE v1.0 label on GitHub, which can be further filtered by backend. The release history and changelog can be found in the changelog.

Documentation¶

This document, guides, and the full module API documentation can be found online at https://optimade.org/optimade-python-tools.

Installation¶

Detailed instructions for installing and running the index meta-database and the main API can be found in the installation documentation.

The latest stable version of this package can be obtained from PyPI pip install optimade. The latest development version of this package can be installed from the master branch of this repository git clone https://github.com/Materials-Consortia/optimade-python-tools.

Supported OPTIMADE versions¶

Each release of the optimade package from this repository only targets one version of the OPTIMADE specification, summarised in the table below.

^† Whilst both the specification and this package follow semantic versioning, a potentially backwards incompatible change was introduced in v1.0.1 of the specification.

Contributing¶

Contribution tips and guidelines can be found in the contributing guidelines.

Links¶

• OPTIMADE Specification, the human-readable specification that this library is based on.
• optimade-validator-action, a GitHub action that can be used to validate implementations from a URL (using the validator from this repo).
• OpenAPI, the machine-readable format used to specify the OPTIMADE API in openapi.json and index_openapi.json.
• Interactive documentation generated from openapi.json (see also interactive JSON editor).
• pydantic, the library used for generating the OpenAPI schema from Python models.
• FastAPI, the framework used for generating the reference implementation expressed by the openapi.json specification.
• lark, the library used to parse the filter language in OPTIMADE queries.