Data

Tools

Indexes

Applications

Experiments

Open Source Science

optimade-python-tools

optimade-python-tools: a Python library for serving and consuming materials data via OPTIMADE APIs - Published in JOSS (2021)

https://github.com/materials-consortia/optimade-python-tools

Science Score: 95.0%

This score indicates how likely this project is to be science-related based on various indicators:

  • ○
    CITATION.cff file
  • ✓
    codemeta.json file
    Found codemeta.json file
  • ✓
    .zenodo.json file
    Found .zenodo.json file
  • ✓
    DOI references
    Found 12 DOI reference(s) in README and JOSS metadata
  • ○
    Academic publication links
  • ✓
    Committers with academic emails
    8 of 29 committers (27.6%) from academic institutions
  • ○
    Institutional organization owner
  • ✓
    JOSS paper metadata
    Published in Journal of Open Source Software

Keywords

openapi optimade optimade-api optimade-python optimade-specification python

Keywords from Contributors

energy-system graph-generation exoplanet cryptocurrencies hydrology mesh analyses kmer minhash scaled-minhash

Scientific Fields

Chemistry Physical Sciences - 83% confidence
Last synced: 4 months ago · JSON representation

Repository

Tools for implementing and consuming OPTIMADE APIs in Python

Basic Info
Statistics
  • Stars: 80
  • Watchers: 5
  • Forks: 47
  • Open Issues: 106
  • Releases: 102
Topics
openapi optimade optimade-api optimade-python optimade-specification python
Created over 7 years ago · Last pushed 4 months ago
Metadata Files
Readme Changelog Contributing License Codeowners

README.md

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:

shell pip install optimade

The latest development version of this package can be obtained from the main branch of this repository:

shell 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

Owner

  • Name: Open Databases Integration for Materials Design
  • Login: Materials-Consortia
  • Kind: organization

The Open Databases Integration for Materials Design (OPTIMADE) makes the materials databases interoperational by developing a common REST API.

JOSS Publication

optimade-python-tools: a Python library for serving and consuming materials data via OPTIMADE APIs
Published
September 22, 2021
DOI
Volume 6, Issue 65, Page 3458
Authors
Matthew L. Evans ORCID
Institut de la Matière Condensée et des Nanosciences, Université catholique de Louvain, Chemin des Étoiles 8, Louvain-la-Neuve 1348, Belgium, Theory of Condensed Matter Group, Cavendish Laboratory, University of Cambridge, J. J. Thomson Avenue, Cambridge, CB3 0HE, United Kingdom
Casper W. Andersen ORCID
Theory and Simulation of Materials (THEOS), Faculté des Sciences et Techniques de l'Ingénieur, École Polytechnique Fédérale de Lausanne, CH-1015 Lausanne, Switzerland
Shyam Dwaraknath ORCID
Lawrence Berkeley National Laboratory, Berkeley, CA, USA
Markus Scheidgen ORCID
Fritz-Haber-Institut der Max-Planck-Gesellschaft, Faradayweg 4-6, 14195, Berlin, Germany, Humboldt-Universität zu Berlin, Institut für Physik and IRIS Adlershof, 12489 Berlin, Germany
Ádám Fekete ORCID
Institut de la Matière Condensée et des Nanosciences, Université catholique de Louvain, Chemin des Étoiles 8, Louvain-la-Neuve 1348, Belgium, Department of Physics, King's College London, Strand, London WC2R 2LS, United Kingdom, Department of Physics and Namur Institute of Structured Materials, University of Namur, Rue de Bruxelles 51, 5000 Namur, Belgium
Donald Winston ORCID
Lawrence Berkeley National Laboratory, Berkeley, CA, USA, Polyneme LLC, New York, NY, USA
Editor
Jeff Gostick ORCID
Tags
REST API JSON:API OPTIMADE API crystallography density-functional theory ab initio materials discovery databases
View PDF Review Thread Software Archive

Papers & Mentions

Total mentions: 1

OPTIMADE, an API for exchanging materials data
Last synced: 2 months ago

GitHub Events

Total
  • Create event: 132
  • Issues event: 34
  • Release event: 12
  • Watch event: 9
  • Delete event: 100
  • Issue comment event: 177
  • Push event: 265
  • Pull request review comment event: 4
  • Pull request review event: 29
  • Pull request event: 196
  • Fork event: 4
Last Year
  • Create event: 133
  • Issues event: 34
  • Release event: 12
  • Watch event: 9
  • Delete event: 100
  • Issue comment event: 177
  • Push event: 265
  • Pull request review comment event: 4
  • Pull request review event: 29
  • Pull request event: 196
  • Fork event: 4

