> ## Documentation Index
> Fetch the complete documentation index at: https://proto.evodesign.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Metal3D
> Metal3D is a deep-learning model that predicts where zinc ions bind in a protein structure, developed by the Laboratory of Computational Chemistry and Biochemistry at EPFL. Given a structure, it scores candidate metal-binding sites and returns the predicted zinc coordinates together with a per-site confidence. This toolkit runs Metal3D over one or more input structures, returning clustered metal-site probabilities, optional per-residue probabilities, and an annotated PDB containing the top predicted zinc site when it clears the reporting threshold.
**License:** Metal3D uses MIT for code and CC-BY-4.0 for model weights and may require explicit attribution when utilized. Please refer to the [code license](https://github.com/gelnesr/dEVA/blob/main/LICENSE) and [model weights license](https://github.com/lcbc-epfl/metal-site-prediction#license) for full terms.
This toolkit is open source. Any third-party models, product names, or trademarks referenced are the property of their respective owners, and Proto is not affiliated with them.
```bibtex theme={null}
@article{durr2023metal3d,
title = {Metal3D: a general deep learning framework for accurate metal ion location prediction in proteins},
author = {Dürr, Simon L. and Levy, Andrea and Rothlisberger, Ursula},
journal = {Nature Communications},
year = {2023},
volume = {14},
pages = {2713},
doi = {10.1038/s41467-023-37870-6}
}
@article{elnesr2026deva,
title = {Zero-shot design of a de novo metalloenzyme},
author = {El Nesr, Gina and Dürr, Simon L. and Mathews, Irimpan I. and Wen, Qi and Zhao, Kewei and Sarangi, Ritimukta and Rothlisberger, Ursula and Sunden, Fanny and Huang, Po-Ssu},
journal = {bioRxiv},
year = {2026},
pages = {2026.04.23.720277},
doi = {10.1101/2026.04.23.720277}
}
```
| Function | Description | |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `run_metal3d_prediction()` | Predict catalytic or structural metal-ion sites in protein structures using Metal3D/dEVA checkpoi... (GPU) | Docs Source |
## Background
Metal3D ([Dürr, Levy, and Rothlisberger, 2023](https://doi.org/10.1038/s41467-023-37870-6)) is a three-dimensional convolutional neural network for predicting zinc-ion locations in protein structures. Around each candidate metal-coordinating residue (such as histidine, cysteine, aspartate, and glutamate), it voxelizes the local atomic environment into a grid of physicochemical features — capturing properties such as hydrophobicity, aromaticity, metal-coordinating atoms, hydrogen-bond donors and acceptors, and charge. The network maps each voxelized environment to a per-voxel probability of zinc occupancy; these residue-centered densities are averaged onto a shared grid and clustered into discrete predicted sites, each with a confidence value. Because it reasons from local structure rather than sequence conservation, Metal3D localizes zinc ions accurately even for proteins with few homologs in the Protein Data Bank.
Metal3D yields two complementary outputs used in protein engineering: a per-residue zinc density that feeds into design workflows, and a global zinc density suitable for annotating computationally predicted structures. The published model is trained solely on zinc sites from the Protein Data Bank, though the authors note that the same framework extends to other metals by retraining on the corresponding sites.
This toolkit defaults to the published checkpoint (`metal3d-original`) and additionally bundles two retrained variants from dEVA ([El Nesr et al., 2026](https://www.biorxiv.org/content/10.1101/2026.04.23.720277)), a multi-objective protein-design framework that uses Metal3D to score catalytic-metal coordination: `metal3d-cat` and `metal3d-clean`. These variants adopt a slightly modified network architecture and a wider grid-averaging radius; all three checkpoints are downloaded from the [dEVA repository](https://github.com/gelnesr/dEVA) during standalone setup.
## Tools
### Metal3D Prediction (`metal3d-prediction`)
Predicts metal-ion sites for one or more input protein structures. Each input can optionally include a `candidate_residues` selection keyed by chain identifier; when omitted, the standalone worker evaluates canonical metal-binding residue types across the protein.
#### API Reference
Source
Structures to evaluate.
Optional per-chain residue positions to evaluate. When omitted, Metal3D evaluates all canonical metal-binding residue types in the protein.
Protein structure to evaluate.
Source
Checkpoint variant to use. `metal3d-original` (default) is the original Metal3D zinc checkpoint from the Nature Communications paper; `metal3d-cat` and `metal3d-clean` are dEVA's retrained catalytic-metal and cleaned variants.
Available options: `metal3d-original`, `metal3d-cat`, `metal3d-clean`
Probability threshold used to decide whether a predicted site should be annotated as a zinc atom.
Agglomerative clustering distance threshold in Angstroms for merging high-probability grid points into sites.
Maximum number of clustered sites to return per structure.
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr). `True` is coerced to `1` and `False` to `0`.
Runtime device.
Maximum execution time in seconds. `None` waits indefinitely.
Random seed. When set, tools run reproducibly up to small GPU float noise (see `BaseToolOutput.approx_equal`), and the seed participates in cache keys. When None, cacheable seed-sensitive tools skip cache until seeded.
Source
One Metal3D prediction result per input structure.
Whether Metal3D found a site above the threshold.
Clustered metal-site calls.
Per-candidate-residue Metal3D probabilities.
Input structure with the top predicted zinc site appended when it passes the threshold.
Name of the metric that best summarizes the result overall (e.g. `"avg_plddt"` for AlphaFold2). Used by downstream UI and reporting to pick a headline value.
Concrete Metrics subclass tag; enables typed reconstruction after a serialization round-trip.
**Metrics** (one set per `results` item)
| Metric | Type | Range | Availability |
| -------- | ----- | ---------- | ------------ |
| `pmetal` | float | 0.0 to 1.0 | always |
#### Applications
This tool is appropriate for scoring enzyme-design proposals by predicted metal-site strength, checking whether a redesigned structure still supports a target metal pocket, and annotating likely zinc-site coordinates before downstream structural inspection.
#### Usage Tips
* **`model_checkpoint` (default `metal3d-original`) selects the network.** `metal3d-original` is the published Metal3D zinc model. `metal3d-cat` and `metal3d-clean` are dEVA's retrained variants on a modified architecture; choose `metal3d-cat` when scoring catalytic metal sites.
* **Pass `candidate_residues` when the pocket is known.** Candidate filtering reduces the scored residue set and returns per-residue probabilities for the configured pocket positions.
* **Tune `probability_threshold` for reporting, not model inference.** The model always produces grid probabilities; the threshold controls which clustered sites are returned and whether the top zinc site is appended to the annotated PDB.
* **Use persistent tool instances for repeated calls.** The worker keeps the selected checkpoint loaded when reused through `ToolInstance.persist_tool("metal3d")`.
## Toolkit Notes
These apply to every Metal3D tool in this toolkit (`metal3d-prediction`).
* **Structure inputs accept typed `Structure` objects or path / coordinate strings.** The wrapper writes PDB text to the standalone worker and remaps temporary PDB-safe chain identifiers back to the original chain identifiers in the returned residue probabilities.
* **Outputs are returned as typed metric objects.** Each result carries `pmetal`, a `found` flag, clustered `sites`, optional `residue_probabilities`, and an `annotated_structure`. JSON and PDB export are supported through the standard export interface.
**Example notebook:** See the [full working example](https://github.com/evo-design/proto-tools/blob/47e34afa5ea240a3b406e323dc38aa5dc85f223e/proto_tools/tools/structure_scoring/metal3d/examples/example.ipynb) for a copy-paste-ready walkthrough.
## Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.
Keep a tool's model warm across calls instead of reloading it every invocation.How GPUs are allocated to tools and how to target specific devices.Fan a batch of inputs out across multiple GPUs.
evo-design/proto-tools/proto\_tools/tools/structure\_scoring/metal3d
