ParaNMR-Synth 0.3.0__tar.gz

paranmr_synth-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ernest Borysenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

paranmr_synth-0.3.0/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: ParaNMR-Synth
+Version: 0.3.0
+Summary: Reproducible synthetic pNMR dataset generator for ParaNMR workflows
+Author: Ernest Borysenko
+License: MIT License
+        
+        Copyright (c) 2026 Ernest Borysenko
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Mephistos-ML/ParaNMR-Synth
+Project-URL: Repository, https://github.com/Mephistos-ML/ParaNMR-Synth
+Project-URL: Issues, https://github.com/Mephistos-ML/ParaNMR-Synth/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: paranmr
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: python-semantic-release>=9.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# ParaNMR-Synth
+
+`ParaNMR-Synth` generates deterministic, replayable synthetic pNMR datasets for supervised learning and validation of ParaNMR fitting workflows.
+
+Each synthetic case follows the layout of a ParaNMR example. The dataset root
+also contains one paired ML table:
+
+```text
+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. One row contains `m1..mN` as features and six Cartesian susceptibility components plus `p1,p2` as targets. The selected susceptibility unit is recorded in `manifest.json`.
+
+`DATA/DIA/diamagnetic.csv` is always atom-resolved and normalized to
+`atom_label,shift`, including when the source input was DFT plus a reference.
+`DATA/CHI/susceptibility.csv` contains susceptibility truth only; linewidth
+truth remains exclusively in the root `dataset.csv`.
+
+## Requirements
+
+The dataset pipeline requires ParaNMR with atom-labelled diamagnetic CSV input, fixed-assignment `linewidth: estimate: p1_p2`, and ParaNMR experiment CSV round-tripping.
+
+```bash
+python3 -m pip install paranmr
+python3 -m pip install -e .[dev]
+```
+
+## Dataset YAML
+
+```yaml
+project:
+  name: ybl8_moments_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
+moments:
+  number_of_moments: 10
+linewidth:
+  method: r6
+susceptibility:
+  model: isoaxrho_euler
+```
+
+`chi_iso` is calculated through ParaNMR's spin-only Curie-law implementation.
+Synth samples `rho_over_ax` in `[0, 1/3]`, derives physical bounds for
+`chi_ax`, and samples Euler angles in standard ZYZ domains. All χ targets are
+exported in canonical ParaNMR units of ų.
+
+For `linewidth.method: r6`, Synth derives `p1` from ParaNMR's point-dipole
+Guéron Curie R2 calculation with the fixed generation policy
+`tau_R = 1 ns`. It samples the distance-independent `p2` uniformly in
+`[0, 50] Hz`, then converts it to the ppm convention required by ParaNMR's R6
+forward model. Neither coefficient is a user-facing configuration parameter.
+
+## CLI
+
+```bash
+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
+paranmr-synth dataset validate ../..
+```
+
+`validation_report.json` records truth, fitted values and errors. It does not silently reject a sample based on rank, condition number or score.
+
+## Validation stages
+
+The replay profile uses ParaNMR fixed assignment. It validates the forward data contract and separately recovers R6 `p1,p2` from labelled linewidths. Assignment-free GMM moments validation belongs to ParaNMR's own synthetic test suite and is intentionally a later stage.
+
+## Development
+
+```bash
+python3 -m pytest -m 'not integration'
+python3 -m pytest -m integration
+```
+
+The integration suite launches the real `paranmr` executable and must run against the compatible ParaNMR version. Every generated CSV records `ParaNMR-Synth` version provenance in its comment header.

paranmr_synth-0.3.0/README.md

@@ -0,0 +1,103 @@
+# ParaNMR-Synth
+
+`ParaNMR-Synth` generates deterministic, replayable synthetic pNMR datasets for supervised learning and validation of ParaNMR fitting workflows.
+
+Each synthetic case follows the layout of a ParaNMR example. The dataset root
+also contains one paired ML table:
+
+```text
+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. One row contains `m1..mN` as features and six Cartesian susceptibility components plus `p1,p2` as targets. The selected susceptibility unit is recorded in `manifest.json`.
+
+`DATA/DIA/diamagnetic.csv` is always atom-resolved and normalized to
+`atom_label,shift`, including when the source input was DFT plus a reference.
+`DATA/CHI/susceptibility.csv` contains susceptibility truth only; linewidth
+truth remains exclusively in the root `dataset.csv`.
+
+## Requirements
+
+The dataset pipeline requires ParaNMR with atom-labelled diamagnetic CSV input, fixed-assignment `linewidth: estimate: p1_p2`, and ParaNMR experiment CSV round-tripping.
+
+```bash
+python3 -m pip install paranmr
+python3 -m pip install -e .[dev]
+```
+
+## Dataset YAML
+
+```yaml
+project:
+  name: ybl8_moments_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
+moments:
+  number_of_moments: 10
+linewidth:
+  method: r6
+susceptibility:
+  model: isoaxrho_euler
+```
+
+`chi_iso` is calculated through ParaNMR's spin-only Curie-law implementation.
+Synth samples `rho_over_ax` in `[0, 1/3]`, derives physical bounds for
+`chi_ax`, and samples Euler angles in standard ZYZ domains. All χ targets are
+exported in canonical ParaNMR units of ų.
+
+For `linewidth.method: r6`, Synth derives `p1` from ParaNMR's point-dipole
+Guéron Curie R2 calculation with the fixed generation policy
+`tau_R = 1 ns`. It samples the distance-independent `p2` uniformly in
+`[0, 50] Hz`, then converts it to the ppm convention required by ParaNMR's R6
+forward model. Neither coefficient is a user-facing configuration parameter.
+
+## CLI
+
+```bash
+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
+paranmr-synth dataset validate ../..
+```
+
+`validation_report.json` records truth, fitted values and errors. It does not silently reject a sample based on rank, condition number or score.
+
+## Validation stages
+
+The replay profile uses ParaNMR fixed assignment. It validates the forward data contract and separately recovers R6 `p1,p2` from labelled linewidths. Assignment-free GMM moments validation belongs to ParaNMR's own synthetic test suite and is intentionally a later stage.
+
+## Development
+
+```bash
+python3 -m pytest -m 'not integration'
+python3 -m pytest -m integration
+```
+
+The integration suite launches the real `paranmr` executable and must run against the compatible ParaNMR version. Every generated CSV records `ParaNMR-Synth` version provenance in its comment header.