Committers

Last synced: 5 months ago

All Time
  • Total Commits: 1,609
  • Total Committers: 29
  • Avg Commits per committer: 55.483
  • Development Distribution Score (DDS): 0.602
Past Year
  • Commits: 121
  • Committers: 7
  • Avg Commits per committer: 17.286
  • Development Distribution Score (DDS): 0.612
Top Committers
Name Email Commits
Matthew Evans 7****s 640
Casper Welzel Andersen c****n@e****h 360
OPTIMADE Developers d****v@o****g 142
dependabot[bot] 4****] 114
Shyam Dwaraknath s****d@l****v 80
Donny Winston d****n@a****u 54
Michael Wu w****1@g****m 54
Adam Fekete a****e@k****k 39
Johan Bergsma 2****a 30
Leopold Talirz l****z@g****m 16
Thomas Purcell p****l@f****e 11
pre-commit-ci[bot] 6****] 9
Markus Scheidgen m****n@g****m 8
Michael Wu m****u@M****t 8
Michael Wu m****u@M****l 7
Abhijith Gopakumar a****g@g****m 6
Andrius Merkys a****s@g****m 5
Fawzi Mohamed f****i@k****u 5
Adam Fekete f****d 4
Fawzi Mohamed f****i@g****h 3
Mehmet Giritli 9****i 3
dependabot-preview[bot] 2****] 3
Diether John Estrada d****a@l****v 2
Jan Janssen j****n 1
Kamal Choudhary w****9@g****m 1
Munawar m****z@g****m 1
Michael Wu m****u@a****u 1
Michael Wu m****u@a****u 1
Rickard Armiento g****s@a****t 1
Committer Domains (Top 20 + Academic)
lbl.gov: 2 armiento.net: 1 airbears2-10-142-142-178.airbears2.1918.berkeley.edu: 1 airbears2-10-142-54-68.airbears2.1918.berkeley.edu: 1 gmx.ch: 1 kitabi.eu: 1 michaels-mbp.attlocal.net: 1 fhi-berlin.mpg.de: 1 kcl.ac.uk: 1 alum.mit.edu: 1 optimade.org: 1 epfl.ch: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time
  • Total issues: 89
  • Total pull requests: 974
  • Average time to close issues: 7 months
  • Average time to close pull requests: 10 days
  • Total issue authors: 15
  • Total pull request authors: 10
  • Average comments per issue: 0.63
  • Average comments per pull request: 0.88
  • Merged pull requests: 729
  • Bot issues: 3
  • Bot pull requests: 751
Past Year
  • Issues: 25
  • Pull requests: 240
  • Average time to close issues: 7 days
  • Average time to close pull requests: 6 days
  • Issue authors: 11
  • Pull request authors: 5
  • Average comments per issue: 0.6
  • Average comments per pull request: 1.15
  • Merged pull requests: 125
  • Bot issues: 1
  • Bot pull requests: 179
View more stats
Top Authors
Issue Authors
  • ml-evs (60)
  • CasperWA (8)
  • JPBergsma (6)
  • dependabot[bot] (3)
  • mehmetgiritli (2)
  • anyangml (1)
  • blokhin (1)
  • jan-janssen (1)
  • TLCFEM (1)
  • mkhorton (1)
  • 93-hsngit (1)
  • tschaume (1)
  • worldforxaz (1)
  • tuocvu (1)
  • hongyi-zhao (1)
Pull Request Authors
  • dependabot[bot] (729)
  • ml-evs (158)
  • bot-optimade (31)
  • pre-commit-ci[bot] (22)
  • JPBergsma (16)
  • CasperWA (6)
  • mehmetgiritli (6)
  • merkys (3)
  • markus1978 (2)
  • unkcpz (1)
Top Labels
Issue Labels
bug (16) help wanted (15) OPTIMADE v1.2 (12) client (9) server (7) release-summary (7) priority/medium (7) dependency_updates (6) CI (5) suggestions (5) schema (5) enhancement (5) deployment (4) priority/low (3) models (3) docs (3) validator (3) ergonomics (2) transformers (2) grammar (2) needs discussion (2) priority/high (2) OpenAPI (1) on-hold (1) good first issue (1) refactoring (1)
Pull Request Labels
dependency_updates (722) CI (51) skip_changelog (41) OPTIMADE v1.2 (22) providers_updates (19) bug (15) server (14) client (14) schema (12) models (10) on-hold (10) python (10) enhancement (7) blocked (6) priority/high (4) validator (3) config (3) deployment (2) grammar (2) docs (2) ergonomics (1) dependencies (1)

