Skip to main content
Yanked

This release has been yanked by its maintainers, and will be ignored by installers, except when explicitly specified.
Reason given by maintainers: Temporarily withdrawn pending review

ParaNMR Synth

ParaNMR Synth is a deterministic synthetic-data generator for paramagnetic NMR (pNMR) workflows. It creates replayable datasets for supervised learning, regression testing, and validation of ParaNMR fitting pipelines.

It is designed as a companion tool: generated cases follow the ParaNMR example layout, preserve the same data contracts, and include the information required to reproduce each case.

ParaNMR Synth is part of the broader SimpNMR ecosystem.

Why use ParaNMR Synth?

  • Generate deterministic datasets from a single YAML specification.
  • Produce paired NMR observables, physical targets, and replayable fit inputs.
  • Validate susceptibility and linewidth recovery against known truth.
  • Create structured datasets for supervised-learning experiments.
  • Record configuration, units, provenance, and generation metadata.

The generator is intended for research software development where reproducible inputs and explicit validation are as important as the numerical result.

Package identity

Interface Value
PyPI package paranmr-synth
CLI command paranmr-synth
Python import paranmr_synth
Companion package paranmr

Installation

Install the published package and its ParaNMR dependency with:

python3 -m pip install paranmr-synth

For development from a local checkout:

python3 -m pip install -e ".[dev]"

Quick start

Generate a dataset from a YAML configuration, replay one generated case through ParaNMR, and validate the complete dataset:

paranmr-synth dataset generate ybl8.yml --output datasets/yb_v1

cd datasets/yb_v1/cases/<sample_id>/SIMULATIONS/FITTING
MPLBACKEND=Agg paranmr --hide fit_susc config.yml

cd ../../../..
paranmr-synth dataset validate .

The validation command writes validation_report.json with generated truth, fitted values, and errors. A sample is not silently rejected based only on rank, condition number, or score.

Dataset layout

Each generated dataset contains a manifest, one canonical machine-learning table, and one self-contained ParaNMR case per sample:

dataset.csv
manifest.json
cases/<sample_id>/
  DATA/
    PARA/generated_shifts.csv
    HFC/geometry.xyz
    DIA/diamagnetic.csv
    CHI/susceptibility.csv
    LABELS/labels.csv              # optional
  SIMULATIONS/
    FITTING/config.yml

dataset.csv is the canonical supervised-learning artifact. Each row contains sample_id, temperature in K, magnetic field in T, six Cartesian susceptibility components, and p1,p2 linewidth targets. Peak features are stored in each case's DATA/PARA/generated_shifts.csv. Dataset manifests use schema version 2; susceptibility targets are in ų. Peak-table shifts are in ppm, linewidths in Hz, and areas are relative nucleus counts.

The generated case files remain compatible with the ParaNMR workflow:

  • DATA/PARA/generated_shifts.csv contains synthetic paramagnetic shifts.
  • DATA/HFC/geometry.xyz contains the molecular geometry used for generation.
  • DATA/DIA/diamagnetic.csv is atom-resolved and normalized to atom_label,shift.
  • DATA/CHI/susceptibility.csv contains susceptibility truth.
  • DATA/LABELS/labels.csv is included when chemical labels are configured.
  • SIMULATIONS/FITTING/config.yml is a replayable fitting configuration.

Linewidth truth remains exclusively in the root dataset.csv.

Dataset configuration

The following configuration generates a deterministic YbL8 peak dataset:

project:
  name: ybl8_peaks_v1
  n_cases: 1000
  seed: 42
hyperfine:
  method: pdip
  file: geometries/YbL8.xyz
  paramagnetic_centre: [0.0, 0.0, 0.0]
  spin: 0.5
  orbit: 3
  total_momentum_J: 3.5
nuclei:
  include: H
diamagnetic:
  method: csv
  file: inputs/diamagnetic.csv
signal_labels:                 # optional
  file: inputs/labels.csv
experiment:
  temperature_k: 302.15
  magnetic_field_t: 4.7