paranmr_synth-0.3.0/pyproject.toml

@@ -0,0 +1,78 @@
+# Project build, packaging, and tooling configuration.
+
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ParaNMR-Synth"
+dynamic = ["version"]
+description = "Reproducible synthetic pNMR dataset generator for ParaNMR workflows"
+readme = "README.md"
+license = { file = "LICENSE" }
+authors = [
+    { name = "Ernest Borysenko" },
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "numpy",
+    "paranmr",
+    "pyyaml",
+]
+
+[project.optional-dependencies]
+dev = [
+    "build>=1.2.0",
+    "pytest>=8.0.0",
+    "python-semantic-release>=9.0.0",
+    "ruff>=0.5.0",
+]
+
+[project.scripts]
+paranmr-synth = "paranmr_synth.cli.main:main"
+
+[project.urls]
+Homepage = "https://github.com/Mephistos-ML/ParaNMR-Synth"
+Repository = "https://github.com/Mephistos-ML/ParaNMR-Synth"
+Issues = "https://github.com/Mephistos-ML/ParaNMR-Synth/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = {attr = "paranmr_synth.__version__.__version__"}
+
+[tool.semantic_release]
+version_variables = ["src/paranmr_synth/__version__.py:__version__"]
+branch = "main"
+commit_parser = "conventional"
+allow_zero_version = true
+build_command = "python -m pip install build && python -m build --sdist --wheel ."
+changelog_file = "CHANGELOG.md"
+commit_message = "chore(release): {version}"
+
+[tool.semantic_release.remote]
+type = "github"
+
+[tool.ruff]
+line-length = 88
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+addopts = "-ra -q"
+pythonpath = ["src"]
+markers = [
+    "integration: end-to-end example/CLI integration tests (may be slow)",
+    "smoke: fast smoke tests for CLI/entrypoints",
+    "unit: fast unit tests with no subprocess, no network, minimal IO",
+]
+
+log_cli = true
+log_cli_level = "INFO"

paranmr_synth-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

paranmr_synth-0.3.0/src/ParaNMR_Synth.egg-info/PKG-INFO