Packages

  • Total packages: 4
  • Total downloads:
    • pypi 15,496 last-month
  • Total docker downloads: 28,305
  • Total dependent packages: 2
    (may contain duplicates)
  • Total dependent repositories: 14
    (may contain duplicates)
  • Total versions: 387
  • Total maintainers: 5
pypi.org: optimade

Tools for implementing and consuming OPTIMADE APIs.

  • Versions: 121
  • Dependent Packages: 2
  • Dependent Repositories: 13
  • Downloads: 15,496 Last month
  • Docker Downloads: 28,305
Rankings
Docker downloads count: 1.2%
Dependent repos count: 4.0%
Downloads: 4.5%
Dependent packages count: 4.8%
Average: 5.0%
Forks count: 6.4%
Stargazers count: 9.1%
Maintainers (5)
leopold.talirz CasperWA dwinston ml-evs JPBergsma
Last synced: 4 months ago
proxy.golang.org: github.com/materials-consortia/optimade-python-tools
  • Versions: 113
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.5%
Average: 5.6%
Dependent repos count: 5.8%
Last synced: 4 months ago
proxy.golang.org: github.com/Materials-Consortia/optimade-python-tools
  • Versions: 113
  • Dependent Packages: 0
  • Dependent Repositories: 0
Rankings
Dependent packages count: 5.5%
Average: 5.6%
Dependent repos count: 5.8%
Last synced: 4 months ago
conda-forge.org: optimade

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.

  • Versions: 40
  • Dependent Packages: 0
  • Dependent Repositories: 1
Rankings
Dependent repos count: 24.3%
Forks count: 28.4%
Average: 36.5%
Stargazers count: 41.7%
Dependent packages count: 51.6%
Last synced: 4 months ago

Dependencies

.github/workflows/cd_container_image.yml actions
  • actions/checkout v3 composite
.github/workflows/cd_release.yml actions
  • CasperWA/push-protected v2 composite
  • CharMixer/auto-changelog-action v1 composite
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • pypa/gh-action-pypi-publish release/v1 composite
.github/workflows/ci.yml actions
  • Materials-Consortia/optimade-validator-action v2 composite
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • codecov/codecov-action v3 composite
  • elasticsearch 7.17.7 docker
  • mongo 4 docker
  • postgres 10 docker
.github/workflows/ci_automerge_dependabot.yml actions
  • actions/checkout v3 composite
.github/workflows/ci_cd_updated_master.yml actions
  • CasperWA/push-protected v2 composite
  • CharMixer/auto-changelog-action v1 composite
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • superfly/flyctl-actions/setup-flyctl master composite
.github/workflows/ci_dependabot.yml actions
  • actions/checkout v3 composite
  • actions/setup-python v4 composite
  • chuhlomin/render-template v1.6 composite
  • peter-evans/create-pull-request v4 composite
Dockerfile docker
  • python 3.10-slim build
requirements-client.txt pypi
  • aiida-core ==2.2.1
  • ase ==3.22.1
  • jarvis-tools ==2022.12.11
  • numpy ==1.24.1
  • pymatgen ==2022.7.25
requirements-dev.txt pypi
  • black ==22.12.0 development
  • build ==0.9.0 development
  • codecov ==2.1.12 development
  • flake8 ==6.0.0 development
  • invoke ==1.7.3 development
  • isort ==5.11.4 development
  • jsondiff ==2.0.0 development
  • mypy ==0.991 development
  • pre-commit ==2.21.0 development
  • pylint ==2.15.9 development
  • pytest ==7.2.0 development
  • pytest-cov ==4.0.0 development
  • types-all ==1.0.0 development
requirements-docs.txt pypi
  • mike ==1.1.2
  • mkdocs ==1.4.2
  • mkdocs-awesome-pages-plugin ==2.8.0
  • mkdocs-material ==9.0.3
  • mkdocstrings ==0.19.1
requirements-http-client.txt pypi
  • click ==8.1.3
  • httpx ==0.23.3
  • rich ==13.0.1
requirements-server.txt pypi
  • elasticsearch ==7.17.7
  • elasticsearch-dsl ==7.4.0
  • fastapi ==0.89.0
  • mongomock ==4.1.2
  • pymongo ==4.3.3
requirements.txt pypi
  • email_validator ==1.3.0
  • lark ==1.1.5
  • pydantic ==1.10.4
  • pyyaml ==6.0
  • requests ==2.28.1
  • uvicorn ==0.20.0
pyproject.toml pypi
  • email_validator >=1.2
  • lark ~=1.1
  • pydantic ~=1.10,>=1.10.2,!=1.10.7
  • requests ~=2.28