MaterialsAtlas Docs

Doping Recommender

App slug: doping-recommender Category: Utilities & Tools

The Doping Recommender suggests likely n-type and p-type dopants for a host material. It can work from a chemical formula or a host CIF structure. When a CIF is available, the app can also generate doped CIF structures for the highest-ranked candidates.

This tool is intended to help researchers quickly explore substitutional doping ideas before running more expensive DFT, MLIP, or experimental validation workflows.

What The App Does

The app ranks dopant candidates by combining chemically motivated substitution rules with structure-aware information when available.

It can:

recommend electron-donor n-type dopants
recommend electron-acceptor p-type dopants
target specific crystallographic sites, such as only doping the Ti site in SrTiO3
restrict the candidate dopants to a user-defined element list
use manual oxidation states, pymatgen oxidation-state guesses, or BERTOS-assisted oxidation-state prediction
generate doped CIF files for selected top candidates
optionally run approximate MACE stability screening on generated doped structures

Inputs

Formula And Options

Use the text box for a host formula and optional key-value settings.

Basic formula example:

formula=SrTiO3

Target only one host site:

formula=SrTiO3
target_sites=Ti

Restrict allowed dopants:

formula=SrTiO3
allowed_dopants=La,Nb,Fe,Mn,Co,Al

Provide oxidation states manually:

formula=SrTiO3
oxidation_states=Sr:2,Ti:4,O:-2

Combine options:

formula=SrTiO3
target_sites=Ti
allowed_dopants=La,Nb,Fe,Mn,Co,Al
oxidation_states=Sr:2,Ti:4,O:-2

Supported text keys:

Key	Meaning	Example
`formula`	Host chemical formula	`formula=SrTiO3`
`target_sites`	Host elements/sites allowed for substitution	`target_sites=Ti`
`allowed_dopants`	Candidate dopants to consider	`allowed_dopants=La,Nb,Fe`
`oxidation_states`	Manual oxidation states	`oxidation_states=Sr:2,Ti:4,O:-2`
`num_dopants`	Number of candidates requested per method	`num_dopants=10`
`num_generate`	Number of structures to generate per doping type	`num_generate=5`
`min_supercell_length`	Minimum supercell length for generated CIFs	`min_supercell_length=10`

Host CIF File

Upload a CIF file when you want structure-based recommendations or doped CIF generation.

Formula-only mode can rank dopants, but generated doped structures require either:

an uploaded CIF file, or
a Materials Project structure fetched from the formula when an MP API key is configured.

Main Options

Doping Type

Choose whether to search:

both n-type and p-type dopants
n-type dopants only
p-type dopants only

Candidates Per Method

Controls how many candidates are requested from each internal ranking method before merging and sorting the result list.

Generate Doped CIFs

When enabled, the app generates substitutional doped structures for top candidates.

This works best when the input is a clean host CIF with well-defined crystallographic sites.

Structures Per Type

Controls how many top n-type and/or p-type candidates are converted into doped CIF files.

Minimum Supercell Length

Controls the approximate minimum supercell size used for generated doped structures. Larger values reduce dopant concentration but create larger CIF files and more expensive downstream calculations.

Oxidation States

The app can use:

manual oxidation states supplied in the text box
pymatgen oxidation-state guesses
BERTOS-assisted oxidation-state prediction when enabled and available

Manual oxidation states are recommended when the system has unusual valence chemistry.

Stability Screen

The optional MACE stability screen estimates the relative stability of generated doped CIFs.

Important: this is a mixed-scale diagnostic that combines raw MACE MLIP energies with Materials Project-style hull analysis. It is useful for ranking and triage, but it should not be treated as an official DFT-corrected Materials Project energy above hull.

Algorithm Summary

The current app wraps a pymatgen-based doping recommender.

The workflow is:

1. Parse the host formula or uploaded CIF. 2. Assign oxidation states using manual values, BERTOS, or pymatgen fallback. 3. Identify possible substitution sites and dopant oxidation states. 4. Generate n-type and p-type candidate substitutions based on charge difference. 5. Score candidates using chemical substitution criteria. 6. Merge and rank candidates. 7. Optionally generate doped CIF structures for top candidates. 8. Optionally screen generated structures with MACE.

