# OPTIMADE client (in Voilà)
[](https://materialscloud.org/optimadeclient/)
[](https://mybinder.org/v2/gh/CasperWA/voila-optimade-client/develop?urlpath=%2Fvoila%2Frender%2FOPTIMADE-Client.ipynb)
Query for and import structures from [OPTIMADE](https://www.optimade.org) providers (COD, MaterialsCloud, NoMaD, Materials Project, ODBX, OQMD, and more ...).
Current supported OPTIMADE API versions: `1.0.0`, `1.0.0-rc.2`, `1.0.0-rc.1`, `0.10.1`
## Run the client
This Jupyter-based app is intended to run either:
- In [AiiDAlab](https://aiidalab.materialscloud.org) as well as inside a [Quantum Mobile](https://materialscloud.org/work/quantum-mobile) Virtual Machine;
- As a [MaterialsCloud tool](https://materialscloud.org/optimadeclient/);
- As a standalone [MyBinder application](https://mybinder.org/v2/gh/CasperWA/voila-optimade-client/develop?urlpath=%2Fvoila%2Frender%2FOPTIMADE-Client.ipynb); or
- As a standalone local application (see more information about this below).
For AiiDAlab, use the App Store in the [Home App](https://github.com/aiidalab/aiidalab-home) to install it.
## Usage
### AiiDAlab
To use the OPTIMADE structure importer in your own AiiDAlab application write the following:
```python
from aiidalab_widget_base import OptimadeQueryWidget
from aiidalab_widgets_base.viewers import StructureDataViewer
from ipywidgets import dlink
structure_query = OptimadeQueryWidget()
structure_viewer = StructureDataViewer()
# Save to `_` in order to suppress output
_ = dlink((structure_query, 'structure'), (structure_viewer, 'structure'))
display(structure_query)
display(structure_viewer)
```
This will immediately display a query widget with a dropdown of current structure databases that implements the OPTIMADE API.
Then you can filter to find a family of structures according to elements, number of elements, chemical formula, and more.
See the [OPTIMADE API specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/master/optimade.rst) for the full list of filter options and their description.
In order to delve deeper into the details of a particular structure, you can also import and display `OptimadeResultsWidget`.
See the notebook [`OPTIMADE-Client.ipynb`](OPTIMADE-Client.ipynb) for an example of how to set up a general purpose OPTIMADE importer.
#### Embedded
The query widget may also be embedded into another app.
For this a more "minimalistic" version of the widget can be used by passing `embedded=True` upon initiating the widget, i.e., `structure_query = OptimadeQueryWidget(embedded=True)`.
Everything else works the same - so you would still have to link up the query widget to the rest of your app.
### General Jupyter notebook
The package's widgets can be used in any general Jupyter notebook as well as AiiDAlab.
Example:
```python
from optimade_client import
OptimadeQueryProviderWidget,
OptimadeQueryFilterWidget,
OptimadeSummaryWidget
from ipywidgets import dlink
database_selector = OptimadeQueryProviderWidget()
structure_query = OptimadeQueryFilterWidget()
structure_viewer = OptimadeSummaryWidget()
# Save to `_` in order to suppress output
_ = dlink((database_selector, 'database'), (structure_query, 'database'))
_ = dlink((structure_query, 'structure'), (structure_viewer, 'entity'))
display(database_selector, structure_query, structure_viewer)
```
This will use the package's own structure viewer and summary widget.
Note, the `OptimadeQueryWidget` mentioned above is a special wrapper widget in AiiDAlab for the `OptimadeQueryProviderWidget` and `OptimadeQueryFilterWidget` widgets.
### Running application locally
First, you will need to install the package either from [PyPI](https://pypi.org/project/optimade-client) or by retrieving the git repository hosted on [GitHub](https://github.com/CasperWA/voila-optimade-client).
#### PyPI
```shell
pip install optimade-client[server]
```
#### GitHub
```shell
git clone https://github.com/CasperWA/voila-optimade-client.git
cd voila-optimade-client
pip install .[server]
```
Note, it is important to install the `server` extra in order to also install the `voila` package (and the `ase` package for a wider variety of download formats).
To now run the application (notebook) [`OPTIMADE-Client.ipynb`](OPTIMADE-Client.ipynb) you can simply run the command `optimade-client` in a terminal and go to the printed URL (usually <http://localhost:8866>) or pass the `--open-browser` option to let the program try to automatically open your default browser.
The application will be run in Voilà using Voilà's own `tornado`-based server.
The configuration will automatically be copied to Jupyter's configuration directory before starting the server.
```shell
optimade-client
```
For a list of all options that can be passed to `optimade-client` use the `-h/--help` option.
## Contribute
If you wish to contribute to the application, you can install it in "editable" mode by using the `-e` flag: `pip install -e .[dev]`.
It is recommended that you use the GitHub-route mentioned above.
You should also install `pre-commit` in the cloned git repository by running:
```shell
pre-commit install
```
To start making contributions, fork the repository and create PRs.
## Configuration (Voilà)
For running the application (in Voilà) on Binder, the configuration file [`jupyter_config.json`](optimade_client/jupyter_config.json) can be used.
If you wish to start the Voilà server locally with the same configuration, either copy the [`jupyter_config.json`](optimade_client/jupyter_config.json) file to your Jupyter config directory, renaming it to `voila.json` or pass the configurations when you start the server using the CLI.
> **Note**: `jupyter_config.json` is automatically copied over as `voila.json` when running the application using the `optimade-client` command.
Locate your Jupyter config directory:
```shell
jupyter --config-dir
/path/to/jupyter/config/dir
```
Example of passing configurations when you start the Voilà server using the CLI:
```shell
voila --enable_nbextensions=True --VoilaExecutePreprocessor.timeout=180 "OPTIMADE-Client.ipynb"
```
To see the full list of configurations you can call `voila` and pass `--help-all`.
### Running with "development" providers (Materials Cloud-specific)
Set the environment variable `OPTIMADE_CLIENT_DEVELOPMENT_MODE` to `1` (the integer version for `True` (`1`) or `False` (`0`)) in order to force the use of development servers for providers (currently only relevant for Materials Cloud).
## License
MIT. The terms of the license can be found in the [LICENSE](LICENSE) file.
## Acknowledgements
| | |
|---|---|
| [](https://www.big-map.eu/) | [BIG-MAP](https://www.big-map.eu/); This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 957189. The project is part of [BATTERY 2030+](https://battery2030.eu/), the large-scale European research initiative for inventing the sustainable batteries of the future. |
## Contact
casper+github@welzel.nu
aiidalab@materialscloud.org
Raw data
{
"_id": null,
"home_page": "https://github.com/CasperWA/voila-optimade-client",
"name": "optimade-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "",
"author": "Casper Welzel Andersen",
"author_email": "casper+github@welzel.nu",
"download_url": "https://files.pythonhosted.org/packages/d3/0c/685701b05d458a7a9d326524765b913a61bad37ad992694b0421b5b4c9c4/optimade-client-2023.8.30.tar.gz",
"platform": null,
"description": "# OPTIMADE client (in Voil\u00e0)\n\n[](https://materialscloud.org/optimadeclient/)\n[](https://mybinder.org/v2/gh/CasperWA/voila-optimade-client/develop?urlpath=%2Fvoila%2Frender%2FOPTIMADE-Client.ipynb)\n\nQuery for and import structures from [OPTIMADE](https://www.optimade.org) providers (COD, MaterialsCloud, NoMaD, Materials Project, ODBX, OQMD, and more ...).\n\nCurrent supported OPTIMADE API versions: `1.0.0`, `1.0.0-rc.2`, `1.0.0-rc.1`, `0.10.1`\n\n## Run the client\n\nThis Jupyter-based app is intended to run either:\n\n- In [AiiDAlab](https://aiidalab.materialscloud.org) as well as inside a [Quantum Mobile](https://materialscloud.org/work/quantum-mobile) Virtual Machine;\n- As a [MaterialsCloud tool](https://materialscloud.org/optimadeclient/);\n- As a standalone [MyBinder application](https://mybinder.org/v2/gh/CasperWA/voila-optimade-client/develop?urlpath=%2Fvoila%2Frender%2FOPTIMADE-Client.ipynb); or\n- As a standalone local application (see more information about this below).\n\nFor AiiDAlab, use the App Store in the [Home App](https://github.com/aiidalab/aiidalab-home) to install it.\n\n## Usage\n\n### AiiDAlab\n\nTo use the OPTIMADE structure importer in your own AiiDAlab application write the following:\n\n```python\nfrom aiidalab_widget_base import OptimadeQueryWidget\nfrom aiidalab_widgets_base.viewers import StructureDataViewer\nfrom ipywidgets import dlink\n\nstructure_query = OptimadeQueryWidget()\nstructure_viewer = StructureDataViewer()\n\n# Save to `_` in order to suppress output\n_ = dlink((structure_query, 'structure'), (structure_viewer, 'structure'))\n\ndisplay(structure_query)\ndisplay(structure_viewer)\n```\n\nThis will immediately display a query widget with a dropdown of current structure databases that implements the OPTIMADE API.\n\nThen you can filter to find a family of structures according to elements, number of elements, chemical formula, and more.\nSee the [OPTIMADE API specification](https://github.com/Materials-Consortia/OPTiMaDe/blob/master/optimade.rst) for the full list of filter options and their description.\n\nIn order to delve deeper into the details of a particular structure, you can also import and display `OptimadeResultsWidget`. \nSee the notebook [`OPTIMADE-Client.ipynb`](OPTIMADE-Client.ipynb) for an example of how to set up a general purpose OPTIMADE importer.\n\n#### Embedded\n\nThe query widget may also be embedded into another app. \nFor this a more \"minimalistic\" version of the widget can be used by passing `embedded=True` upon initiating the widget, i.e., `structure_query = OptimadeQueryWidget(embedded=True)`.\n\nEverything else works the same - so you would still have to link up the query widget to the rest of your app.\n\n### General Jupyter notebook\n\nThe package's widgets can be used in any general Jupyter notebook as well as AiiDAlab.\nExample:\n\n```python\nfrom optimade_client import\n OptimadeQueryProviderWidget,\n OptimadeQueryFilterWidget,\n OptimadeSummaryWidget\nfrom ipywidgets import dlink\n\ndatabase_selector = OptimadeQueryProviderWidget()\nstructure_query = OptimadeQueryFilterWidget()\nstructure_viewer = OptimadeSummaryWidget()\n\n# Save to `_` in order to suppress output\n_ = dlink((database_selector, 'database'), (structure_query, 'database'))\n_ = dlink((structure_query, 'structure'), (structure_viewer, 'entity'))\n\ndisplay(database_selector, structure_query, structure_viewer)\n```\n\nThis will use the package's own structure viewer and summary widget.\n\nNote, the `OptimadeQueryWidget` mentioned above is a special wrapper widget in AiiDAlab for the `OptimadeQueryProviderWidget` and `OptimadeQueryFilterWidget` widgets.\n\n### Running application locally\n\nFirst, you will need to install the package either from [PyPI](https://pypi.org/project/optimade-client) or by retrieving the git repository hosted on [GitHub](https://github.com/CasperWA/voila-optimade-client).\n\n#### PyPI\n\n```shell\npip install optimade-client[server]\n```\n\n#### GitHub\n\n```shell\ngit clone https://github.com/CasperWA/voila-optimade-client.git\ncd voila-optimade-client\npip install .[server]\n```\n\nNote, it is important to install the `server` extra in order to also install the `voila` package (and the `ase` package for a wider variety of download formats).\n\nTo now run the application (notebook) [`OPTIMADE-Client.ipynb`](OPTIMADE-Client.ipynb) you can simply run the command `optimade-client` in a terminal and go to the printed URL (usually <http://localhost:8866>) or pass the `--open-browser` option to let the program try to automatically open your default browser.\n\nThe application will be run in Voil\u00e0 using Voil\u00e0's own `tornado`-based server.\nThe configuration will automatically be copied to Jupyter's configuration directory before starting the server.\n\n```shell\noptimade-client\n```\n\nFor a list of all options that can be passed to `optimade-client` use the `-h/--help` option.\n\n## Contribute\n\nIf you wish to contribute to the application, you can install it in \"editable\" mode by using the `-e` flag: `pip install -e .[dev]`.\nIt is recommended that you use the GitHub-route mentioned above.\n\nYou should also install `pre-commit` in the cloned git repository by running:\n\n```shell\npre-commit install\n```\n\nTo start making contributions, fork the repository and create PRs.\n\n## Configuration (Voil\u00e0)\n\nFor running the application (in Voil\u00e0) on Binder, the configuration file [`jupyter_config.json`](optimade_client/jupyter_config.json) can be used. \nIf you wish to start the Voil\u00e0 server locally with the same configuration, either copy the [`jupyter_config.json`](optimade_client/jupyter_config.json) file to your Jupyter config directory, renaming it to `voila.json` or pass the configurations when you start the server using the CLI.\n\n> **Note**: `jupyter_config.json` is automatically copied over as `voila.json` when running the application using the `optimade-client` command.\n\nLocate your Jupyter config directory:\n\n```shell\njupyter --config-dir\n/path/to/jupyter/config/dir\n```\n\nExample of passing configurations when you start the Voil\u00e0 server using the CLI:\n\n```shell\nvoila --enable_nbextensions=True --VoilaExecutePreprocessor.timeout=180 \"OPTIMADE-Client.ipynb\"\n```\n\nTo see the full list of configurations you can call `voila` and pass `--help-all`.\n\n### Running with \"development\" providers (Materials Cloud-specific)\n\nSet the environment variable `OPTIMADE_CLIENT_DEVELOPMENT_MODE` to `1` (the integer version for `True` (`1`) or `False` (`0`)) in order to force the use of development servers for providers (currently only relevant for Materials Cloud).\n\n## License\n\nMIT. The terms of the license can be found in the [LICENSE](LICENSE) file.\n\n## Acknowledgements\n\n| | |\n|---|---|\n| [](https://www.big-map.eu/) | [BIG-MAP](https://www.big-map.eu/); This project has received funding from the European Union\u2019s Horizon 2020 research and innovation programme under grant agreement No 957189. The project is part of [BATTERY 2030+](https://battery2030.eu/), the large-scale European research initiative for inventing the sustainable batteries of the future. |\n\n## Contact\n\ncasper+github@welzel.nu \naiidalab@materialscloud.org\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Voil\u00e0/Jupyter client for searching through OPTIMADE databases.",
"version": "2023.8.30",
"project_urls": {
"Homepage": "https://github.com/CasperWA/voila-optimade-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "78523fa63d96a8ebb1d226165dcc7087017bac3549c9e19429f1dc77bf99f28b",
"md5": "2bc452675cac01623ae0728ede7fe361",
"sha256": "3a190ac92acf44ef2aed519c81b1a90d3e760ce83c3981f2fb4152389cfc4a08"
},
"downloads": -1,
"filename": "optimade_client-2023.8.30-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2bc452675cac01623ae0728ede7fe361",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 181775,
"upload_time": "2023-08-30T11:30:10",
"upload_time_iso_8601": "2023-08-30T11:30:10.565823Z",
"url": "https://files.pythonhosted.org/packages/78/52/3fa63d96a8ebb1d226165dcc7087017bac3549c9e19429f1dc77bf99f28b/optimade_client-2023.8.30-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d30c685701b05d458a7a9d326524765b913a61bad37ad992694b0421b5b4c9c4",
"md5": "b9bee504d2fb7d2e07d34a51908db96e",
"sha256": "efb580977043b0b6a9625437c782772b3a0907f8c18caa59a1499918b701bd65"
},
"downloads": -1,
"filename": "optimade-client-2023.8.30.tar.gz",
"has_sig": false,
"md5_digest": "b9bee504d2fb7d2e07d34a51908db96e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 178245,
"upload_time": "2023-08-30T11:30:12",
"upload_time_iso_8601": "2023-08-30T11:30:12.492437Z",
"url": "https://files.pythonhosted.org/packages/d3/0c/685701b05d458a7a9d326524765b913a61bad37ad992694b0421b5b4c9c4/optimade-client-2023.8.30.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-30 11:30:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CasperWA",
"github_project": "voila-optimade-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "optimade-client"
}
JSON
