{"id":24711226,"url":"https://github.com/materials-consortia/optimade-tutorial-exercises","last_synced_at":"2025-10-09T11:30:36.711Z","repository":{"id":45060468,"uuid":"399904741","full_name":"Materials-Consortia/optimade-tutorial-exercises","owner":"Materials-Consortia","description":"Tutorial exercises for the OPTIMADE API","archived":false,"fork":false,"pushed_at":"2023-09-27T08:32:31.000Z","size":1667,"stargazers_count":15,"open_issues_count":2,"forks_count":7,"subscribers_count":12,"default_branch":"main","last_synced_at":"2024-11-13T03:34:49.344Z","etag":null,"topics":["materials-design","materials-informatics","optimade","optimade-api"],"latest_commit_sha":null,"homepage":"https://optimade.org","language":"Jupyter Notebook","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":null,"contributing":null,"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}},"created_at":"2021-08-25T17:33:15.000Z","updated_at":"2024-10-02T13:18:15.000Z","dependencies_parsed_at":"2023-02-10T04:01:00.970Z","dependency_job_id":"3cd17e50-d20a-4734-8f79-a2757bb4cb67","html_url":"https://github.com/Materials-Consortia/optimade-tutorial-exercises","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-tutorial-exercises","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-tutorial-exercises/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-tutorial-exercises/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Materials-Consortia%2Foptimade-tutorial-exercises/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Materials-Consortia","download_url":"https://codeload.github.com/Materials-Consortia/optimade-tutorial-exercises/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235813569,"owners_count":19048989,"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":["materials-design","materials-informatics","optimade","optimade-api"],"created_at":"2025-01-27T07:14:17.091Z","updated_at":"2025-10-09T11:30:31.001Z","avatar_url":"https://github.com/Materials-Consortia.png","language":"Jupyter Notebook","readme":"\u003cdiv class=\"cell markdown\"\u003e\n\n# OPTIMADE Tutorial Exercises\n\n[![Open In\nColab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Materials-Consortia/optimade-tutorial-exercises/blob/main/notebooks/exercises.ipynb)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Materials-Consortia/optimade-tutorial-exercises/HEAD?filepath=notebooks%2Fexercises.ipynb)\n[![GitHub\nlicense](https://img.shields.io/github/license/Materials-Consortia/optimade-tutorial-exercises?logo=GitHub)](https://github.com/Materials-Consortia/optimade-tutorial-exercises)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Preface\n\nThis repository hosts general tutorials on the OPTIMADE specification\nand particular database implementations of the API. These open-ended\nexercises were initially provided to accompany the following workshops:\n\n- NOMAD CoE [Tutorial 6:\n  OPTIMADE](https://th.fhi-berlin.mpg.de/meetings/nomad-tutorials/index.php?n=Meeting.Tutorial6),\n  7-8 September 2021\n- ICTP-EAIFR [Training School: Working with Materials Databases and\n  OPTIMADE](https://eaifr.ictp.it/about/news/ml-for-es-and-md/),\n  November-December 2021.\n- CECAM Flagship Workshop [Open Databases Integration for Materials\n  Design](https://www.cecam.org/workshop-details/1120), May 30, 2022 -\n  June 3, 2022.\n- [Actively Learning Materials\n  Science](https://sites.utu.fi/al4ms2023/), Aalto University, February\n  27, 2023 - March 3, 2023.\n\nThis document is hosted on\n[GitHub](https://github.com/Materials-Consortia/optimade-tutorial-exercises),\nand all feedback or suggestions for new exercises can be provided as an\nissue or pull request in that repository.\n\nIf you would like to get involved with the OPTIMADE consortium, you can\nfind some more details on the [OPTIMADE home\npage](https://optimade.org/#get-involved).\n\n### Contributors\n\n- [Matthew Evans](https://ml-evs.science), *UCLouvain* (repository and\n  general exercises)\n- [Matthew Horton](https://github.com/mkhorton), *LBNL* (`pymatgen`\n  exercise)\n- [Evgeny Blokhin](https://tilde.pro), *Tilde Materials Informatics*\n  (typos and bug fixes)\n- [Cormac Toher](https://github.com/ctoher), *Duke University* (AFLOW\n  exercise)\n- [Abhijith Gopakumar](https://github.com/tachyontraveler),\n  *Northwestern U.* (OQMD exercise)\n- [Johan Bergsma](https://github.com/JPBergsma), *CECAM* (typos, testing\n  and feedback)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Introduction\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThe OPTIMADE specification defines a web-based JSON API that is\nimplemented by many [different materials\ndatabases](https://www.optimade.org/providers-dashboard) to allow users\nto query the underlying data with the same syntax and response format.\nThere are several tools that can access these APIs, for example, any web\nbrowser, any programming language that can make HTTP requests, or common\ncommand-line tools such as `curl` or `wget`.\n\nThere are also specialist tools, developed by members of the OPTIMADE\ncommunity. You may have heard about three such tools in other tutorials\nand talks:\n\n1.  [The Materials Cloud web-based OPTIMADE\n    client](https://materialscloud.org/optimadeclient/).\n2.  [The optimade.science web-based\n    aggregator](https://optimade.science).\n3.  [`pymatgen`'s built-in OPTIMADE\n    client](https://pymatgen.org/pymatgen.ext.html#pymatgenextoptimade-module).\n4.  [`optimade-python-tools`'s\n    `OptimadeClient`](https://www.optimade.org/optimade-python-tools/latest/getting_started/client/)\n\nSome of these clients can send requests to multiple OPTIMADE providers\n*simultaneously*, based on programmatic [providers\nlist](https://providers.optimade.org/). You can explore this list at the\nhuman-readable [providers\ndashboard](https://www.optimade.org/providers-dashboard/), where you can\nsee the current OPTIMADE structure count exceeds 26 million!\n\nYou may wish to familiarise yourselves with the OPTIMADE API by writing\nyour own queries, scripts or code. Some possible options:\n\n- Craft (or copy) your own URL queries to a particular OPTIMADE\n  implementation. Some web browsers (e.g., Firefox) will automatically\n  format the JSON response for you (see Exercise 1).\n- Use command-line tools such as [`curl`](https://curl.se/) or\n  [`wget`](https://www.gnu.org/software/wget/) to receive data in your\n  terminal, or pipe it to a file. You could use the tool\n  [`jq`](https://stedolan.github.io/jq/) to format the JSON response.\n- Make an appropriate HTTP request from your programming language of\n  choice. For Python, you could use the standard library\n  [urllib.request](https://docs.python.org/3/library/urllib.request.html)\n  or the more ergonomic external libraries\n  [requests](https://docs.python-requests.org/en/latest/index.html) and\n  [httpx](https://www.python-httpx.org). Some example code for Python is\n  provided below the exercises. In Javascript, you can just use\n  `fetch(...)` or a more advanced OPTIMADE client such as that provided\n  by Tilde Informatics'\n  [optimade-client](https://github.com/tilde-lab/optimade-client).\n\nIf you are following these tutorials as part of a school or workshop,\nplease do not hesitate to ask about how to get started with any of the\nabove tools!\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 1\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThis aim of this exercise is to familiarise yourself with the OPTIMADE\nJSON API. In the recent OPTIMADE paper \\[[1](#ref1)\\], we provided the\nnumber of results to a set of queries across all OPTIMADE\nimplementations, obtained by applying the same filter to the structures\nendpoint of each database. The filters are:\n\n- Query for structures containing a group IV element:\n  `elements HAS ANY \"C\", \"Si\", \"Ge\", \"Sn\", \"Pb\"`.\n\n- As above, but return only binary phases:\n  `elements HAS ANY \"C\", \"Si\", \"Ge\", \"Sn\", \"Pb\" AND nelements=2`.\n\n- This time, exclude lead and return ternary phases:\n  `elements HAS ANY \"C\", \"Si\", \"Ge\", \"Sn\" AND NOT elements HAS \"Pb\" AND elements LENGTH 3`.\n\n- In your browser, try visiting the links in Table 1 of the OPTIMADE\n  paper \\[[1](#ref1)\\] (clickable links in arXiv version\n  \\[[2](#ref2)\\]), which is reproduced below.\n\n  - Familiarise yourself with the standard JSON:API output fields\n    (`data`, `meta` and `links`).\n  - You will find the crystal structures returned for the query as a\n    list under the `data` key, with the OPTIMADE-defined fields listed\n    under the `attributes` of each list entry.\n  - The `meta` field provides useful information about your query, e.g.\n    `data_returned` shows how many results there are in total, not just\n    in the current page of the response (you can check if the table\n    still contains the correct number of entries, or if it is now out of\n    date).\n  - The `links` field provides links to the next or previous pages of\n    your response, in case you requested more structures than the\n    `page_limit` for that implementation.\n\n- Choose one particular entry to focus on: replace the `filter` URL\n  parameter with `/\u003cstructure_id\u003e` for the `id` of one particular\n  structure (e.g.\n  `https://example.org/optimade/v1/structures/\u003cstructure_id\u003e`).\n\n- Explore other endpoints provided by each of these providers. If they\n  serve \"extra\" fields (i.e. those containing the provider prefix), try\n  to find out what these fields mean by querying the `/info/structures`\n  endpoint.\n\n- Try performing the same queries with some of the tools listed above,\n  or in scripts of your own design.\n\n\u003ccenter\u003e\n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003cth\u003eProvider\u003c/th\u003e\n        \u003cth\u003eN\u003csub\u003e1\u003c/sub\u003e\u003c/th\u003e\n        \u003cth\u003eN\u003csub\u003e2\u003c/sub\u003e\u003c/th\u003e\n        \u003cth\u003eN\u003csub\u003e3\u003c/sub\u003e\u003c/th\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"http://www.aflow.org\"\u003eAFLOW\u003c/a\u003e\u003cspan class=\"citation\" data-cites=\"AFLOW_database aflow_fleet_chapter\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://aflow.org/API/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e700,192\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://aflow.org/API/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e62,293\u003c/a\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://aflow.org/API/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e382,554\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/cod\"\u003eCrystallography Open Database\u003c/a\u003e (COD)\u003cspan class=\"citation\" data-cites=\"Grazulis_COD_2009 Grazulis_COD_2012\"\u003e\u003c/span\u003e\u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/cod/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e416,314\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/cod/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e3,896\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/cod/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e32,420\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/tcod\"\u003eTheoretical Crystallography Open Database\u003c/a\u003e (TCOD)\u003cspan class=\"citation\" data-cites=\"Merkys_TCOD_2017\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/tcod/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e2,631\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/tcod/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e296\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://www.crystallography.net/tcod/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e660\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"https://materialscloud.org\"\u003eMaterials Cloud\u003c/a\u003e\u003cspan class=\"citation\" data-cites=\"AiiDA AiiDA2 MaterialsCloud\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://aiida.materialscloud.org/optimade-sample/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e886,518\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://aiida.materialscloud.org/optimade-sample/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e801,382\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://aiida.materialscloud.org/optimade-sample/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e103,075\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"http://materialsproject.org\"\u003eMaterials Project\u003c/a\u003e\u003cspan class=\"citation\" data-cites=\"Materials_Project Jain_2011 Ong_pymatgen_2013 Mathew_Atomate_CMS_2017\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://optimade.materialsproject.org/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e27,309\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://optimade.materialsproject.org/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e3,545\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://optimade.materialsproject.org/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e10,501\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"https://nomad-lab.eu\"\u003eNovel Materials Discovery Laboratory\u003c/a\u003e (NOMAD)\u003cspan class=\"citation\" data-cites=\"NOMAD_2017 NOMAD_2018\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://nomad-lab.eu/prod/rae/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e3,359,594\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://nomad-lab.eu/prod/rae/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e532,123\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://nomad-lab.eu/prod/rae/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e1,611,302\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"https://odbx.science\"\u003eOpen Database of Xtals\u003c/a\u003e (odbx)\u003cspan class=\"citation\" data-cites=\"odbx-matador\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://optimade.odbx.science/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e55\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://optimade.odbx.science/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e54\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"https://optimade.odbx.science/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e0\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"http://openmaterialsdb.se\"\u003eOpen Materials Database\u003c/a\u003e (\u003cem\u003eomdb\u003c/em\u003e)\u003cspan class=\"citation\" data-cites=\"HTTKOMDB\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://optimade.openmaterialsdb.se/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e58,718\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://optimade.openmaterialsdb.se/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e690\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://optimade.openmaterialsdb.se/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e7,428\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003e\u003ca href=\"http://oqmd.org\"\u003eOpen Quantum Materials Database\u003c/a\u003e (OQMD)\u003cspan class=\"citation\" data-cites=\"OQMD\"\u003e\u003c/span\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://oqmd.org/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot;\"\u003e153,113\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://oqmd.org/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot;,\u0026quot;Pb\u0026quot; AND nelements=2\"\u003e11,011\u003c/a\u003e \u003c/td\u003e\n        \u003ctd\u003e\u003ca href=\"http://oqmd.org/optimade/v1/structures?filter=elements HAS ANY \u0026quot;C\u0026quot;,\u0026quot;Si\u0026quot;,\u0026quot;Ge\u0026quot;,\u0026quot;Sn\u0026quot; AND NOT elements HAS \u0026quot;Pb\u0026quot; AND elements LENGTH 3\"\u003e70,252\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\u003c/center\u003e\n\n\u003cspan id=\"ref1\"\u003e\\[1\\]\u003c/span\u003e Andersen *et al.*, \"OPTIMADE, an API for\nexchanging materials data\", *Sci Data* **8**, 217 (2021)\n[10.1038/s41597-021-00974-z](https://doi.org/10.1038/s41597-021-00974-z).\n\n\u003cspan id=\"ref2\"\u003e\\[2\\]\u003c/span\u003e Andersen *et al.*, \"OPTIMADE, an API for\nexchanging materials data\" (2021)\n[arXiv:2103.02068](https://arxiv.org/abs/2103.02068).\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 2\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThe filters from Exercise 1 screened for group IV containing compounds,\nfurther refining the query to exclude lead, and finally to include only\nternary phases.\n\n- Choose a suitable database and modfiy the filters from Exercise 1 to\n  search for binary \\[III\\]-\\[V\\] semiconductors.\n  - A \"suitable\" database here is one that you think will have good\n    coverage across this chemical space.\n- Using the `chemical_formula_anonymous` field, investigate the most\n  common stoichiometric ratios between the constituent elements, e.g.\n  1:1, 2:1, etc.\n  - You may need to follow pagination links (`links-\u003enext` in the\n    response) to access all available data for your query, or you can\n    try adding the `page_limit=100` URL parameter to request more\n    structures per response.\n- Apply the same filter to another database and assess the similarity\n  between the results, thinking carefully about how the different\n  focuses of each database and different methods in their\n  construction/curation could lead to biases in this outcome.\n  - For example, an experimental database may have one crystal structure\n    entry per experimental sample studied, in which case the most useful\n    (or \"fashionable\") compositions will return many more entries,\n    especially when compared to a database that curates crystal\n    structures such that each ideal crystal has one canonical entry\n    (e.g., a database of minerals).\n- Try to use the query you have constructed in the multi-provider\n  clients (linked above), to query all OPTIMADE providers\n  simultaneously.\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 3 (pymatgen)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThis interactive exercise will explore the use of the OPTIMADE client\nimplemented in the `pymatgen` Python library. This exercise can be found\nin this repository under `./notebooks/demonstration-pymatgen.ipynb` or\naccessed online in [Google\nColab](https://colab.research.google.com/github/Materials-Consortia/optimade-tutorial-exercises/blob/main/notebooks/demonstration-pymatgen-for-optimade-queries.ipynb)\n(or equivalent notebook runners, such as\n[Binder](https://mybinder.org/v2/gh/Materials-Consortia/optimade-tutorial-exercises/HEAD?filepath=notebooks%2Fdemonstration-pymatgen-for-optimade-queries.ipynb)).\n\n[![Open In\nColab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Materials-Consortia/optimade-tutorial-exercises/blob/main/notebooks/demonstration-pymatgen-for-optimade-queries.ipynb)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Materials-Consortia/optimade-tutorial-exercises/HEAD?filepath=notebooks%2Fdemonstration-pymatgen-for-optimade-queries.ipynb)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 4\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThere are many useful properties that the OPTIMADE specification has not\nstandardized. This is typically because the use of the property requires\nadditional context, e.g., reporting a \"band gap\" without describing how\nit was calculated or measured, or properties that are only meaningful in\nthe context of a database, e.g., relative energies that depend on other\nreference calculations. For this reason, the OPTIMADE specification\nallows implementations to serve their own fields with an appropriate\n\"provider prefix\" to the field name, and a description at the\n`/info/structures` endpoint.\n\nOne computed property that is key to many high-throughput studies is the\n*chemical stability* ($\\delta$) of a crystal structure, i.e. whether the\nstructure is predicted to spontaneously decompose into a different phase\n(or phases). This is typically computed as the distance from the convex\nhull in composition-energy space, with a value of 0 (or \\\u003c0, if the\ntarget structure was not used to compute the hull itself) indicating a\nstable structure.\n\n- Interrogate the `/info/structures` endpoints of the OPTIMADE\n  implementations that serve DFT data (e.g., Materials Project, AFLOW,\n  OQMD, etc.) and identify those that serve a field that could\n  correspond to hull distance, or other stability metrics.\n- Construct a filter that allows you to screen a database for metastable\n  materials (i.e., $0 \u003c \\delta \u003c 25\\text{ meV/atom}$) according to this\n  metric.\n- Try to create a filter that can be applied to multiple databases\n  simultaneously (e.g., apply\n  `?filter=_databaseA_hull_distance \u003c 25 OR _databaseB_stability \u003c 25`).\n  What happens when you run this filter against a database that does not\n  contain the field?\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 5\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nAs a final general exercise, consider your own research problems and how\nyou might use OPTIMADE. If you have any suggestions or feedback about\nhow OPTIMADE can be made more useful for you, please start a discussion\non the [OPTIMADE MatSci forum](https://matsci.org/c/optimade/29) or\nraise an issue at the appropriate [Materials-Consortia\nGitHub](https://github.com/Materials-Consortia/) repository.\n\nSome potential prompts:\n\n- What additional fields or entry types should OPTIMADE standardize to\n  be most useful to you?\n- How could the existing tools be improved, or what new tools could be\n  created to make OPTIMADE easier to use?\n- What features from other APIs/databases that you use could be adopted\n  within OPTIMADE?\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 6 (AFLOW)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThe AFLOW database is primarily built by decorating crystallographic\nprototypes, and a list of the most common prototypes can be found in the\n[Library of Crystallographic\nPrototypes](https://aflow.org/prototype-encyclopedia/). The prototype\nlabels can also be used to search the database for entries with relaxed\nstructures matching a particular prototype, using the AFLOW keyword\n`aflow_prototype_label_relax`; a full list of AFLOW keywords can be\nfound at AFLOW's `/info/structures` endpoint\n(\u003chttp://aflow.org/API/optimade/v1.0/info/structures\u003e). Searches can be\nperformed for prototype labels using OPTIMADE by appending the `_aflow_`\nprefix to the keyword: `_aflow_aflow_prototype_label_relax`.\n\n- Use OPTIMADE to search AFLOW for NaCl in the rock salt structure\n  (prototype label `AB_cF8_225_a_b`)\n- Use OPTIMADE to search AFLOW for lead-free halide cubic perovskites\n  with a band gap greater than 3 eV: (cubic perovskite prototype label\n  is `AB3C_cP5_221_a_c_b`)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 7 (OQMD)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\nThis interactive exercise explores the OQMD's OPTIMADE API, and\ndemonstrates how you can train machine learning models on OPTIMADE data.\nThe notebook is available at\n`./notebooks/exercise7-oqmd-optimade-tutorial` and can also be accessed\nonline with\n[Colab](https://colab.research.google.com/github/Materials-Consortia/optimade-tutorial-exercises/blob/main/notebooks/exercise7-oqmd-optimade-tutorial.ipynb)\nor\n[Binder](https://mybinder.org/v2/gh/Materials-Consortia/optimade-tutorial-exercises/HEAD?filepath=notebooks/exercise7-oqmd-optimade-tutorial.ipynb)\n(buttons below).\n\n[![Open In\nColab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Materials-Consortia/optimade-tutorial-exercises/blob/main/notebooks/exercise7-oqmd-optimade-tutorial.ipynb)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Materials-Consortia/optimade-tutorial-exercises/HEAD?filepath=notebooks/exercise7-oqmd-optimade-tutorial.ipynb)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n## Exercise 8 (optimade-python-tools)\n\nThis example explores the use of optimade-python-tools for querying and\nserving OPTIMADE data. The notebook is available at\n`./notebooks/exercise8-optimade-python-tools` and can be accessed online\nwith Colab or Biner (buttons below).\n\n[![Open In\nColab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Materials-Consortia/optimade-tutorial-exercises/blob/main/notebooks/exercise8-optimade-python-tools.ipynb)\n[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/Materials-Consortia/optimade-tutorial-exercises/HEAD?filepath=notebooks/exercise8-optimade-python-tools.ipynb)\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell markdown\"\u003e\n\n# Appendix\n\n## Example Python code\n\nYou may find the following Python code snippets useful in the above\nexercises. This document can be opened as a Jupyter notebook using the\nColab or Binder buttons above, or by downloading the notebook from the\nGitHub repository.\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell code\" execution_count=\"1\"\u003e\n\n``` python\n# Construct a query URL.\n#\n# You should be able to use any valid OPTIMADE implementation's\n# database URL with any valid query\n#\n# Lets choose a random provider for now:\nimport random\nsome_optimade_base_urls = [\n    \"https://optimade.materialsproject.org\", \n    \"http://crystallography.net/cod/optimade\", \n    \"https://nomad-lab.eu/prod/rae/optimade/\"\n]\ndatabase_url = random.choice(some_optimade_base_urls)\n\nquery = 'elements HAS ANY \"C\", \"Si\", \"Ge\", \"Sn\", \"Pb\"'\nparams = {\n    \"filter\": query,\n    \"page_limit\": 3\n}\n\nquery_url = f\"{database_url}/v1/structures\"\n```\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell code\"\u003e\n\n``` python\n# Using the third-party requests library:\n!pip install requests\n```\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell code\"\u003e\n\n``` python\n# Import the requests library and make the query\nimport requests\nresponse = requests.get(query_url, params=params)\nprint(response)\njson_response = response.json()\n```\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell code\"\u003e\n\n``` python\n# Explore the first page of results\nimport pprint\nprint(json_response.keys())\nstructures = json_response[\"data\"]\nmeta = json_response[\"meta\"]\n\nprint(f\"Query {query_url} returned {meta['data_returned']} structures\")\n\nprint(\"First structure:\")\npprint.pprint(structures[0])\n```\n\n\u003c/div\u003e\n\n\u003cdiv class=\"cell code\"\u003e\n\n``` python\n# Using pagination to loop multiple requests\n# We want to add additional page_limit and page_offset parameters to the query\noffset = 0\npage_limit = 10\nwhile True:\n    params = {\n        \"filter\": query,\n        \"page_limit\": page_limit,\n        \"page_offset\": offset\n    }\n\n    response = requests.get(query_url, params=params).json()\n\n    # Print the IDs in the response\n    for result in response[\"data\"]:\n        print(result[\"id\"])\n    \n    offset += page_limit\n    if response[\"meta\"][\"data_returned\"] \u003c offset:\n        break\n    \n    if offset \u003e 100:\n        break\n```\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterials-consortia%2Foptimade-tutorial-exercises","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaterials-consortia%2Foptimade-tutorial-exercises","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaterials-consortia%2Foptimade-tutorial-exercises/lists"}