linewidth:
  method: r6
susceptibility:
  model: isoaxrho_euler
  rho_over_ax: 0.0             # optional fixed tensor orientation
  alpha: 0.0
  beta: 0.0
  gamma: 0.0

When signal_labels.file is supplied, the generator creates one peak per chemical label using ParaNMR's average_shifts: all policy. Exported replay configurations contain the same label mapping.

Susceptibility models

susceptibility.model supports two generation bases:

  • isoaxrho_euler samples axial/rhombic invariants and ZYZ Euler angles.
  • split samples the traceless Cartesian components dxx, dyy, dxy, dxz, and dyz.

Both modes derive chi_iso from the ParaNMR spin-only Curie-law model and write the same Cartesian tensor targets. A split configuration may optionally fix all five Cartesian deviation components:

susceptibility:
  model: split
  dxx: 0.012
  dyy: -0.008
  dxy: 0.003
  dxz: -0.002
  dyz: 0.005

Either provide all five split components or omit all of them for deterministic sampling. rho_over_ax and Euler-angle fields apply only to isoaxrho_euler.

Generation model

ParaNMR Synth uses the scientific implementations and conventions provided by ParaNMR:

  • chi_iso is calculated using the spin-only Curie-law implementation.
  • For isoaxrho_euler, explicit rhombicity ratios and Euler angles are fixed; omitted values are sampled deterministically.
  • rho_over_ax is sampled in [0, 1/3] and Euler angles in standard ZYZ domains when not fixed.
  • For split, Cartesian deviations are sampled deterministically and scaled so that the generated susceptibility tensor has non-negative eigenvalues.
  • Susceptibility targets are exported in canonical ParaNMR units of ų.
  • For linewidth.method: r6, p1 is derived from the point-dipole Guéron Curie R2 calculation with the fixed generation policy tau_R = 1 ns.
  • The distance-independent p2 is sampled uniformly in [0, 50] Hz and converted to the ppm convention required by the ParaNMR R6 model.

Neither linewidth coefficient is a user-facing configuration parameter.

Validation stages

The replay profile uses ParaNMR fixed assignment to validate the forward data contract and separately recover R6 p1,p2 from labelled linewidths.

Development

Run the unit and integration suites with:

python3 -m pytest -m 'not integration'
python3 -m pytest -m integration

The integration suite launches the real paranmr executable and must run against a compatible ParaNMR version. Every generated CSV records the ParaNMR Synth version in its comment header.

License

Copyright (c) 2026 Ernest Borysenko. Licensed under GPL-3.0-or-later; see LICENSE for the full terms.

Metadata

Release files for paranmr-synth 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for paranmr-synth 0.5.1
File Size Uploaded Provenance Actions
paranmr_synth-0.5.1.tar.gz 36.2 kB With provenance Details for paranmr_synth-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for paranmr-synth 0.5.1
File Interpreter ABI Platform Actions
paranmr_synth-0.5.1-py3-none-any.whl Python 3 none any Details for paranmr_synth-0.5.1-py3-none-any.whl

Total release size: 80.5 kB

Release files / paranmr_synth-0.5.1.tar.gz

Download URL paranmr_synth-0.5.1.tar.gz
Size 36.2 kB
Tags Source
SHA-256 checksum
How to use checksums
01977dc4045810c21c19d92094116ea1bfa7db19cd167b30f34d01e908e733d9
BLAKE2b-256 checksum
How to use checksums
6f486a5776389219bd71362d08428937beb062939882a85b1b71763df6ddf5e6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Release files / paranmr_synth-0.5.1-py3-none-any.whl

Download URL paranmr_synth-0.5.1-py3-none-any.whl
Size 44.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
df124c790eede0184af9efe9dd3700083fc8a78247d023a0af5825657e28058d
BLAKE2b-256 checksum
How to use checksums
2f9851a9faf4096d3bda74a6f756a7936a3743ace5609e23caea3d64d9d47126
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

Security for paranmr-synth 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for paranmr_synth-0.5.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page