---
title: OpXRD inputs and parameters
description: 'Search filters, similarity queries, and operation configuration for OpXRD.'
tags:
  - opxrd
  - inputs
---

You provide an operation plus its inputs — search filters, a query pattern, or a pattern ID. The `operation` choice is what most shapes the result, since it determines which filters and data each request needs.

## OpXRD inputs and parameters

## Operation selection

The `operation` parameter determines which OpXRD function to execute:

| Operation | Description | Required Inputs |
|-----------|-------------|-----------------|
| `search_patterns` | Filter database by element, formula, or space group | At least one filter |
| `similarity_search` | Find similar patterns using CrystalNN fingerprints | `two_theta_values` + `intensities` |
| `compute_fingerprint` | Generate a fingerprint from a crystal structure | `cif_content` or `structure_dict` |
| `get_pattern` | Retrieve a specific pattern by ID | Pattern ID |
| `list_institutions` | Browse contributing institutions | None |
| `compute_statistics` | Get aggregate database statistics | None |

## search_patterns parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `elements` | string[] | No | `[]` | Filter by element symbols (e.g., `["Fe", "O"]`). Auto-extracted from `chemical_formula` if omitted. |
| `elements_exclusive` | boolean | No | `false` | If `true`, a pattern must contain ONLY the listed elements (exact composition, not a superset) |
| `spacegroup` | integer | No | `null` | Filter by spacegroup **number** (1-230) — not a Hermann-Mauguin symbol |
| `spacegroup_range` | [integer, integer] | No | `null` | Filter by an inclusive spacegroup-number range `[min, max]` |
| `chemical_formula` | string | No | `null` | Chemical formula (e.g., `"Fe2O3"`) |
| `min_atoms` / `max_atoms` | integer | No | `null` | Filter by unit-cell atom count |
| `volume_min` / `volume_max` | number | No | `null` | Filter by unit cell volume (ų) |
| `label_type` | string | No | `null` | `fully_labeled`, `lattice_labeled`, `partially_labeled`, `unlabeled`, or `any` |
| `institution` | string | No | `null` | Filter by contributing institution |
| `max_results` | integer | No | `100` | Maximum patterns to return |

### Element filter examples

| Filter | elements_exclusive | Matches |
|--------|--------------|---------|
| `["Fe", "O"]`, `false` | Iron oxides, iron oxyhydroxides, etc. |
| `["Fe", "O"]`, `true` | Only pure iron-oxygen compounds |
| `["Ti"]`, `false` | Any titanium-containing compound |

## similarity_search parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `two_theta_values` | number[] | Yes | -- | 2-theta values (degrees) of the query pattern |
| `intensities` | number[] | Yes | -- | Intensity values of the query pattern, same length and order as `two_theta_values` |
| `similarity_threshold` | number | No | `0.8` | Minimum similarity score (0.0-1.0) |
| `similarity_metric` | string | No | `"cosine"` | `cosine`, `pearson`, or `euclidean` |
| `max_results` | integer | No | `100` | Maximum similar patterns to return |

There is no separate `pattern_data`/`wavelength` field for this operation — provide the two arrays directly:

```json
{
  "operation": "similarity_search",
  "two_theta_values": [10.0, 20.5, 25.3, 30.1],
  "intensities": [100, 350, 800, 450]
}
```

## compute_fingerprint parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `cif_content` | string | One of the two | CIF file content for the structure to fingerprint |
| `structure_dict` | object | One of the two | Pymatgen structure dict, as an alternative to `cif_content` |

This operation takes a crystal **structure**, not a raw diffraction pattern — it is not the same input shape as `similarity_search`. The platform's tool schema does not currently expose a `cif_content`/`structure_dict` field for OpXRD, so this operation may not be reachable from chat; see [PyWPEM](/docs/pywpem) if you need a fingerprint or comparison derived directly from a raw pattern.

## get_pattern parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `pattern_id` | string | Yes | OpXRD database pattern identifier |

## Shared output options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `offset` | integer | `0` | Pagination offset |
| `include_pattern_data` | boolean | `true` | Include full 2-theta/intensity data in results |
| `include_structure` | boolean | `true` | Include crystal structure details in results |
| `include_fingerprint` | boolean | `false` | Compute and include CrystalNN fingerprints (slower) |

## Input validation rules

- **Elements**: Must be valid element symbols from the periodic table
- **Spacegroup**: A numeric spacegroup (1-230), not a Hermann-Mauguin symbol — use `chemical_formula` or `elements` if you only know the symbol
- **Similarity search**: `two_theta_values` and `intensities` must both be present, with matching lengths
- **Similarity threshold**: Must be between 0.0 and 1.0. Values below 0.5 may return many low-quality matches
- **At least one criterion**: `search_patterns` needs at least one of `elements`, `chemical_formula`, `pattern_id`, `spacegroup`/`spacegroup_range`, or a similarity-search pair — otherwise the tool returns an error rather than the whole database

## Read next