Package: ipyoptimade
OPTIMADE Jupyter widgets and Voilà applicationQuery for and import structures fromOPTIMADEproviders (COD, MaterialsCloud, NoMaD, Materials Project, ODBX, OQMD, and more ...).
The package provides a Jupyter widget for querying OPTIMADE providers and an example Voilà application to stack widgets into an web application.Current supported OPTIMADE API versions:1.1.0,1.0.0,1.0.0-rc.2,1.0.0-rc.1,0.10.1Run the clientThis Jupyter-based app is intended to run either:InAiiDAlabas well as inside aQuantum MobileVirtual Machine;As aMaterialsCloud tool;As a standaloneMyBinder application; orAs a standalone local application (see more information about this below).For AiiDAlab, use the App Store in theHome Appto install it.UsageAiiDAlabTo use the OPTIMADE structure importer in your own AiiDAlab application write the following:fromaiidalab_widget_baseimportOptimadeQueryWidgetfromaiidalab_widgets_base.viewersimportStructureDataViewerfromipywidgetsimportdlinkstructure_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 theOPTIMADE API specificationfor 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 displayOptimadeResultsWidget.See the notebookoptimade-client.ipynbfor an example of how to set up a general purpose OPTIMADE importer.EmbeddedThe query widget may also be embedded into another app.For this a more "minimalistic" version of the widget can be used by passingembedded=Trueupon 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 notebookThe package's widgets can be used in any general Jupyter notebook as well as AiiDAlab.
Example:fromipyoptimadeimportOptimadeQueryProviderWidget,OptimadeQueryFilterWidget,OptimadeSummaryWidgetfromipywidgetsimportdlinkdatabase_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, theOptimadeQueryWidgetmentioned above is a special wrapper widget in AiiDAlab for theOptimadeQueryProviderWidgetandOptimadeQueryFilterWidgetwidgets.Running application locallyTo run the application locally, you need to have Jupyter installed.
You can then run the application by opening the notebookoptimade-client.ipynbin Jupyter and running all cells.
If you have thevoilapackage installed, you can also run the application in Voilà by clicking the Voilà button in the Jupyter notebook toolbar.Configuration (Voilà)For running the application (in Voilà) on Binder, the configuration filejupyter_config.jsoncan be used.If you wish to start the Voilà server locally with the same configuration, either copy thejupyter_config.jsonfile to your Jupyter config directory, renaming it tovoila.jsonor pass the configurations when you start the server using the CLI.Note:jupyter_config.jsonis automatically copied over asvoila.jsonwhen running the application using theoptimade-clientcommand.Locate your Jupyter config directory:jupyter--config-dir
/path/to/jupyter/config/dirExample of passing configurations when you start the Voilà server using the CLI:voila--enable_nbextensions=True--VoilaExecutePreprocessor.timeout=180"OPTIMADE-Client.ipynb"To see the full list of configurations you can callvoilaand pass--help-all.Running with "development" providers (Materials Cloud-specific)Set the environment variableipyoptimade_DEVELOPMENT_MODEto1(the integer version forTrue(1) orFalse(0)) in order to force the use of development servers for providers (currently only relevant for Materials Cloud).ContributeIf you wish to contribute to the application, you can install it in "editable" mode by using the-eflag:pip install -e .[dev].
It is recommended that you use the GitHub-route mentioned above.You should also installpre-commitin the cloned git repository by running:pre-commitinstallTo start making contributions, fork the repository and create PRs.For maintainersTo create a new release, clone the repository, install development dependencies withpip install -e '.[dev]', and then executebumpver update [--major|--minor|--patch] [--tag-num --tag [alpha|beta|rc]].
This will:Create a tagged release with bumped version and push it to the repository.Trigger a GitHub actions workflow that creates a GitHub release and publishes it on PyPI.Additional notes:Use the--dryoption to preview the release change.The release tag (e.g. a/b/rc) is determined from the last release.
Use the--tagoption to switch the release tag.This package followssemantic versioning.LicenseMIT. The terms of the license can be found in theLICENSEfile.AcknowledgementsBIG-MAP; 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 ofBATTERY 2030+, the large-scale European research initiative for inventing the sustainable batteries of the future.Contactcasper+github@welzel.nuaiidalab@materialscloud.org