Nucleus

Nucleus is the shared monorepo for Zatom-2, an atomistic foundation model for molecules, materials, and protein generation, and Zevals, its evaluation pipelines. It includes training code, paper configurations, data preparation tools, the inference CLI, and Zatom-2's project page.

Project page · arXiv · Weights · PyPI

Install

From PyPI

zatom-nucleus and zatom2 can be installed using uv (recommended) or pip:

uv venv
source .venv/bin/activate
uv pip install zatom-nucleus zatom2

(or uv pip install "zatom-nucleus[all]" to include zevals)

From source

Use Python 3.12 and uv. The paper environment uses Linux, NVIDIA A100 80 GB GPUs, PyTorch 2.13, and CUDA 13.2. A compatible NVIDIA driver is required for GPU execution. The lockfile pins public AtomWorks and Foundry revisions.

git clone https://github.com/Zatom-AI/nucleus.git
cd nucleus
uv sync --locked --extra all
source .venv/bin/activate

One root installation provides nucleus, zatom2, and zevals; separate model-package installs are unnecessary. For training, copy .env.example to .env and follow the data preparation guide. Inference on the included molecule example does not require training datasets.

Download weights and generate a molecule

nucleus list-available
nucleus install zatom2
zatom2 design inputs=models/zatom2/docs/examples/demo.json out_dir=logs/demo

zatom2 selects the checksummed large joint-property model (configuration VI). The downloader verifies SHA-256 and stores weights in ~/.nucleus/checkpoints. Use a paper identifier from nucleus list-available to select another model:

nucleus install zatom2-table3-scope-from-joint-properties-force-conditioned
zatom2 design \
  ckpt_path=zatom2-table3-scope-from-joint-properties-force-conditioned \
  inputs=models/zatom2/docs/examples/protein.json out_dir=logs/protein

See inference for force conditioning, custom checkpoint directories, output formats, and evaluation. Weight availability is tracked in the release status.

Reproduce the paper

• Paper-to-command guide: pretraining, ablations, scaling, generation, structure/property prediction, and protein transfer.
• Data preparation: sources, licenses, frozen splits, LMDB loading, molecular bonds, and evaluation references.
• Zevals: metrics and separate external-oracle setup.
• Preprint source and project page source.

Repository layout

Code is distributed under the Nucleus license. Dataset, model, oracle, and webpage licenses are described in third-party notices. Citation metadata is in CITATION.cff.