NMRNet++ chemical shifts

Per-atom ¹H and ¹³C predictions from molecular elements and 3D coordinates, reported in ppm.

This is the scientific guide for the NMR API provider's peaks_from_mol analysis. Submit through the API/GUI client supplied by your operator; this page explains the inputs and results, rather than accepting a submission. Result contract · Source code.

Inputs

Select NMRNet++ for molecular-to-shift analysis (peaks_from_mol) in your API/GUI client.

Geometry and SMILES input

Choose one input method per request: paste coordinates, attach a structure file, or supply SMILES to generate coordinates.

1. Paste one geometry

Paste one atom per line as element x y z, separated by whitespace, with no column header or blank lines between atoms. State the coordinate unit: angstrom, nm or bohr. For example:

Predict 1H and 13C shifts. Coordinates are in nm.

H   0.1027   0       -0.0363
Cl  0        0        0.178
C   0        0        0
H  -0.0514   0.089   -0.0363
H  -0.0514  -0.089   -0.0363

This authored chloromethane geometry is used in the example result. Plain XYZ text is also accepted: an atom-count line, a comment line, then exactly that many atom rows. The same geometry in XYZ format, with coordinates in angstroms:

5
Chloromethane; coordinates in angstrom
H   1.027   0       -0.363
Cl  0       0        1.78
C   0       0        0
H  -0.514   0.89    -0.363
H  -0.514  -0.89    -0.363

Paste only one geometry; attach a file for several structures. Sources: coordinate-table reader; plain XYZ reader.

For both pasted and attached coordinates, atom order is preserved and no geometry optimization or addition of missing hydrogens is performed. Include the H coordinates for which you want proton shifts; see hydrogen coverage.

2. Attach structures

Attach a coordinate table, plain XYZ, V2000 MOL/SDF, PDB, MOL2 or coordinate JSON file. MOL/SDF must be marked 3D; 2D drawings are rejected. Coordinate JSON declares coordinate_unit as angstrom, nm or bohr in the file. The reader uses this field to interpret the coordinates; submission instructions cannot override it. For other files, state the unit or use the supported format convention.

Identify the file, including its exact path inside a ZIP archive. For a file containing several structures, request all records in file order or specify individual records, for example record 2 or records 2 then 1. XYZ, SDF and MOL2 record numbers start at 1; for PDB, use the file's MODEL numbers. Example instructions for an attached archive:

Use structures/conformers.sdf, all records in file order.
Coordinates are in angstrom. Predict 1H and 13C shifts for each structure.

The same authored chloromethane geometry can be supplied as JSON in nanometres:

{
  "coordinate_unit": "nm",
  "atoms": ["H", "Cl", "C", "H", "H"],
  "coordinates": [
    [0.1027, 0, -0.0363],
    [0, 0, 0.178],
    [0, 0, 0],
    [-0.0514, 0.089, -0.0363],
    [-0.0514, -0.089, -0.0363]
  ]
}

For example, the chlorine coordinate 0.178 nm becomes 1.78 angstrom before prediction. Atom order and the original file hash remain recorded, together with the declared unit and conversion factor. The same rule applies to a JSON member selected inside a ZIP. Missing or unknown file units require correction. Keep submission instructions consistent with the file's unit. Sources: prepare_json and coordinate_conversion; JSON reading and conversion.

Each selected structure receives its own predictions, without averaging. PDB files with alternate atom locations require a chosen location label. See format examples and atom mappings. Sources: format and record selection; V2000 3D requirement; PDB alternate locations; archive selection.

3. Generate coordinates from SMILES

Supply one plain SMILES string and an explicit conformer count. For example:

SMILES: CCl
Generate 3 conformers and predict 1H and 13C shifts for each.

This route adds hydrogens and generates 3D coordinates with RDKit. Each conformer is predicted separately; there is no conformer averaging or guarantee that the generated structures are distinct. See conformer generation. Source: SMILES admission and generation.

Each geometry admits at most 128 atoms, including hydrogens; the requested conformer count is 1–128. Byte and runtime limits can reduce the practical batch size. See calculation limits and result detail and digits. Sources: prediction admission; conformer-count bounds.

Request settings

Write verbosity and significant-digit preferences in your client's submission instructions, alongside your chosen molecular input. These settings apply to all three input methods. The defaults are medium verbosity and 4 significant digits. For example:

SMILES: CCl
Generate 3 conformers and predict 1H and 13C shifts for each.
Return low verbosity and 3 significant digits.

Low omits coordinates for both supplied and generated structures. Select medium or max when you need the geometry record; a completed low result cannot be upgraded.

