{"id":13698566,"url":"https://github.com/Materials-Consortia/optimade-python-tools","last_synced_at":"2025-05-04T03:31:36.302Z","repository":{"id":32527814,"uuid":"136234321","full_name":"Materials-Consortia/optimade-python-tools","owner":"Materials-Consortia","description":"Tools for implementing and consuming OPTIMADE APIs in Python","archived":false,"fork":false,"pushed_at":"2025-05-02T21:20:41.000Z","size":119828,"stargazers_count":75,"open_issues_count":104,"forks_count":45,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-05-02T22:24:58.359Z","etag":null,"topics":["openapi","optimade","optimade-api","optimade-python","optimade-specification","python"],"latest_commit_sha":null,"homepage":"https://www.optimade.org/optimade-python-tools/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Materials-Consortia.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-06-05T21:00:07.000Z","updated_at":"2025-05-02T21:17:28.000Z","dependencies_parsed_at":"2023-10-16T06:24:20.710Z","dependency_job_id":"2fd4387e-b635-4f39-b4f0-919c0bc60fe7","html_url":"https://github.com/Materials-Consortia/optimade-python-tools","commit_stats":{"total_commits":1400,"total_committers":32,"mean_commits":43.75,"dds":0.6035714285714286,"last_synced_commit":"39a423e03b7b41f9a5b41ea693df7fe0ed41ac61"},"previous_names":[],"tags_count":112,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-python-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-python-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-python-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-python-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Materials-Consortia","download_url":"https://codeload.github.com/Materials-Consortia/optimade-python-tools/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252117371,"owners_count":21697566,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["openapi","optimade","optimade-api","optimade-python","optimade-specification","python"],"created_at":"2024-08-02T19:00:49.730Z","updated_at":"2025-05-04T03:31:36.058Z","avatar_url":"https://github.com/Materials-Consortia.png","language":"Python","readme":"\u003c!-- markdownlint-disable MD033 --\u003e\n\u003c!-- markdownlint-disable-next-line MD041 --\u003e\n\u003cdiv align=\"center\" style=\"padding-bottom: 1em;\"\u003e\n\u003cimg width=\"100px\" align=\"center\" src=\"https://matsci.org/uploads/default/original/2X/b/bd2f59b3bf14fb046b74538750699d7da4c19ac1.svg\"\u003e\n\u003c/div\u003e\n\n# \u003cdiv align=\"center\"\u003eOPTIMADE Python tools\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://doi.org/10.21105/joss.03458\"\u003e\u003cimg alt=\"JOSS DOI\" src=\"https://img.shields.io/badge/JOSS-10.21105%2Fjoss.03458-blueviolet\"\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ctable\u003e\n\u003cthead align=\"center\"\u003e\n\u003ctr\u003e\u003cth align=\"center\"\u003eLatest release\u003c/th\u003e\u003cth align=\"center\"\u003eBuild status\u003c/th\u003e\u003cth align=\"center\"\u003eActivity\u003c/th\u003e\u003c/tr\u003e\n\u003c/thead\u003e\n\n\u003ctbody\u003e\n\u003ctr\u003e\n  \u003ctd align=\"center\"\u003e\n    \u003ca href=\"https://pypi.org/project/optimade\"\u003e\u003cimg alt=\"PyPI version\" src=\"https://img.shields.io/pypi/v/optimade?logo=pypi\u0026logoColor=white\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"https://pypi.org/project/optimade\"\u003e\u003cimg alt=\"PyPI - Python Version\"  src=\"https://img.shields.io/pypi/pyversions/optimade?logo=python\u0026logoColor=white\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"https://github.com/Materials-Consortia/OPTIMADE\"\u003e\u003cimg alt=\"OPTIMADE version\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/main/optimade-version.json\"\u003e\u003c/a\u003e\n  \u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\n    \u003ca href=\"https://github.com/Materials-Consortia/optimade-python-tools/actions?query=branch%3Amain+\"\u003e\u003cimg alt=\"Build Status\" src=\"https://img.shields.io/github/actions/workflow/status/Materials-Consortia/optimade-python-tools/ci.yml?logo=github\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"https://optimade.org/optimade-python-tools\"\u003e\u003cimg alt=\"Docs\" src=\"https://img.shields.io/github/actions/workflow/status/Materials-Consortia/optimade-python-tools/ci_cd_updated_main.yml?label=docs\u0026logo=github\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"https://codecov.io/gh/Materials-Consortia/optimade-python-tools\"\u003e\u003cimg alt=\"Codecov\" src=\"https://img.shields.io/codecov/c/github/Materials-Consortia/optimade-python-tools?logo=codecov\u0026logoColor=white\u0026token=UJAtmqkZZO\"\u003e\u003c/a\u003e\u003cbr\u003e\n  \u003c/td\u003e\n  \u003ctd align=\"center\"\u003e\n    \u003ca href=\"https://github.com/Materials-Consortia/optimade-python-tools/pulse\"\u003e\u003cimg alt=\"Commit Activity\" src=\"https://img.shields.io/github/commit-activity/m/Materials-Consortia/optimade-python-tools?logo=github\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"https://github.com/Materials-Consortia/optimade-python-tools/commits/main\"\u003e\u003cimg alt=\"Last Commit\" src=\"https://img.shields.io/github/last-commit/Materials-Consortia/optimade-python-tools/main?logo=github\"\u003e\u003c/a\u003e\u003cbr\u003e\n    \u003ca href=\"https://github.com/Materials-Consortia/optimade-python-tools/graphs/contributors\"\u003e\u003cimg alt=\"Contributors\" src=\"https://badgen.net/github/contributors/Materials-Consortia/optimade-python-tools?icon=github\"\u003e\u003c/a\u003e\n  \u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\n\u003c/div\u003e\n\nThe aim of [OPTIMADE](https://optimade.org) is to develop a common API, compliant with the [JSON:API 1.0](http://jsonapi.org/format/1.0/) specification.\nThis is to enable interoperability among databases that serve crystal structures and calculated properties of existing and hypothetical materials.\n\nThis repository contains a library of tools for implementing and consuming [OPTIMADE APIs](https://www.optimade.org) using Python:\n\n1. [pydantic](https://github.com/pydantic/pydantic) data models for all [OPTIMADE entry types](https://www.optimade.org/optimade-python-tools/latest/all_models/) and endpoint responses, and a [Lark](https://github.com/lark-parser/lark) [EBNF grammar](https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form) implementation for the OPTIMADE filter language.\n1. Adapters to map OPTIMADE data to and from many commonly used atomistic Python frameworks (e.g., [pymatgen](https://pymatgen.org/), [ASE](https://wiki.fysik.dtu.dk/ase/)) and crystallographic file types (e.g., [CIF](https://www.iucr.org/resources/cif)), using the `optimade.adapters` module.\n1. 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](https://optimade.fly.dev)! The OpenAPI schemas of the server are used to construct the [OPTIMADE schemas](https://schemas.optimade.org/) site.\n1. An [OPTIMADE client](https://www.optimade.org/optimade-python-tools/latest/getting_started/client/) (`optimade-get`) that can query multiple [OPTIMADE providers](https://optimade.org/providers-dashboard) concurrently with a given filter, at the command-line or from Python code.\n1. A fuzzy API validator tool, which may be called from the shell (`optimade-validator`) or used as a GitHub Action from [optimade-validator-action](https://github.com/Materials-Consortia/optimade-validator-action); this validator is used to construct the [providers dashboard](https://optimade.org/providers-dashboard).\n\n\n## Documentation\n\nThis document, guides, and the full module API documentation can be found online at [https://optimade.org/optimade-python-tools](https://optimade.org/optimade-python-tools).\nIn particular, documentation of the OPTIMADE API response data models (implemented here with [pydantic](https://github.com/pydantic/pydantic)) can be found online under [OPTIMADE Data Models](https://optimade.org/optimade-python-tools/latest/all_models).\n\nThe release history and changelog can be found in [the changelog](CHANGELOG.md).\n\n## Installation\n\nDetailed installation instructions for different use cases (e.g., using the library or running a server) can be found in [the installation documentation](INSTALL.md).\n\nThe latest stable version of this package can be obtained from [PyPI](https://pypi.org/project/optimade):\n\n```shell\npip install optimade\n```\n\nThe latest development version of this package can be obtained from the main branch of this repository:\n\n```shell\ngit clone https://github.com/Materials-Consortia/optimade-python-tools\n```\n\n## Supported OPTIMADE versions\n\nEach release of the `optimade` package from this repository only targets one version of the OPTIMADE specification, summarised in the table below.\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ctable\u003e\n\n\u003cthead\u003e\n    \u003ctr\u003e\n        \u003cth align=\"center\"\u003eOPTIMADE API version\u003c/th\u003e\n        \u003cth align=\"center\"\u003e\u003ccode\u003eoptimade\u003c/code\u003e requirements\u003c/th\u003e\n    \u003c/tr\u003e\n\u003c/thead\u003e\n\n\u003ctbody\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Materials-Consortia/OPTIMADE/blob/v1.0.0/optimade.rst\"\u003ev1.0.0\u003c/a\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003ccode\u003eoptimade\u003c=0.12.9\u003c/code\u003e\u003c/td\u003e  \n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Materials-Consortia/OPTIMADE/blob/v1.1.0/optimade.rst\"\u003ev1.1.0\u003c/a\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003ccode\u003eoptimade\u003e=0.16,\u003c1.2\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd align=\"center\"\u003e\u003ca href=\"https://github.com/Materials-Consortia/OPTIMADE/blob/v1.2.0/optimade.rst\"\u003ev1.2.0\u003c/a\u003e\u003c/td\u003e\n        \u003ctd align=\"center\"\u003e\u003ccode\u003eoptimade\u003e=1.2.0\u003c/code\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\n\u003c/div\u003e\n\n## Contributing and Getting Help\n\nAll development of this package (bug reports, suggestions, feedback and pull requests) occurs in the [optimade-python-tools GitHub repository](https://github.com/Materials-Consortia/optimade-python-tools).\nContribution guidelines and tips for getting help can be found in the [contributing notes](CONTRIBUTING.md).\n\n## How to cite\n\nIf you use this package to access or serve OPTIMADE data, we kindly request that you cite the following:\n\n- 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](https://doi.org/10.1039/D4DD00039K)\n- Andersen *et al.*, OPTIMADE, an API for exchanging materials data, *Sci. Data* **8**, 217 (2021) [10.1038/s41597-021-00974-z](https://doi.org/10.1038/s41597-021-00974-z)\n- 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](https://doi.org/10.21105/joss.03458)\n\n## Links\n\n- [OPTIMADE Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst), the human-readable specification that this library is based on.\n- [optimade-validator-action](https://github.com/Materials-Consortia/optimade-validator-action), a GitHub action that can be used to validate implementations from a URL (using the validator from this repo).\n- [OpenAPI](https://github.com/OAI/OpenAPI-Specification), the machine-readable format used to specify the OPTIMADE API in [`openapi.json`](openapi/openapi.json) and [`index_openapi.json`](openapi/index_openapi.json).\n- [Interactive documentation](https://petstore.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/main/openapi/openapi.json) generated from [`openapi.json`](openapi/openapi.json) (see also [interactive JSON editor](https://editor.swagger.io/?url=https://raw.githubusercontent.com/Materials-Consortia/optimade-python-tools/main/openapi/openapi.json)).\n- [pydantic](https://pydantic-docs.helpmanual.io/), the library used for generating the OpenAPI schema from [Python models](https://www.optimade.org/optimade-python-tools/all_models/).\n- [FastAPI](https://fastapi.tiangolo.com/), the framework used for generating the reference implementation expressed by the [`openapi.json`](openapi/openapi.json) specification.\n- [Lark](https://github.com/lark-parser/lark), the library used to parse the filter language in OPTIMADE queries.\n","funding_links":[],"categories":["Datasets","Software and products"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMaterials-Consortia%2Foptimade-python-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FMaterials-Consortia%2Foptimade-python-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FMaterials-Consortia%2Foptimade-python-tools/lists"}