| Name | optimade-maker JSON |
| Version |
0.6.0
JSON |
| download |
| home_page | None |
| Summary | Tools for making OPTIMADE APIs from raw structural data. |
| upload_time | 2025-08-21 14:53:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <3.13,>=3.10 |
| license | MIT |
| keywords |
optimade
jsonapi
materials
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<div align="center" style="padding: 2em;">
<span style="padding: 1em">
<img height="70px" align="center" src="https://matsci.org/uploads/default/original/2X/b/bd2f59b3bf14fb046b74538750699d7da4c19ac1.svg">
</span>
</div>
# <div align="center">optimade-maker</div>
<div align="center">
[](https://pypi.org/project/optimade-maker/)
</div>
Tools for making [OPTIMADE APIs](https://optimade.org) from various formats of structural data (e.g. an archive of CIF files).
This repository contains the src/optimade-maker Python package and the corresponding CLI tool optimake, which together provide this functionality. Features include
- definition of a config file format (`optimade.yaml`) for annotating data archives to be used in the OPTIMADE ecosystem;
- conversion of the raw data into corresponding OPTIMADE types using pre-existing parsers (e.g., ASE for structures);
- conversion of the annotated data archive into the OPTIMADE JSON Lines file format ([spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#the-optimade-json-lines-format-for-database-exchange)) that can be ingested into a database and used to serve a full OPTIMADE API.
- serving either an annotated data archive or a JSON Lines file as an OPTIMADE API (using the [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/)
reference server implementation).
## Usage
See `./examples` for a more complete set of supported formats and corresponding `optimade.yaml` config files.
### Annotating with `optimade.yaml`
To annotate your structural data for `optimade-maker`, the data archive needs to be accompanied by an `optimade.yaml` config file. The following is a simple example for a zip archive (`structures.zip`) of cif files together with an optional property file (`data.csv`):
```yaml
config_version: 0.1.1
database_description: Simple database
entries:
- entry_type: structures
entry_paths:
- file: structures.zip
matches:
- cifs/*/*.cif
# (optional) property file and definitions:
property_paths:
- file: data.csv
property_definitions:
- name: energy
title: Total energy per atom
description: DFT total energy per atom
unit: eV/atom
type: float
```
### Structure `id`s and property files
`optimade-maker` will assign an `id` for each structure based on its full path in the archive, following a simple deterministic rule: from the set of all archive paths, the maximum common path prefix and postfix (including file extensions) are removed. E.g.
```
structures.zip/cifs/set1/101.cif
structures.zip/cifs/set2/102.cif
```
produces `["set1/101", "set2/102"]`.
The property files need to either refer to these `id`s or the full path in the archive to be associated with a structure. E.g. a possible property `csv` file could be
```csv
id,energy
set1/101,2.5
structures.zip/cifs/set2/102.cif,3.2
```
### Installing and running `optimake`
Install with
```bash
pip install optimade-maker
```
this will also make the `optimake` CLI utility available.
For a folder containing the data archive and the `optimade.yaml` file (such as in `/examples`), run
- `optimake convert .` to just convert the entry into the JSONL format (see below).
- `optimake serve .` to start the OPTIMADE API (this also first converts the entry, if needed);
For more detailed information see also `optimake --help`.
## Relevant links
- [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst)
- [OPTIMADE specification: JSON Lines format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#the-optimade-json-lines-format-for-database-exchange)
## Contributors
The initial prototype was created at the Paul Scherrer Institute, Switzerland, during the week of 12–16 June 2023.
Authors (alphabetical):
- Kristjan Eimre
- Matthew Evans
- Giovanni Pizzi
- Gian-Marco Rignanese
- Jusong Yu
- Xing Wang
Raw data
{
"_id": null,
"home_page": null,
"name": "optimade-maker",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.10",
"maintainer_email": null,
"keywords": "optimade, jsonapi, materials",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/91/c1/c83c78f76c074aacf18d10c9f977f5882aec98eb05a400780e4cb54093d7/optimade_maker-0.6.0.tar.gz",
"platform": null,
"description": "<div align=\"center\" style=\"padding: 2em;\">\n<span style=\"padding: 1em\">\n<img height=\"70px\" align=\"center\" src=\"https://matsci.org/uploads/default/original/2X/b/bd2f59b3bf14fb046b74538750699d7da4c19ac1.svg\">\n</span>\n</div>\n\n# <div align=\"center\">optimade-maker</div>\n\n<div align=\"center\">\n\n[](https://pypi.org/project/optimade-maker/)\n\n\n\n</div>\n\nTools for making [OPTIMADE APIs](https://optimade.org) from various formats of structural data (e.g. an archive of CIF files).\n\nThis repository contains the src/optimade-maker Python package and the corresponding CLI tool optimake, which together provide this functionality. Features include\n\n- definition of a config file format (`optimade.yaml`) for annotating data archives to be used in the OPTIMADE ecosystem;\n- conversion of the raw data into corresponding OPTIMADE types using pre-existing parsers (e.g., ASE for structures);\n- conversion of the annotated data archive into the OPTIMADE JSON Lines file format ([spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#the-optimade-json-lines-format-for-database-exchange)) that can be ingested into a database and used to serve a full OPTIMADE API.\n- serving either an annotated data archive or a JSON Lines file as an OPTIMADE API (using the [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/)\n reference server implementation).\n\n## Usage\n\nSee `./examples` for a more complete set of supported formats and corresponding `optimade.yaml` config files.\n\n### Annotating with `optimade.yaml`\n\nTo annotate your structural data for `optimade-maker`, the data archive needs to be accompanied by an `optimade.yaml` config file. The following is a simple example for a zip archive (`structures.zip`) of cif files together with an optional property file (`data.csv`):\n\n```yaml\nconfig_version: 0.1.1\ndatabase_description: Simple database\n\nentries:\n - entry_type: structures\n entry_paths:\n - file: structures.zip\n matches:\n - cifs/*/*.cif\n # (optional) property file and definitions:\n property_paths:\n - file: data.csv\n property_definitions:\n - name: energy\n title: Total energy per atom\n description: DFT total energy per atom\n unit: eV/atom\n type: float\n```\n\n### Structure `id`s and property files\n\n`optimade-maker` will assign an `id` for each structure based on its full path in the archive, following a simple deterministic rule: from the set of all archive paths, the maximum common path prefix and postfix (including file extensions) are removed. E.g.\n\n```\nstructures.zip/cifs/set1/101.cif\nstructures.zip/cifs/set2/102.cif\n```\n\nproduces `[\"set1/101\", \"set2/102\"]`.\n\nThe property files need to either refer to these `id`s or the full path in the archive to be associated with a structure. E.g. a possible property `csv` file could be\n\n```csv\nid,energy\nset1/101,2.5\nstructures.zip/cifs/set2/102.cif,3.2\n```\n\n### Installing and running `optimake`\n\nInstall with\n\n```bash\npip install optimade-maker\n```\n\nthis will also make the `optimake` CLI utility available.\n\nFor a folder containing the data archive and the `optimade.yaml` file (such as in `/examples`), run\n\n- `optimake convert .` to just convert the entry into the JSONL format (see below).\n- `optimake serve .` to start the OPTIMADE API (this also first converts the entry, if needed);\n\nFor more detailed information see also `optimake --help`.\n\n## Relevant links\n\n- [OPTIMADE specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst)\n- [OPTIMADE specification: JSON Lines format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#the-optimade-json-lines-format-for-database-exchange)\n\n## Contributors\n\nThe initial prototype was created at the Paul Scherrer Institute, Switzerland, during the week of 12\u201316 June 2023.\n\nAuthors (alphabetical):\n\n- Kristjan Eimre\n- Matthew Evans\n- Giovanni Pizzi\n- Gian-Marco Rignanese\n- Jusong Yu\n- Xing Wang\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Tools for making OPTIMADE APIs from raw structural data.",
"version": "0.6.0",
"project_urls": null,
"split_keywords": [
"optimade",
" jsonapi",
" materials"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ed4dadfdd8983636722b0eb029d168e5682d126b2425fb6b8cbccfd61c01471d",
"md5": "73b2b7c9419f21e65ef6bfaafe79b684",
"sha256": "1d73293de0b43109dfae4abe5ff7978fc479eeb4e6d153b5bd83eb98b286a34b"
},
"downloads": -1,
"filename": "optimade_maker-0.6.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "73b2b7c9419f21e65ef6bfaafe79b684",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.10",
"size": 26288,
"upload_time": "2025-08-21T14:53:49",
"upload_time_iso_8601": "2025-08-21T14:53:49.230671Z",
"url": "https://files.pythonhosted.org/packages/ed/4d/adfdd8983636722b0eb029d168e5682d126b2425fb6b8cbccfd61c01471d/optimade_maker-0.6.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "91c1c83c78f76c074aacf18d10c9f977f5882aec98eb05a400780e4cb54093d7",
"md5": "6fe0fd8aece45691f84977b7cddf4637",
"sha256": "5283b6dff31ad460c5382e83501eb7f738b2e98dd11160e91ca9bf7e8e70759b"
},
"downloads": -1,
"filename": "optimade_maker-0.6.0.tar.gz",
"has_sig": false,
"md5_digest": "6fe0fd8aece45691f84977b7cddf4637",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.10",
"size": 1858929,
"upload_time": "2025-08-21T14:53:50",
"upload_time_iso_8601": "2025-08-21T14:53:50.475104Z",
"url": "https://files.pythonhosted.org/packages/91/c1/c83c78f76c074aacf18d10c9f977f5882aec98eb05a400780e4cb54093d7/optimade_maker-0.6.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 14:53:50",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "optimade-maker"
}