Choose 1–17 significant digits independently of verbosity. This rounds chemical shifts only; coordinates and conformer generation are unchanged. Numeric JSON does not preserve written trailing zeros. Extra digits do not imply greater accuracy.

Other input choices are the coordinate unit, file, record selection and order, and PDB alternate-location label, and the SMILES conformer count. The selected models have no solvent or temperature parameter; conformer-generation settings such as the random seed are fixed by the provider. See experimental conditions and generation method.

Before prediction, the provider checks whether the chosen result detail fits the API's size limit. If it does not, request lower verbosity or fewer geometries. Sources: OutputSettings, defaults and ranges; request settings and tools; result projection and capacity; design and qualification. Operator limits also apply.

The calculation

NMRNet++ extends a 3D neural predictor with semi-supervised training: atom-assigned examples teach individual shifts, while unassigned literature spectra teach matching between predicted and observed shift sets. The published architecture uses an SE(3)-equivariant Transformer with an atom-level regression head. This repository loads released weights; it does not retrain them. The submission interpreter is a separate language model that selects preparation operations. Sources: paper v1, Sections 3.2–3.3, released-weight loader, and input interpreter.

The scientific input is an ordered list of element symbols and three-dimensional coordinates. The selected released H and C models predict chemical shifts in ppm for the corresponding atoms. Other admitted elements remain part of the geometric context. The calculation does not take bond orders, charge, isotope, solvent or temperature as separate prediction features. The exact request fields are coordinate_unit, atoms and coordinates. Sources: request admission and prediction, model tensor construction, and result contract, SCIENTIFIC_LIMITS and GENERATED_LIMITS.

The local selection uses one released fold-0 checkpoint and its paired scaler for each of H and C. H/C heads run sequentially when present, and the returned predictions are sorted by the zero-based atom index within that geometry. Inverse scaling returns the release's ppm convention. A failed required head does not produce a partial scientific result. Sources: exact checkpoint/scaler/archive members and SHA-256 identities, SelectedReleaseModels and release admission, predict_request and _prediction_result, and upstream inverse scaling, pinned revision, lines 75–76.

One request admits at most 128 atoms; a batch admits at most 128 geometries. Byte, result-size and runtime limits may constrain a batch before those count limits. They are software bounds, not a qualified chemical applicability domain. Sources: MAX_ATOMS, MAX_GEOMETRIES, MAX_INPUT_BYTES and MAX_RESULT_BYTES and ResultPlan.

Applicability and experimental comparison

Software admission checks element tokens and finite coordinates; it does not validate that a molecule lies within the model's training distribution. Every atom must have a dedicated token in the pinned release dictionary. Its element tokens are C, N, O, S, H, Cl, F, Br, I, Si, P, B, Na, K, Al, Ca, Sn, As, Mg, Fe, Zn, Cr, Se, Gd, Au and Li; only H/C have selected prediction heads here. Token inventory: reference packet, dictionary.symbols_before_task; selected heads: model declaration, elements. In particular, a successful parse or a 128-atom capacity test is not an accuracy qualification for ions, radicals, metals, unusual bonding or a particular stereoisomer. Sources: require_dictionary_atoms, request admission, and bounded qualification scope.

The paper describes filtered molecular datasets, including removal of radicals and isotope-labelled entries, rather than universal chemical coverage. The local coordinate-only interface does not reproduce those training-data filters as a chemical validity assessment. Sources: paper v1, Section 3.1 and Appendix A and local request fields.

The selected interface has no solvent, temperature or reference-standard parameter and performs no additional experimental-reference calibration. Ppm denotes the released target scale after inverse scaling; it does not establish that your experimental conditions match the data. The paper's solvent-conditioned experiments are a separate model configuration, not a capability implied by these selected H/C checkpoints. Sources: request fields, selected checkpoint names, scaler implementation, and paper v1, Sections 3.4 and 4.3.

Supplied coordinates are not optimized or repaired by preparation. Generated coordinates are estimates from the procedure below. The retained comparisons do not quantify the prediction error due to an inaccurate geometry or the local generator's difference from the paper's optimization procedure. Preserve that distinction when comparing a predicted shift with experiment. Sources: coordinate preparation, generator, and qualification limits.

Supplied coordinates and units

For coordinate JSON, declare the unit in the file's coordinate_unit field and keep submission instructions consistent with it. For other coordinate sources, state the unit in your submission instructions: angstrom, nm or bohr. The provider can also use a supported file format's unit convention. It does not infer units from coordinate magnitudes; if the unit cannot be determined, the input needs clarification. Preparation preserves atom order and does not optimize or repair the supplied geometry. It records the source unit and converts coordinates to angstroms using the factors below. Sources: unit-selection instructions and tools; PreparedGeometry, prepare_rows and coordinate_conversion.

