Skip to main content

Tools for implementing and consuming OPTIMADE APIs.

Project description

OPTIMADE Python tools

JOSS DOI

Latest releaseBuild statusActivity
PyPI version
PyPI - Python Version
OPTIMADE version
Build Status
Docs
Codecov
Commit Activity
Last Commit
Contributors

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 serve crystal structures and calculated properties of existing and hypothetical materials.

This repository contains a library of tools for implementing and consuming OPTIMADE APIs using Python:

  1. pydantic data models for all OPTIMADE entry types and endpoint responses, and a Lark EBNF grammar implementation for the OPTIMADE filter language.
  2. Adapters to map OPTIMADE data to and from many commonly used atomistic Python frameworks (e.g., pymatgen, ASE) and crystallographic file types (e.g., CIF), using the optimade.adapters module.
  3. A configurable reference server implementation that can make use of either MongoDB or Elasticsearch database backends out-of-the-box, and is readily extensible to other backends. Try it out on the demo site! The OpenAPI schemas of the server are used to construct the OPTIMADE schemas site.
  4. An OPTIMADE client (optimade-get) that can query multiple OPTIMADE providers concurrently with a given filter, at the command-line or from Python code.
  5. A fuzzy API validator tool, which may be called from the shell (optimade-validator) or used as a GitHub Action from optimade-validator-action; this validator is used to construct the providers dashboard.

Documentation

This document, guides, and the full module API documentation can be found online at https://optimade.org/optimade-python-tools. In particular, documentation of the OPTIMADE API response data models (implemented here with pydantic) can be found online under OPTIMADE Data Models.

The release history and changelog can be found in the changelog.

Installation

Detailed installation instructions for different use cases (e.g., using the library or running a server) 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 obtained from the main 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.

OPTIMADE API version optimade requirements
v1.0.0 optimade<=0.12.9
v1.1.0 optimade>=0.16,<1.2
v1.2.0 optimade>=1.2.0

Contributing and Getting Help

All development of this package (bug reports, suggestions, feedback and pull requests) occurs in the optimade-python-tools GitHub repository. Contribution guidelines and tips for getting help can be found in the contributing notes.

How to cite

If you use this package to access or serve OPTIMADE data, we kindly request that you cite the following:

  • Evans et al., Developments and applications of the OPTIMADE API for materials discovery, design, and data exchange, Digital Discovery, 3, 1509-1533 (2024) 10.1039/D4DD00039K
  • Andersen et al., OPTIMADE, an API for exchanging materials data, Sci. Data 8, 217 (2021) 10.1038/s41597-021-00974-z
  • Evans et al., optimade-python-tools: a Python library for serving and consuming materials data via OPTIMADE APIs. Journal of Open Source Software, 6(65), 3458 (2021) 10.21105/joss.03458

Links

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

optimade-1.2.4.tar.gz (193.5 kB view details)

Uploaded Source

Built Distribution

optimade-1.2.4-py3-none-any.whl (241.7 kB view details)

Uploaded Python 3

File details

Details for the file optimade-1.2.4.tar.gz.

File metadata

  • Download URL: optimade-1.2.4.tar.gz
  • Upload date:
  • Size: 193.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for optimade-1.2.4.tar.gz
Algorithm Hash digest
SHA256 ae7c25be62d8fcc94589db1319830b3cd4640f37937d65c970102fd80729efad
MD5 1b59cbac88622600cc62f921bec45ef2
BLAKE2b-256 5bf87633aa93cd797285d5c8d8233100f664bf43244b4b097ac4b567b2411bae

See more details on using hashes here.

Provenance

The following attestation bundles were made for optimade-1.2.4.tar.gz:

Publisher: cd_release.yml on Materials-Consortia/optimade-python-tools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file optimade-1.2.4-py3-none-any.whl.

File metadata

  • Download URL: optimade-1.2.4-py3-none-any.whl
  • Upload date:
  • Size: 241.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for optimade-1.2.4-py3-none-any.whl
Algorithm Hash digest
SHA256 4df85602e9f3ef2943b9fd033f2a2eb54b494d7efa5e8f5999326969b1a8a2f4
MD5 4ce99eff9cbbc5e6bf8e462c2cc7cf52
BLAKE2b-256 727b5058b9977597096cc4962eb7b9ef42586fa982cfbdf21ee8fee0e58360d4

See more details on using hashes here.

Provenance

The following attestation bundles were made for optimade-1.2.4-py3-none-any.whl:

Publisher: cd_release.yml on Materials-Consortia/optimade-python-tools

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page