@@ -0,0 +1,149 @@
+Metadata-Version: 2.4
+Name: ParaNMR-Synth
+Version: 0.3.0
+Summary: Reproducible synthetic pNMR dataset generator for ParaNMR workflows
+Author: Ernest Borysenko
+License: MIT License
+        
+        Copyright (c) 2026 Ernest Borysenko
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Mephistos-ML/ParaNMR-Synth
+Project-URL: Repository, https://github.com/Mephistos-ML/ParaNMR-Synth
+Project-URL: Issues, https://github.com/Mephistos-ML/ParaNMR-Synth/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: paranmr
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: build>=1.2.0; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: python-semantic-release>=9.0.0; extra == "dev"
+Requires-Dist: ruff>=0.5.0; extra == "dev"
+Dynamic: license-file
+
+# ParaNMR-Synth
+
+`ParaNMR-Synth` generates deterministic, replayable synthetic pNMR datasets for supervised learning and validation of ParaNMR fitting workflows.
+
+Each synthetic case follows the layout of a ParaNMR example. The dataset root
+also contains one paired ML table:
+
+```text
+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. One row contains `m1..mN` as features and six Cartesian susceptibility components plus `p1,p2` as targets. The selected susceptibility unit is recorded in `manifest.json`.
+
+`DATA/DIA/diamagnetic.csv` is always atom-resolved and normalized to
+`atom_label,shift`, including when the source input was DFT plus a reference.
+`DATA/CHI/susceptibility.csv` contains susceptibility truth only; linewidth
+truth remains exclusively in the root `dataset.csv`.
+
+## Requirements
+
+The dataset pipeline requires ParaNMR with atom-labelled diamagnetic CSV input, fixed-assignment `linewidth: estimate: p1_p2`, and ParaNMR experiment CSV round-tripping.
+
+```bash
+python3 -m pip install paranmr
+python3 -m pip install -e .[dev]
+```
+
+## Dataset YAML
+
+```yaml
+project:
+  name: ybl8_moments_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
+moments:
+  number_of_moments: 10
+linewidth:
+  method: r6
+susceptibility:
+  model: isoaxrho_euler
+```
+
+`chi_iso` is calculated through ParaNMR's spin-only Curie-law implementation.
+Synth samples `rho_over_ax` in `[0, 1/3]`, derives physical bounds for
+`chi_ax`, and samples Euler angles in standard ZYZ domains. All χ targets are
+exported in canonical ParaNMR units of ų.
+
+For `linewidth.method: r6`, Synth derives `p1` from ParaNMR's point-dipole
+Guéron Curie R2 calculation with the fixed generation policy
+`tau_R = 1 ns`. It samples the distance-independent `p2` uniformly in
+`[0, 50] Hz`, then converts it to the ppm convention required by ParaNMR's R6
+forward model. Neither coefficient is a user-facing configuration parameter.
+
+## CLI
+
+```bash
+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
+paranmr-synth dataset validate ../..
+```
+
+`validation_report.json` records truth, fitted values and errors. It does not silently reject a sample based on rank, condition number or score.
+
+## Validation stages
+
+The replay profile uses ParaNMR fixed assignment. It validates the forward data contract and separately recovers R6 `p1,p2` from labelled linewidths. Assignment-free GMM moments validation belongs to ParaNMR's own synthetic test suite and is intentionally a later stage.
+
+## Development
+
+```bash
+python3 -m pytest -m 'not integration'
+python3 -m pytest -m integration
+```
+
+The integration suite launches the real `paranmr` executable and must run against the compatible ParaNMR version. Every generated CSV records `ParaNMR-Synth` version provenance in its comment header.

paranmr_synth-0.3.0/src/ParaNMR_Synth.egg-info/SOURCES.txt

@@ -0,0 +1,42 @@
+LICENSE
+README.md
+pyproject.toml
+src/ParaNMR_Synth.egg-info/PKG-INFO
+src/ParaNMR_Synth.egg-info/SOURCES.txt
+src/ParaNMR_Synth.egg-info/dependency_links.txt
+src/ParaNMR_Synth.egg-info/entry_points.txt
+src/ParaNMR_Synth.egg-info/requires.txt
+src/ParaNMR_Synth.egg-info/top_level.txt
+src/paranmr_synth/__init__.py
+src/paranmr_synth/__version__.py
+src/paranmr_synth/app/__init__.py
+src/paranmr_synth/app/pipelines/__init__.py
+src/paranmr_synth/app/pipelines/dataset_export.py
+src/paranmr_synth/app/pipelines/dataset_generation.py
+src/paranmr_synth/app/pipelines/dataset_validation.py
+src/paranmr_synth/cfg/__init__.py
+src/paranmr_synth/cfg/dataset.py
+src/paranmr_synth/cfg/models.py
+src/paranmr_synth/cli/__init__.py
+src/paranmr_synth/cli/main.py
+src/paranmr_synth/cli/set_logging.py
+src/paranmr_synth/core/__init__.py
+src/paranmr_synth/core/dataset/__init__.py
+src/paranmr_synth/core/dataset/records.py
+src/paranmr_synth/core/generators/__init__.py
+src/paranmr_synth/core/generators/deterministic.py
+src/paranmr_synth/core/generators/linewidth.py
+src/paranmr_synth/core/generators/specs.py
+src/paranmr_synth/core/generators/susceptibility.py
+src/paranmr_synth/io/__init__.py
+src/paranmr_synth/io/csv/__init__.py
+src/paranmr_synth/io/csv/csv_util.py
+src/paranmr_synth/io/csv/experiment.py
+src/paranmr_synth/io/csv/ml.py
+src/paranmr_synth/io/csv/susceptibility.py
+src/paranmr_synth/io/json/__init__.py
+src/paranmr_synth/io/json/manifest.py
+src/paranmr_synth/io/xyz/__init__.py
+src/paranmr_synth/io/xyz/geometry.py
+src/paranmr_synth/io/yaml/__init__.py
+src/paranmr_synth/io/yaml/fit.py

paranmr_synth-0.3.0/src/ParaNMR_Synth.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

paranmr_synth-0.3.0/src/ParaNMR_Synth.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+paranmr-synth = paranmr_synth.cli.main:main

paranmr_synth-0.3.0/src/ParaNMR_Synth.egg-info/requires.txt

@@ -0,0 +1,9 @@
+numpy
+paranmr
+pyyaml
+
+[dev]
+build>=1.2.0
+pytest>=8.0.0
+python-semantic-release>=9.0.0
+ruff>=0.5.0

paranmr_synth-0.3.0/src/ParaNMR_Synth.egg-info/top_level.txt

@@ -0,0 +1 @@
+paranmr_synth

paranmr_synth-0.3.0/src/paranmr_synth/__version__.py

@@ -0,0 +1,3 @@
+# DO NOT EDIT THIS NUMBER!
+# IT IS AUTOMATICALLY CHANGED BY python-semantic-release
+__version__ = "0.3.0"

paranmr_synth-0.3.0/src/paranmr_synth/app/pipelines/dataset_export.py

@@ -0,0 +1,80 @@
+"""Orchestrate a complete replayable synthetic dataset export."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import shutil
+
+import pandas as pd
+
+from paranmr_synth.app.pipelines.dataset_generation import (
+    GeneratedCase,
+    generate_case_artifacts,
+    prepare_dataset_molecule,
+)
+from paranmr_synth.cfg.dataset import DatasetGenerationConfig
+from paranmr_synth.io.csv.experiment import write_experiment
+from paranmr_synth.io.csv.ml import write_ml_dataset
+from paranmr_synth.io.csv.susceptibility import write_susceptibility
+from paranmr_synth.io.csv.csv_util import write_csv_safe
+from paranmr_synth.io.json.manifest import write_manifest
+from paranmr_synth.io.xyz.geometry import write_indexed_geometry
+from paranmr_synth.io.yaml.fit import write_fit_config
+
+
+def generate_dataset(
+    *, config: DatasetGenerationConfig, output_dir: str | Path
+) -> Path:
+    """Generate all cases, their ParaNMR inputs, and the paired ML dataset."""
+    molecule, checksum = prepare_dataset_molecule(config)
+    cases = tuple(
+        generate_case_artifacts(
+            config=config,
+            molecule=molecule,
+            geometry_checksum=checksum,
+            case_index=index,
+        )
+        for index in range(config.project.n_cases)
+    )
+    root = Path(output_dir)
+    root.mkdir(parents=True, exist_ok=True)
+    for case in cases:
+        _write_case(config=config, case=case, molecule=molecule, root=root)
+    write_ml_dataset(cases=cases, output_file=root / "dataset.csv")
+    write_manifest(
+        config=config,
+        output_file=root / "manifest.json",
+        geometry_checksum=checksum,
+    )
+    return root
+
+
+def _write_case(*, config: DatasetGenerationConfig, case: GeneratedCase, molecule, root: Path) -> None:
+    """Write one replayable case through format-specific IO writers."""
+    case_root = root / "cases" / case.record.sample_id
+    data_dir = case_root / "DATA"
+    fitting_dir = case_root / "SIMULATIONS" / "FITTING"
+    write_indexed_geometry(input_file=config.hyperfine.file, output_file=data_dir / "HFC" / "geometry.xyz")
+    if config.signal_labels_file:
+        labels_file = data_dir / "LABELS" / "labels.csv"
+        labels_file.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy2(config.signal_labels_file, labels_file)
+    write_fit_config(config=config, output_file=fitting_dir / "config.yml")
+    write_experiment(config=config, case=case, output_file=data_dir / "PARA" / "generated_shifts.csv")
+    _write_diamagnetic_csv(molecule=molecule, output_file=data_dir / "DIA" / "diamagnetic.csv")
+    write_susceptibility(
+        target=case.record.target,
+        latent=case.susceptibility,
+        output_file=data_dir / "CHI" / "susceptibility.csv",
+    )
+
+
+def _write_diamagnetic_csv(*, molecule, output_file: Path) -> None:
+    """Write ParaNMR-normalized atom-resolved dia shifts for replay."""
+    write_csv_safe(
+        pd.DataFrame(
+            [{"atom_label": nucleus.label, "shift": nucleus.shift.dia} for nucleus in molecule.nuclei]
+        ),
+        output_file,
+        float_format="%.15g",
+    )