Conversion uses 64-bit floating-point arithmetic (binary64). The predictor then converts the coordinates to 32-bit floating point (float32), rejecting values that cannot be represented as finite numbers. At medium (the default) or max verbosity, the result includes both the prepared angstrom coordinates and their float32 representation, before the model centers and pads them. Compare these two fields to inspect that rounding step; consult the original input separately to check its decimal text. Sources: _float32_coordinate; compose_net_input; _planned_request, result fields prepared_request and float32_coordinates.

The bohr conversion uses CODATA's recommended central value, whose standard uncertainty is 8.2 × 10⁻¹¹ angstrom per bohr. The nm conversion factor is exact. Both conversions can still incur floating-point rounding: uncertainty in a physical constant and rounding during calculation are separate effects. Preparation records the factor and its reference. The conversion fixtures and independent rounding bounds derive binary64 bounds for the fixed nm examples independently of the implementation's output.

Why angstroms?

The selected released H and C models need a coordinate-unit convention, but our review of the NMRNet++ paper v1, release metadata and upstream instructions found no explicit unit statement tied to those model files. The source-review record, “Coordinate-unit evidence gate”, identifies the material examined and the limits of that search.

We use angstroms for these models based on the following evidence:

1. The upstream geometry helper generates molecular conformations with RDKit and stores their coordinates. RDKit documents conformer bond lengths in angstroms, supporting an angstrom interpretation of these coordinates. Sources: mol2coords, lines 146–192; RDKit GetBondLength.
2. The upstream preprocessing centers each geometry by subtracting its centroid. This changes the origin without changing bond lengths, so it preserves the incoming coordinate scale. Source: NormalizeDataset, lines 20–26.
3. We checked two molecules from the released validation data, CH3Cl and CH2Cl2. Treating their stored coordinates as angstroms gives C–H and C–Cl distances within 0.01 Å and 0.04 Å, respectively, of NIST experimental bond lengths. Sources: NIST CCCBDB release 22, Internal coordinates for CH3Cl and CH2Cl2; exact record identities, reference values and tolerance rationale; bond-distance comparison.

The two-molecule comparison supports an angstrom scale and would detect a factor-of-ten error. Its tolerances are local acceptance thresholds, not experimental uncertainties: both released C–Cl distances are about 1.803 Å, compared with NIST values of 1.785 Å for CH3Cl and 1.767 Å for CH2Cl2. This check does not measure chemical-shift prediction accuracy. See the bond-comparison record, “Test meaning and tolerance”.

Together, these observations support our choice of angstroms for model input. They do not establish how every archived or historical training geometry was produced; the upstream helper has not been linked to every such record. The coordinate_unit_decision in the numerical-evidence manifest records the choice and that limitation.

Hydrogens: preserve supplied structures, expand only generated ones

For supplied coordinates, the software neither infers nor adds missing H atoms. It reports the supplied and predicted H counts, while preserving genuinely H-free inputs. Coordinates alone cannot establish whether hydrogens were omitted, partially supplied, or intentionally absent. Missing atoms can also change the predictions for atoms that are present because they change the model's context. Sources: SCIENTIFIC_LIMITS and hydrogen coverage construction and supplied-geometry preparation.

The supplied-structure rows follow the result limits and coverage fields; the SMILES row follows _embed and its recorded hydrogen expansion. To obtain complete proton coverage from an incomplete supplied structure, supply the intended H coordinates or explicitly request a separate generation step. Preserving an incomplete geometry is not evidence that its shifts are accurate.

Generated conformers

The SMILES route uses RDKit's ETKDGv3 embedding with recorded seed, iteration and timeout settings. Its parser preserves explicit H atoms; graph expansion adds the remaining hydrogens. The evidence records original atoms/bonds, added-H parent mapping, actual conformer IDs, effective embedding parameters, RDKit version and coordinate-derived stereochemistry. Charge, isotope and graph stereochemistry remain provenance rather than additional model input fields. Source: generate_conformers, _embed, _conformer.

If the SMILES contains disconnected components, RDKit embeds them separately; they may overlap and their relative placement is not physically established. NMRNet uses all components together as the geometric context for H/C predictions, so this placement can affect their shifts. Sources: RDKit 2026.09.1 embedFragmentsSeparately default, overlap caveat and parameter documentation; local embedding call and model tensor construction.

To predict H/C shifts for an isolated component, submit that component alone. For an intended combined arrangement, supply its coordinates.

