---
title: XTalNet Quickstart
description: Run xtalnet_csp_predict from a SMILES string and sort candidates by energy_kcal, then screen polymorphs or match an experimental PXRD pattern.
---

You want to know what solid form(s) a compound is likely to adopt; this walks through predicting crystal structures from a SMILES string, screening for polymorphs, and matching against an experimental PXRD pattern.

## Crystal structure prediction with XTalNet in .bloom*

## Workflow 1: De novo crystal structure prediction from SMILES

### Step 1: Open XTalNet

Navigate to **Tools > XTalNet** in .bloom*, or ask Ivy:

```
Predict crystal structure forms for aspirin (CC(=O)Oc1ccccc1C(=O)O)
```

### Step 2: Configure the prediction

| Parameter | Value |
|-----------|-------|
| Tool | `xtalnet_csp_predict` |
| `compound_smiles` | `CC(=O)Oc1ccccc1C(=O)O` |
| `num_candidates` | `10` (default) |
| `analysis_level` | `standard` (default) |

### Step 3: Review the candidates

The job returns, on completion:

- `structures_cif`: CIF files for each candidate structure
- `energy_landscape_json`: per-candidate `energy_kcal`, `space_group`, `density`, `cell_parameters`
- `summary_csv`: a flat table of the same fields for quick sorting

Sort by `energy_kcal` — the lowest-energy candidates are the most thermodynamically favorable predictions.

### Step 4: Take a candidate forward

Feed a predicted `structures_cif` entry into [PyWPEM](/docs/pywpem)'s `simulate_xrd` to see what diffraction pattern that structure would produce, or compare it against an experimental pattern with [OpXRD](/docs/opxrd) similarity search.

## Workflow 2: Polymorph screening

Use this when you specifically want a stability-ranked set of polymorphs, or a co-crystal prediction.

### Step 1: Configure the screen

| Parameter | Value |
|-----------|-------|
| Tool | `xtalnet_polymorph_predict` |
| `compound_smiles` | Your compound's SMILES |
| `search_depth` | `standard` (default) — use `thorough` for late-stage candidates |
| `num_candidates` | `25` (default, range 10-50) |
| `temperature` | `298` K (default) — use `310` for body temperature |

Or ask Ivy:

```
Run XtalNet polymorph screening on ritonavir and rank the forms by stability at body temperature
```

For a co-crystal prediction, add a coformer:

```
Predict co-crystals of this compound with nicotinamide
```

which sets `coformer_smiles` to nicotinamide's SMILES (`NC(=O)c1cccnc1`).

### Step 2: Review the ranking

The result's `stability_ranking_json` gives `{forms: [{form_id, energy_kcal, stability_rank, is_metastable}], transition_risks: []}`. The lowest `stability_rank` is the most stable form at the requested temperature; `is_metastable: true` flags forms at risk of converting to a more stable one over time.

### Step 3: Check formulation relevance

If you need solubility and bioavailability context, enable `include_pharmaceutical_properties` (default `true` for polymorph screening) and read `pharmaceutical_properties_csv` — `[form_id, solubility, dissolution_rate, bioavailability_class]` per form.

## Workflow 3: Match an experimental PXRD pattern

If you already measured a diffraction pattern and want to identify which crystal form produced it, provide PXRD data instead of a SMILES string:

| Parameter | Value |
|-----------|-------|
| `pxrd_data` | `[[2theta, intensity], ...]` pairs from your measurement |
| `compound_formula` | Required when matching by PXRD (e.g. `"C9H8O4"`) |
| `pxrd_metadata.wavelength` | Default `1.5406` Å (Cu K-alpha) — set if your instrument differs |

```
Match this experimental PXRD pattern against candidate crystal structures for aspirin (C9H8O4): [[5.0, 100], [10.5, 250], [15.2, 400], ...]
```

## Next steps

- See [inputs & restraints](/docs/xtalnet/inputs) for the full parameter set on both tools
- See [outputs & exports](/docs/xtalnet/outputs) for artifact and metric definitions
- Use [PyWPEM](/docs/pywpem) to simulate the diffraction pattern for a predicted structure, or [OpXRD](/docs/opxrd) to search for a matching experimental one

## Read next