Skip to main content
Chemia Discovery
Browse the documentation

Tool reference

The connector offers 28 tools in 7 groups, all read-only. 8 of them have a full reference page and the others are summarised here. Each entry says what the tool does, so you can find the right one for your task.

At a glance
Tools28
Groups7
Read-only tools28 of 28
Full reference pages8

How are the tools organised?

The tools are grouped by what they are for. Each group below lists its tools with a one-sentence summary.

Access, the daily allowance and limits are explained in Access and limits.

What is in the group "Find materials"?

Search the corpus with a plain-language query, or count how many materials meet some criteria.

Find materials
ToolWhat it does
count_materialsReturns one exact number: how many materials meet some criteria, or how many the dataset holds when no criteria are given. Use it instead of a search whenever the question is "how many".
search_materialsFinds materials from a plain-language description of the properties and composition you want. Returns up to 50 matching rows, the constraints we understood, how many materials were eliminated, and a result_set_id that the other tools use to page, refine, rank and export the full match.

What is in the group "Look up a material"?

Resolve a name, list every entry for a formula, read one property or all of them, and classify materials as metals, semiconductors or insulators.

Look up a material
ToolWhat it does
classify_materialClassifies materials as metal, semi-metal, semiconductor or insulator from their band gap, one result per input in the same order.
find_material_entriesLists every entry that matches a formula, a common name or a Chemia ID, with its structure and stability, so you can see all the polymorphs of a compound and pick the one you mean.
get_all_material_propertiesLists every stored property of one material in a single call, each with its value, unit and kind of evidence, plus the material's structure.
get_material_propertyReads one stored property of one material, with its unit, the kind of evidence it comes from, and the material's structure.
resolve_material_nameResolves a commercial or common name, a formula or a Chemia ID to one canonical material, with its Chemia ID, formula and dataset.

What is in the group "Property distributions and coverage"?

See how a property is distributed across a dataset, and find routes to a property we do not hold directly.

Property distributions and coverage
ToolWhat it does
find_property_proxiesWhen a property is missing or too thin in the corpus, finds ranked routes that reach it through related properties, with each route's equation, stated error, failure modes and the data we actually hold for its inputs.
plot_distributionReturns the histogram and summary statistics of one property across a whole dataset, or across a value range, as data you can draw or describe.
property_statsSummarises how one property is distributed across a dataset: how many values and materials there are, the minimum and maximum, the mean and the 5th, 25th, 50th, 75th and 95th percentiles.

What is in the group "Work with a result set"?

A search returns its matches as a result set. These tools page through it, show what was eliminated, narrow it, rank it, chart it, compare it with an incumbent and export it.

Work with a result set
ToolWhat it does
benchmark_againstCompares the top five of a scored result set with a named incumbent material across the properties the set was scored on.
export_result_setPrepares a CSV or JSON file of an earlier result set's full stored match list and returns a download link and a resource to read it from.
get_result_setPages through the stored matches of an earlier search, up to 50 rows at a time, with the match totals and a next_offset to continue from.
plot_resultsReturns the data behind a chart of an earlier result set (bar, spider or Ashby) for you to draw or describe.
refine_result_setNarrows an earlier search's stored matches with extra property limits or element filters, without re-running the search. Returns a new result set; the original is unchanged.
rerank_result_setRe-orders an earlier result set, either by one property or by a new weighting of its constraints, and returns a new result set.
score_resultsRanks an earlier search's stored matches by a weighted score across its constraints and returns a new result set whose rows are in ranked order.
show_eliminatedShows the candidates an earlier search eliminated, closest miss first, so you can see how near each one came to passing.

What is in the group "Explore the knowledge graph"?

Walk MatKG, the literature-derived knowledge graph: neighbours, paths, applications and substitutes.

Explore the knowledge graph
ToolWhat it does
graph_neighborsLists the entities within a few steps of a material in MatKG, closest first.
graph_shortest_pathFinds the shortest path between two entities in MatKG, step by step.
graph_top_connectedLists the most connected entities in MatKG, to show what the graph covers before you ask about a specific material.
list_applicationsLists the applications that MatKG associates with a material, ranked by how often the literature pairs them.
ontology_expandBroadens a plain-language request through MatKG into candidate materials, material classes and property filters you can use to build a search.
ontology_substitutesSuggests candidate substitutes for a material from shared applications in MatKG, each with its match in the dataset.
plot_knowledge_graphBuilds a hub-and-spoke graph of nodes and edges around one entity from entities you already have, for you to draw.

What is in the group "Orient yourself"?

List the datasets you can query and the capabilities of the wider platform.

Orient yourself
ToolWhat it does
list_capabilitiesLists what this server and the wider Chemia platform can do, grouped by category.
list_material_sourcesLists the datasets this server can query, with their ids, descriptions and whether access to them is restricted.

What is in the group "Computed on demand"?

Values that are not stored and are calculated from outside data when you ask.

Computed on demand
ToolWhat it does
compute_pourbaix_stabilityComputes the Pourbaix decomposition energy of a material, its thermodynamic tendency to decompose in water, from Materials Project data. The value is calculated when you ask and is never stored.