The conformers are the returned embeddings in their recorded order, not an energy-ranked or population-weighted ensemble. RMS pruning is disabled (pruneRmsThresh = -1.0). Original graph-atom indices and added-H parent indices identify the expanded graph across conformers. For supplied Upload records, interpret an atom index within its geometry together with its retained source record and source-position mapping; it is not a global index across files. Sources: embedding_settings and _embed, _planned_geometry and _planned_generated.

Each conformer receives its own ordered predictions. The implementation performs neither conformer averaging nor Boltzmann weighting, and does not guarantee that generated conformers are distinct. Incomplete generation fails the requested collection rather than submitting the available subset. Generated coordinates and their stereo annotations are not independent experimental validation. Sources: ConformerShortfall, GENERATED_LIMITS and generated-result construction, and generation fixtures and qualification.

This local generator should not be described as the paper's exact coordinate production procedure: the paper reports RDKit embedding followed by MMFF optimization, while the local _embed path calls EmbedMultipleConfs and does not apply that optimization. Sources: paper v1, Appendix A, “3D conformation generation” and local generator.

Input interpretation and format coverage

The configured language-model service receives your submission text and input-selection evidence. It selects preparation tools; the released NMRNet models calculate the shifts. Source: interpreter input and conversation.

The provider separates interpretation of the user's instruction from the deterministic readers and scientific model. For pasted input, the interpreter passes coordinate text, format (table or xyz) and source unit to prepare_pasted. Recorded text positions refer to that received text, not to byte offsets in the original Job. A successful preparation selects its geometry without another confirmation exchange. SMILES generation and verified Upload selection use their separate tools. Sources: interpreter conversation and tools, preparation and retirement orchestration, pasted source binding, tool definitions and terminal selection, and fixture rationale.

Pasted input accepts one geometry; multi-record XYZ/SDF input uses Upload selection with explicit order. Selected records are evaluated separately; molecular or stereochemical equivalence between records is not checked. Reader support includes coordinate tables, XYZ, V2000 MOL/SDF, PDB and MOL2, with format-specific constraints. Supporting a reader does not establish a complete real-interpreter/API run for that format. The fixture reference identifies authored cases and expected atom/record mappings; the preparation reference identifies format authorities, native-parser restrictions and exact runtime evidence.

The GUI packages attached files and folders as ZIP archives. For attached input, each analysis selects one structure file, which may contain multiple records. If an archive contains several files, identify the intended file by its exact name, including any folders, and state which records to use. For example: Use structures/butane.sdf, all records in file order, in angstroms. For XYZ or SDF, a selection such as records 2 then 1 uses the 1-based record numbers in that order. Repeated member names must be made unique before submission. Sources: GUI file selection and archive packaging; file and record selection instructions; exact member selection and refusal reasons.

For archived input, each result geometry records two source identities. Its source.sha256 and source.byte_length describe the molecular file actually read. The nested source.archive records the outer ZIP's hash and byte length, plus member_name identifying that file inside the archive. These hashes and lengths describe different bytes and need not match. Atom positions and record numbers refer to the molecular file, not the ZIP. Direct-file inputs retain their original file identity without an archive block. Sources: prepare_upload source binding; _planned_supplied result provenance. The qualification record, R47–R48, separates those tests from earlier native prediction evidence.

A locally qualified API Job supplied a ZIP containing two carbon-only SDF records. The real interpreter selected both records in three turns without corrections; the provider returned eight carbon shifts, each exactly matching the retained native fold-0 reference. The result preserves separate ZIP and SDF hashes, record order and supplied atom identities. This is a repeatability observation, not independent experimental accuracy. Sources: R53, successful API delivery: exact Job/Attempt/result and artifact hashes; preflight_sdf_zip and compare_sdf_scientific_documents, executed caller revision. Browser submission was not part of this run.

In separate checks, the real interpreter reported missing coordinate units, conformer count and record selection, and reported the mass-spectrum-only input as unsupported. Those model reports are not independently verified validation results. Three further cases selected MOL, PDB and MOL2 reader options, including the explicitly requested record order. These seven authored cases used inert attachment metadata: they exercised input decisions without file parsing, API Jobs or scientific inference. Their observations complement the separate native-reader and API evidence. Sources: R54, per-case outcomes: exact source/image and evidence hashes; run_batch and _FormatChoiceOnly, executed probe revision.

Reading a result: chloromethane

The authored chloromethane fixture supplies these rows in nm, in this order:

H   0.1027   0       -0.0363
Cl  0        0        0.178
C   0        0        0
H  -0.0514   0.089   -0.0363
H  -0.0514  -0.089   -0.0363

