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 and model weights 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.
lcbc-epfl/metal-site-prediction
Metal3D: a general deep learning framework for accurate metal ion location prediction in proteins
evo-design/proto-tools/proto_tools/tools/structure_scoring/metal3dOpen Notebook
Open notebook
Background
Metal3D (Dürr, Levy, and Rothlisberger, 2023) 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), 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 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
Config: Metal3DPredictionConfig
Config: Metal3DPredictionConfig
enum
default:"metal3d-original"
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-cleannumber
default:"0.2"
Probability threshold used to decide whether a predicted site should be annotated as a zinc atom.
number
default:"7.0"
Agglomerative clustering distance threshold in Angstroms for merging high-probability grid points into sites.
integer
default:"8"
Maximum number of clustered sites to return per structure.
integer
default:"0"
Verbosity level (0=quiet, 1=info, 2=debug, 3=raw subprocess stderr).
True is coerced to 1 and False to 0.string
default:"cuda"
Runtime device.
integer
default:"3600"
Maximum execution time in seconds.
None waits indefinitely.integer
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
Metrics (one set per
Output: Metal3DPredictionOutput
Output: Metal3DPredictionOutput
List[Metal3DPredictionResult]
One Metal3D prediction result per input structure.
results item)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(defaultmetal3d-original) selects the network.metal3d-originalis the published Metal3D zinc model.metal3d-catandmetal3d-cleanare dEVA’s retrained variants on a modified architecture; choosemetal3d-catwhen scoring catalytic metal sites.- Pass
candidate_residueswhen the pocket is known. Candidate filtering reduces the scored residue set and returns per-residue probabilities for the configured pocket positions. - Tune
probability_thresholdfor 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
Structureobjects 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, afoundflag, clusteredsites, optionalresidue_probabilities, and anannotated_structure. JSON and PDB export are supported through the standard export interface.
Infrastructure Guides
The following guides cover how to run tools efficiently and at scale.Tool Persistence
Keep a tool’s model warm across calls instead of reloading it every invocation.
Device Management
How GPUs are allocated to tools and how to target specific devices.
Parallel Execution
Fan a batch of inputs out across multiple GPUs.