nmrpeak-repro

Deploy NMRPeak as a service that processes jobs from the NMR API and returns candidate molecular structures.

Source code

Inputs and results

The provider connects NMR API jobs to two NMRPeak analyses. Use these analysis_kind_ref values when selecting an analysis through the API:

• mol_from_1h_peaks (HF): a molecular formula and a proton (¹H) NMR peak list.
• mol_from_1h_13c_formula (CHF): a molecular formula, a proton (¹H) NMR peak list, and a carbon-13 (¹³C) NMR peak list.

Each proton peak needs a chemical shift or shift range, an integral, and a multiplicity; include coupling constants when reported. Each carbon peak needs a chemical shift. The provider accepts structured input directly and uses a configured language-model service to interpret freeform job text before running NMRPeak.

Results contain candidate structures represented as SMILES strings. They are model predictions; the provider does not establish the compound’s identity or report a confidence score.

Check the software

The maintained tests run in a pinned container. Use Linux, Git, Make, Bash, Python 3.11 or later, Docker with Compose, at least one local Unix-socket Docker context, and a regular Docker-enabled account. Every Docker-using Make command requires DOCKER_CONTEXT=<name> or prompts you to select a local context; there is no default. The image-preparation command requires an explicit network route; building a missing image also requires Podman. If the matching image already exists, run make test DOCKER_CONTEXT=<name>. Otherwise clone the pinned source and prepare the test image; choose an available interface or use system for the default route:

git clone --recurse-submodules https://github.com/numpde/nmrpeak-repro.git
cd nmrpeak-repro
make test-image/base/build WHEELHOUSE=/absolute/path/to/wheelhouse NETWORK_INTERFACE=system DOCKER_CONTEXT=<name>
make test DOCKER_CONTEXT=<name>

Omit NETWORK_INTERFACE to choose interactively, or set it to system for the default route. Unattended preparation requires an explicit selection. Dependency tools use the selected proxy when they honor it; base image bootstrap uses the default connection.

Cloning and test-image preparation use network access. Preparation reuses an existing matching image. Ordinary tests never build or pull images: they run without network, API credentials, model weights, or GPUs, using a read-only source snapshot that excludes credentials and local deployment state. They check provider behavior, communication with the model processes, and repository consistency using fixtures and the pinned source. Passing them does not demonstrate model accuracy or a working deployment.

CPU/GPU comparison

The benchmark guide describes the opt-in comparison. The 2026-10-15 experiment includes the machine description, methods, raw observations, and results for HF and CHF on CPU, Blackwell, and Ada. Its findings apply to synthetic workloads on a shared workstation.

make benchmark/verify RUN=benchmark/20261015T065506.188575Z-4331147244aa

This command checks the committed evidence and regenerates the report offline using Python's standard library. It does not require Docker, model weights, or GPUs, and does not repeat inference.

Deploy the provider

Deployment requires Docker with Compose, built provider and model images, installed model weights, an NMR API provider credential, and a configured OpenAI-compatible language-model endpoint for interpreting input text. The provider and both model processes use Python 3.12. The model processes run on CPU in separate containers without network access. Select a shared deployment binding for the API credential, trust, route and delivery socket; the provider uses its captured API socket and sends terminal reports to shared delivery. Configure the interpreter endpoint separately.

After cloning, run make help for checkpoint preparation, image builds, deployment setup, and start/stop commands, including their required arguments. The Makefile also lists these commands online. The test commands above do not start a deployment.

Monitor the deployment

Run make provider/logs DEPLOYMENT=<name> DOCKER_CONTEXT=<name> to read the provider’s last 200 log lines and follow new entries while it runs. Use make provider/deployment/status DEPLOYMENT=<name> DOCKER_CONTEXT=<name> to find the model runner containers, then read their retained logs with docker --host <selected-Unix-socket> logs <container>.

Application logs record UTC timestamps, startup and model readiness, job and attempt identifiers, interpreter routing and validation, generation timing, result identities, and API delivery outcomes. Diagnostic messages preserve useful producer explanations and relevant excerpts; they do not provide a complete input or result dump. Diagnostics remove configured interpreter keys and recognizable credential syntax before applying size limits. They can still contain scientific input excerpts and producer messages; redaction does not classify arbitrary confidential content.

A hello sends the provider’s description and analysis offerings to the API. Each Provider Hello accepted entry records the API origin, provider, acceptance time, and request identifier. Compare its age with hello_interval_seconds, reported in the Provider ready startup entry. If an expected acknowledgement is missing, inspect subsequent retry or shutdown messages. Provider container health records startup readiness; it does not establish continuing API or interpreter availability.

Completion retained for API delivery means a result is stored locally for delivery; API confirmed complete records the API’s completion receipt. API-access and journal-admission retries report their reason and next delay, capped at five minutes. Retained attempts waiting for API expiry or conflict resolution report about every five minutes while polling continues; empty job polls remain quiet. Follow the reported failure evidence when retries persist. Leave the provider’s Docker journal volume intact so its retained attempts remain available for recovery.

Docker retains up to three 10 MB log files per container. Older entries rotate out.

Scientific references

• Xu et al., NMRPeak: a ready-to-use intelligent system for molecular structure elucidation enabled by synergistic cross-modal learning (2026). This repository pins the authors’ official implementation.
• Wang et al., NMRexp: A database of 3.3 million experimental NMR spectra, Scientific Data 12, 1954 (2025). The NMRPeak paper describes its experimental NMRexp and simulated MST-NMR datasets, including curation and training, validation, and test splits.

This repository maintains the provider deployment. The pinned upstream implementation also includes training scripts; see the NMRPeak paper and upstream project for training and data preparation.

Licensing

This repository does not include a standalone license file for its original provider code. Third-party components retain their own licenses. The pinned NMRPeak license is CC BY-NC-SA 4.0 and restricts use to non-commercial purposes; Uni-Core, the PyTorch model framework used by NMRPeak, uses the MIT License. Their license texts are included in the pinned source directories.

The NMRPeak checkpoints are downloaded from Zenodo record 19122815, whose metadata identifies the deposit’s license as Creative Commons Attribution 4.0 International. This repository does not relicense those files.