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.csvcontains synthetic paramagnetic shifts.DATA/HFC/geometry.xyzcontains the molecular geometry used for generation.DATA/DIA/diamagnetic.csvis atom-resolved and normalized toatom_label,shift.DATA/CHI/susceptibility.csvcontains susceptibility truth.DATA/LABELS/labels.csvis included when chemical labels are configured.SIMULATIONS/FITTING/config.ymlis 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_eulersamples axial/rhombic invariants and ZYZ Euler angles.splitsamples the traceless Cartesian componentsdxx,dyy,dxy,dxz, anddyz.
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_isois 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_axis 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,p1is derived from the point-dipole Guéron Curie R2 calculation with the fixed generation policytau_R = 1 ns. - The distance-independent
p2is sampled uniformly in[0, 50] Hzand 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.
Links
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.