The main ranking signals are:

oxidation-state compatibility
Shannon ionic radii matching where available
ICSD-derived substitution probability where available
combined heuristic score

Lower score means a better ranked candidate in the current recommender.

Output Files

The app returns several result files:

File	Description
`doping-recommendations.csv`	Table of ranked dopant candidates
`doping-recommendations.json`	Full machine-readable result
`doping-recommendations.html`	Formatted report with n-type and p-type tables
`*.cif`	Generated doped structures, when structure generation is enabled
`doping-mace-stability.csv`	Optional approximate MACE stability screen

Result Columns

Typical columns include:

Column	Meaning
`doping_type`	`n-type` or `p-type`
`rank`	Rank within the doping class
`dopant`	Candidate dopant element
`dopant_oxidation_state`	Oxidation state of the dopant
`target_site`	Host element/site being substituted
`target_oxidation_state`	Oxidation state of the host site
`delta_oxidation`	Dopant oxidation state minus target oxidation state
`radii_diff_angstrom`	Difference in ionic radius, when available
`substitution_probability`	ICSD substitution probability, when available
`score`	Combined ranking score
`mixed_scale_e_above_hull`	Optional approximate MACE/MP mixed-scale stability diagnostic

How To Interpret Results

For n-type dopants, the dopant usually has a higher oxidation state than the substituted host site. This can introduce extra electrons.

For p-type dopants, the dopant usually has a lower oxidation state than the substituted host site. This can introduce holes or acceptor behavior.

A good candidate usually has:

chemically reasonable oxidation state
small ionic radius mismatch
nonzero or high substitution probability
low combined score
a substitution site that makes physical sense for the crystal chemistry

The top-ranked candidate is not guaranteed to be synthesizable or electronically active. It should be treated as a starting hypothesis.

Recommended Workflow

1. Start with formula-only mode to get a quick candidate list. 2. Add target_sites if you know which site should be doped. 3. Add allowed_dopants if you want to focus on experimentally realistic dopants. 4. Upload a CIF and enable generated structures. 5. Inspect generated CIFs with the structure viewer. 6. Run optional MACE screening for quick triage. 7. Validate promising candidates with DFT relaxation, defect formation energy, band structure, DOS, and charge-state analysis.

Example: SrTiO3 Donor And Acceptor Search

formula=SrTiO3
target_sites=Ti
allowed_dopants=La,Nb,Fe,Mn,Co,Al
oxidation_states=Sr:2,Ti:4,O:-2

Useful settings:

Doping type: both n-type and p-type
Candidates per method: 10
Generate doped CIFs: yes, if a CIF is uploaded
Minimum supercell length: 10 A or larger

Limitations

The app is a recommender, not a final proof of dopability.

Current limitations include:

substitutional doping only
no explicit charge compensation, defect complexes, or interstitial doping workflow
no finite-temperature solubility prediction
no explicit Fermi-level dependent defect formation energy calculation
generated doped CIFs require careful inspection before DFT
optional MACE stability values are approximate diagnostics, not official DFT hull energies

Troubleshooting

No generated CIF files

Check that:

a CIF file was uploaded, or Materials Project lookup is configured
Generate doped CIFs is set to Yes
the host structure was parsed successfully
the target site exists in the structure

Oxidation states look wrong

Use manual oxidation states in the text box:

oxidation_states=Sr:2,Ti:4,O:-2

Too many unlikely dopants

Restrict the search:

allowed_dopants=La,Nb,Fe,Mn,Co,Al
target_sites=Ti

Generated structures are too large

Reduce the minimum supercell length or the number of structures generated.

Stability screening is slow

Use CPU for small tests and CUDA only on GPU workers. Disable relaxation for quick triage.

Acknowledgements

This app uses open-source materials-science tools including pymatgen for structure handling and oxidation-state support. The recommender logic integrates Shannon ionic radii matching and ICSD-style substitution probability concepts. Optional oxidation-state prediction can use BERTOS, and optional stability screening can use MACE.

Users should cite the relevant upstream tools and datasets when using generated results in publications.

All docs SEO hub