Improved the Encyclopedia API documentation, made the API input for chemical...

Improved the Encyclopedia API documentation, made the API input for chemical elements into a list instead of a comma-separated string, added license boilerplate to the CLI command that generates the units.js file.

encyclopedia-gui @ 1e27a32e

-Subproject commit 0ca60338acd93d10f70fc66f5a64bec422613f9d
+Subproject commit 1e27a32e5626ba8c7e1a97bc5564ccd2998df559

nomad/app/api/encyclopedia.py

@@ -326,10 +326,10 @@ material_result = api.model("material_result", {
 @ns.route("/materials/<string:material_id>")
 class EncMaterialResource(Resource):
     @api.response(404, "The material does not exist")
-    @api.response(200, "Metadata send", fields.Raw)
-    @api.doc("get_material", params={"material_id": "28 character identifier for the material."})
+    @api.response(200, "Metadata send", material_result)
     @api.expect(material_query)
     @api.marshal_with(material_result, skip_none=True)
+    @api.doc("get_material", params={"material_id": "28 character identifier for the material."})
     @authenticate()
     def get(self, material_id):
         """Used to retrieve basic information related to a material.
@@ -388,7 +388,7 @@ class EncMaterialResource(Resource):
                 except AttributeError:
                     pass
             if similarity:
-                result["similarity"] = similarity
+                result["similarity"] = sorted(similarity, key=lambda x: x["value"], reverse=True)
 
         return result, 200
 
@@ -400,11 +400,11 @@ range_query = api.model("range_query", {
 })
 materials_query = api.model("materials_input", {
     "search_by": fields.Nested(api.model("search_query", {
-        "exclusive": fields.Boolean(default=False),
-        "formula": fields.String,
-        "element": fields.String,
-        "page": fields.Integer(default=1, description="Requested page number, indexing starts from 1."),
-        "per_page": fields.Integer(default=25, description="Number of results per page."),
+        "exclusive": fields.Boolean(default=False, description="Set to True to enable exclusive element search."),
+        "formula": fields.String(description="Chemical formula of the material as a string. The order of elements does not matter.", example="TiO2"),
+        "elements": fields.List(fields.String, description="List of chemical species that the material should include. Use capitalized element name abbreviations.", example=["Ti", "O"]),
+        "page": fields.Integer(default=1, description="Requested page number, indexing starts from 1.", example=1),
+        "per_page": fields.Integer(default=25, description="Number of results per page.", example=10),
         "restricted": fields.Boolean(default=False, description="Select to restrict the query to individual calculations. If not selected, the query will combine results from several different calculations."),
     })),
     "material_type": fields.List(fields.String(enum=list(Material.material_type.type)), description=Material.material_type.description),
@@ -500,7 +500,7 @@ class EncMaterialsResource(Resource):
         # ))
 
         formula = search_by["formula"]
-        elements = search_by["element"]
+        elements = search_by["elements"]
         exclusive = search_by["exclusive"]
 
         # The given list of species/formula is reformatted with the Hill system into a
@@ -539,7 +539,7 @@ class EncMaterialsResource(Resource):
                     species_and_counts={"query": query_string, "operator": "and"}
                 ))
         elif elements is not None:
-            species, _ = get_hill_decomposition(elements.split(","))
+            species, _ = get_hill_decomposition(elements)
             query_string = " ".join(species)
 
             if exclusive:

nomad/cli/dev.py

@@ -791,7 +791,25 @@ def units(ctx):
         assert unit in unit_map, "The unit '{}' is not defined in the unit definitions.".format(unit)
 
     # Print unit conversion table and unit systems as a Javascript source file
-    output = "// Generated by NOMAD CLI. Do not edit manually.\n"
+    output = """/*
+ * Copyright The NOMAD Authors.
+ *
+ * This file is part of NOMAD. See https://nomad-lab.eu for further info.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+// Generated by NOMAD CLI. Do not edit manually.
+"""
     output += "export const unitMap = "
     json_string = json.dumps(unit_map, indent=2)
     json_string = re.sub(r'(?<!: )"(\S*?)":', '\\1:', json_string)

tests/app/test_api_encyclopedia.py

@@ -313,14 +313,14 @@ class TestEncyclopedia():
         # authentication
         rv = api.post(
             '/materials/',
-            data=json.dumps({"search_by": {"element": "B"}}),
+            data=json.dumps({"search_by": {"elements": ["B"]}}),
             content_type='application/json',
         )
         results = rv.json['results']
         assert len(results) == 0
         rv = api.post(
             '/materials/',
-            data=json.dumps({"search_by": {"element": "B"}}),
+            data=json.dumps({"search_by": {"elements": ["B"]}}),
             content_type='application/json',
             headers=test_user_auth,
         )