This authored geometry illustrates atom correspondence and unit conversion. It is not an experimental structure. The recorded fold-0 predictions are:

Sources: exact supplied text, format and unit, authored fixture provenance, and R21, Job job:f4b3e820d658200c22cebcef9d2e2c60bee36e4c5edc7a05868d1465857b8c3c.

Cl at index 1 remains in the geometry but receives no shift. The displayed digits identify the recorded numerical outputs; they do not express experimental precision. Per-atom H entries are not grouped into equivalent resonances, and the predictor does not compute rotational/exchange averaging or a spectrum. Sources: _prediction_result, scientific result limits.

Follow the cited fixture and receipt to inspect this example. The reproduction reference explains how to repeat the bounded release calculation; the operator reference describes API execution and diagnostics.

Results use schema nmrnet.coordinate_shifts.result.v2; historical results keep their original schema and bytes.

What the retained numerical evidence establishes

The historical 64 positions are the release's selected reference positions; 137 counts every H/C output across the four complete fixture geometries. Neither count is a test-set accuracy score. The relevant manifests retain request, checkpoint/scaler, source, image and runtime identities. Sources: reference packet, complete fixture observation, and callable qualification packet.

The reference uses Python 3.12.12, CPU float32 and two computation threads. Its original label-roundtrip allowance is 0.0001 ppm; repeat tolerances are zero. The released scalers were serialized under scikit-learn 1.5.2 and loaded under 1.8.0 with a retained version warning and separately checked affine arithmetic. Those observations do not establish cross-platform/GPU equality or remove the warning. Sources: reference runtime and tolerances, dependency/scaler review, and note 001.

Published accuracy and the five-checkpoint ensemble

MAE is the mean absolute prediction error; RMSE is the square root of the mean squared error and gives more weight to large errors. Atom-level evaluation keeps the assigned atom correspondence. Sorted molecule-level evaluation compares within-molecule shift collections and cannot by itself establish that a predicted value belongs to the correct atom. Sources: pinned reg_metrics and sorted molecule evaluation.

The published NMRNet + Semi-supervised results below describe benchmark evaluation. They are not measured errors of this repository's local fold-0 reference or uncertainty bounds for an individual prediction. Source: Jin et al., arXiv:2601.18524v1, Table 2.

The released logs separately report fold-0 atom-level MAEs of 0.1842 ppm for H and 0.9876 ppm for C. These are upstream benchmark observations for that fold, not errors measured by this repository's four-fixture reproducibility checks. Source: note 001, “Published accuracy and ensemble averaging”, exact H/C result.log archive members and SHA-256 hashes.

The released evaluation script runs folds 0–4, averages their prediction vectors, then computes errors. It does not average five error scores. Molecule-level evaluation additionally sorts predictions and targets within each molecule, so it measures a different correspondence from assigned atom-level error. The averaging attribution comes from pinned code and released logs; the paper's methods do not explicitly spell it out. Sources: upstream infer.sh, lines 11–28, get_result.py, lines 80–84, get_result_unlabel.py, lines 97–103, and note 001, “Published accuracy and ensemble averaging”, exact log members and hashes.

Sources and provenance

• Yongqi Jin, Yecheng Wang, Jun-Jie Wang, Rong Zhu, Guolin Ke and Weinan E, From Human Labels to Literature: Semi-Supervised Learning of NMR Chemical Shifts at Scale, arXiv:2601.18524v1, 26 January 2026. Relevant locations: Section 3.3 (architecture), Section 4.1 (experimental setup), Table 2 (benchmark errors), Table 6 (ppm convention), Appendix A (coordinate generation).
• Zenodo record 18232165, DOI 10.5281/zenodo.18232165. This repository's release declaration and selected-model manifest identify archive URLs, members, sizes and hashes; names alone are not artifact identity.
• Scientific source: pinned NMRNet++ revision 3ba8b9c2f3d0a390d00685d238618345c6ab24d7. Source closure and source qualification identify the retained software bytes and the historical image inspection.
• Unit references: NIST SP 811, Appendix B.8, angstrom conversion entries; Peter J. Mohr, David B. Newell, Barry N. Taylor and Eite Tiesinga, CODATA recommended values of the fundamental physical constants: 2022, J. Phys. Chem. Ref. Data 54, 033105 (2025), DOI 10.1063/5.0279860, Table XXXIII, p. 033105-45, Bohr radius.
• Artifact attribution and its evidence record distinguish release association from original producer identity. The pinned software is MIT-licensed; file-specific dataset/checkpoint/scaler licences remain NOASSERTION, and their exact original producers are not inferred from the paper's authors.