reflectosim 0.1.0__tar.gz

reflectosim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isaac Yong
+
+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.

reflectosim-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: reflectosim
+Version: 0.1.0
+Summary: X-ray reflectivity forward physics and synthetic data generation
+Keywords: x-ray reflectivity,XRR,simulation,synthetic data,machine learning
+Author: Isaac Yong
+Author-email: Isaac Yong <isaacyong@naver.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=2.0
+Requires-Dist: numba>=0.61
+Requires-Dist: scipy>=1.13
+Requires-Dist: periodictable>=2.1.0
+Requires-Dist: h5py>=3.10 ; extra == 'hdf5'
+Requires-Dist: torch>=2.5 ; extra == 'torch'
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/NaNIsaac/ReflectoSim
+Project-URL: Repository, https://github.com/NaNIsaac/ReflectoSim
+Project-URL: Issues, https://github.com/NaNIsaac/ReflectoSim/issues
+Project-URL: Changelog, https://github.com/NaNIsaac/ReflectoSim/blob/main/CHANGELOG.md
+Provides-Extra: hdf5
+Provides-Extra: torch
+Description-Content-Type: text/markdown
+
+# ReflectoSim
+
+[![Tests](https://github.com/NaNIsaac/ReflectoSim/actions/workflows/ci.yml/badge.svg)](https://github.com/NaNIsaac/ReflectoSim/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+<img src="https://raw.githubusercontent.com/NaNIsaac/ReflectoSim/main/docs/media/curves.png" width="720" alt="Four curves drawn from examples/lab_films.toml: the reflectivity before noise and the Poisson counts">
+
+Realistic synthetic X-ray reflectivity (XRR) data for machine learning: priors over layer stacks and
+instruments, counting noise, and a dataset format that records how to regenerate it.
+
+It is for anyone training or testing an inverse model for XRR who needs simulated curves that look
+like measured ones: random multilayers with roughness tied to thickness and a minimum contrast
+between neighbours, a native oxide placed where you say, Gaussian resolution, footprint, Kα₂, 2θ
+offset, background and Poisson counts. The package holds all the forward physics (Parratt
+recursion with Névot-Croce roughness, the resolution integral, a differentiable torch forward) and
+the generation on top of it. [ReflectoFit](https://github.com/NaNIsaac/ReflectoFit), the fitting
+engine, depends on it, so a network trained on these curves and a fit of the same measurement use
+the same physics.
+
+Status: early development.
+
+## Visual overview
+
+![ReflectoSim prior-to-dataset pipeline](docs/media/pipeline.svg)
+
+The **example prior bounds** below are configurable input ranges, not empirical distributions. Coupled thickness/roughness and SLD-contrast constraints can alter the accepted distributions.
+
+![Parameter bounds from examples/lab_films.toml](docs/media/prior-ranges.svg)
+
+The XRR curves at the top of this README are generated by the simulator; solid curves show the pre-noise signal and dots show normalized Poisson counts. For a detailed interpretation, the layer-order diagram, units, reproducibility and caveats, see the [visual guide](docs/visual-guide.md).
+
+## Install
+
+Not on PyPI yet. From a clone, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/NaNIsaac/ReflectoSim
+cd ReflectoSim
+uv sync
+```
+
+## First run
+
+Simulate 1000 curves of one to three films on SiO₂ on Si from the example prior, then summarise the
+file:
+
+<!-- test -->
+```sh
+uv run reflectosim sim --prior examples/lab_films.toml --n 1000 --seed 20261024,1 -o train.npz
+uv run reflectosim describe train.npz
+```
+
+`train.npz` holds `q`, `counts`, `reflectivity` (before noise), `counts_scale` and one array per
+parameter (`layer0.thickness`, `oxide.sld`, `tth_offset`, ...; NaN where a curve has fewer layers).
+Its metadata holds the priors, the seed and the versions; `reflectosim.priors.from_metadata` turns it
+back into priors and the same seed gives the same file. Use a `.h5` name for HDF5 (`uv sync --extra
+hdf5`).
+
+## Priors
+
+A prior is a TOML file; `examples/lab_films.toml` shows every field. The native oxide position has no
+default: `oxide = "under"` puts it on the substrate, `"over"` on top of the films, `"none"` leaves it
+out. The two orders give curves that differ by tens of percent, so every prior states its choice.
+
+## Python
+
+```python
+import numpy as np
+from reflectosim import InstrumentPrior, StackPrior, simulate, tth_to_q
+
+stack = StackPrior(
+    n_layers=(1, 3),
+    thickness=(20, 250),
+    sld=(5, 80),
+    roughness=(2, 10),
+    min_contrast=4.0,
+    oxide="none",
+)
+instrument = InstrumentPrior(
+    sigma_q=(5e-4, 3e-3), tth_offset=(-0.01, 0.01), log_background=(-8.5, -7.0), log_counts=(6, 8)
+)
+batch = simulate(
+    stack, instrument, tth_to_q(np.linspace(0.05, 8, 500)), n=10_000, seed=(20261024, 1)
+)
+batch.counts, batch.reflectivity, batch.params["layer0.thickness"]
+```
+
+## Development
+
+```sh
+uv run pytest
+```
+
+## License
+
+MIT

reflectosim-0.1.0/README.md

@@ -0,0 +1,95 @@
+# ReflectoSim
+
+[![Tests](https://github.com/NaNIsaac/ReflectoSim/actions/workflows/ci.yml/badge.svg)](https://github.com/NaNIsaac/ReflectoSim/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+<img src="https://raw.githubusercontent.com/NaNIsaac/ReflectoSim/main/docs/media/curves.png" width="720" alt="Four curves drawn from examples/lab_films.toml: the reflectivity before noise and the Poisson counts">
+
+Realistic synthetic X-ray reflectivity (XRR) data for machine learning: priors over layer stacks and
+instruments, counting noise, and a dataset format that records how to regenerate it.
+
+It is for anyone training or testing an inverse model for XRR who needs simulated curves that look
+like measured ones: random multilayers with roughness tied to thickness and a minimum contrast
+between neighbours, a native oxide placed where you say, Gaussian resolution, footprint, Kα₂, 2θ
+offset, background and Poisson counts. The package holds all the forward physics (Parratt
+recursion with Névot-Croce roughness, the resolution integral, a differentiable torch forward) and
+the generation on top of it. [ReflectoFit](https://github.com/NaNIsaac/ReflectoFit), the fitting
+engine, depends on it, so a network trained on these curves and a fit of the same measurement use
+the same physics.
+
+Status: early development.
+
+## Visual overview
+
+![ReflectoSim prior-to-dataset pipeline](docs/media/pipeline.svg)
+
+The **example prior bounds** below are configurable input ranges, not empirical distributions. Coupled thickness/roughness and SLD-contrast constraints can alter the accepted distributions.
+
+![Parameter bounds from examples/lab_films.toml](docs/media/prior-ranges.svg)
+
+The XRR curves at the top of this README are generated by the simulator; solid curves show the pre-noise signal and dots show normalized Poisson counts. For a detailed interpretation, the layer-order diagram, units, reproducibility and caveats, see the [visual guide](docs/visual-guide.md).
+
+## Install
+
+Not on PyPI yet. From a clone, with [uv](https://docs.astral.sh/uv/):
+
+```sh
+git clone https://github.com/NaNIsaac/ReflectoSim
+cd ReflectoSim
+uv sync
+```
+
+## First run
+
+Simulate 1000 curves of one to three films on SiO₂ on Si from the example prior, then summarise the
+file:
+
+<!-- test -->
+```sh
+uv run reflectosim sim --prior examples/lab_films.toml --n 1000 --seed 20261024,1 -o train.npz
+uv run reflectosim describe train.npz
+```
+
+`train.npz` holds `q`, `counts`, `reflectivity` (before noise), `counts_scale` and one array per
+parameter (`layer0.thickness`, `oxide.sld`, `tth_offset`, ...; NaN where a curve has fewer layers).
+Its metadata holds the priors, the seed and the versions; `reflectosim.priors.from_metadata` turns it
+back into priors and the same seed gives the same file. Use a `.h5` name for HDF5 (`uv sync --extra
+hdf5`).
+
+## Priors
+
+A prior is a TOML file; `examples/lab_films.toml` shows every field. The native oxide position has no
+default: `oxide = "under"` puts it on the substrate, `"over"` on top of the films, `"none"` leaves it
+out. The two orders give curves that differ by tens of percent, so every prior states its choice.
+
+## Python
+
+```python
+import numpy as np
+from reflectosim import InstrumentPrior, StackPrior, simulate, tth_to_q
+
+stack = StackPrior(
+    n_layers=(1, 3),
+    thickness=(20, 250),
+    sld=(5, 80),
+    roughness=(2, 10),
+    min_contrast=4.0,
+    oxide="none",
+)
+instrument = InstrumentPrior(
+    sigma_q=(5e-4, 3e-3), tth_offset=(-0.01, 0.01), log_background=(-8.5, -7.0), log_counts=(6, 8)
+)
+batch = simulate(
+    stack, instrument, tth_to_q(np.linspace(0.05, 8, 500)), n=10_000, seed=(20261024, 1)
+)
+batch.counts, batch.reflectivity, batch.params["layer0.thickness"]
+```
+
+## Development
+
+```sh
+uv run pytest
+```
+
+## License
+
+MIT

reflectosim-0.1.0/pyproject.toml

@@ -0,0 +1,85 @@
+[project]
+name = "reflectosim"
+version = "0.1.0"
+description = "X-ray reflectivity forward physics and synthetic data generation"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "x-ray reflectivity",
+    "XRR",
+    "simulation",
+    "synthetic data",
+    "machine learning",
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.0",
+    "numba>=0.61",
+    "scipy>=1.13",
+    "periodictable>=2.1.0",
+]
+
+[[project.authors]]
+name = "Isaac Yong"
+email = "isaacyong@naver.com"
+
+[project.optional-dependencies]
+hdf5 = ["h5py>=3.10"]
+torch = ["torch>=2.5"]
+
+[project.scripts]
+reflectosim = "reflectosim.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/NaNIsaac/ReflectoSim"
+Repository = "https://github.com/NaNIsaac/ReflectoSim"
+Issues = "https://github.com/NaNIsaac/ReflectoSim/issues"
+Changelog = "https://github.com/NaNIsaac/ReflectoSim/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "h5py>=3.10",
+    "refnx>=0.1.60",
+    "jax>=0.4.30",
+    "torch>=2.5",
+]
+
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[[tool.uv.sources.torch]]
+index = "pytorch-cpu"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+extend-exclude = ["tests/reference/reflectolearn_abeles.py"]
+
+[tool.ruff.lint]
+extend-select = [
+    "B",
+    "I",
+    "UP",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13"]
+build-backend = "uv_build"

reflectosim-0.1.0/pyproject.toml.orig

@@ -0,0 +1,74 @@
+[project]
+name = "reflectosim"
+version = "0.1.0"
+description = "X-ray reflectivity forward physics and synthetic data generation"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Isaac Yong", email = "isaacyong@naver.com" }]
+keywords = ["x-ray reflectivity", "XRR", "simulation", "synthetic data", "machine learning"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Typing :: Typed",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=2.0",
+    "numba>=0.61",
+    "scipy>=1.13",
+    "periodictable>=2.1.0",
+]
+
+[project.optional-dependencies]
+hdf5 = ["h5py>=3.10"]
+torch = ["torch>=2.5"]
+
+[project.scripts]
+reflectosim = "reflectosim.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/NaNIsaac/ReflectoSim"
+Repository = "https://github.com/NaNIsaac/ReflectoSim"
+Issues = "https://github.com/NaNIsaac/ReflectoSim/issues"
+Changelog = "https://github.com/NaNIsaac/ReflectoSim/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "h5py>=3.10",
+    "refnx>=0.1.60",
+    "jax>=0.4.30",
+    "torch>=2.5",
+]
+
+# CPU torch wheels for this project's own lock (tests, CI); installs from PyPI are not affected.
+[[tool.uv.index]]
+name = "pytorch-cpu"
+url = "https://download.pytorch.org/whl/cpu"
+explicit = true
+
+[tool.uv.sources]
+torch = [{ index = "pytorch-cpu" }]
+
+[build-system]
+requires = ["uv_build>=0.12.7,<0.13"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+
+[tool.ruff]
+line-length = 100
+# verbatim copies of other engines, compared against in tests/test_reference_engines.py
+extend-exclude = ["tests/reference/reflectolearn_abeles.py"]
+
+[tool.ruff.lint]
+extend-select = ["B", "I", "UP"]

reflectosim-0.1.0/src/reflectosim/__init__.py

@@ -0,0 +1,32 @@
+"""X-ray reflectivity forward physics and realistic synthetic data for machine learning."""
+
+from importlib.metadata import version
+
+from reflectosim import materials
+from reflectosim.forward import Instrument, forward
+from reflectosim.priors import InstrumentPrior, OxidePrior, StackPrior, SubstratePrior
+from reflectosim.simulate import Batch, simulate
+from reflectosim.structure import Layer, Stack
+from reflectosim.units import CU_KALPHA1, CU_KALPHA2, fwhm_to_sigma, q_to_tth, tth_to_q
+
+__version__ = version("reflectosim")
+
+__all__ = [
+    "CU_KALPHA1",
+    "CU_KALPHA2",
+    "Batch",
+    "Instrument",
+    "InstrumentPrior",
+    "Layer",
+    "OxidePrior",
+    "Stack",
+    "StackPrior",
+    "SubstratePrior",
+    "__version__",
+    "forward",
+    "fwhm_to_sigma",
+    "materials",
+    "q_to_tth",
+    "simulate",
+    "tth_to_q",
+]

reflectosim-0.1.0/src/reflectosim/cli.py

@@ -0,0 +1,76 @@
+"""Command line: reflectosim sim | describe."""
+
+import argparse
+import json
+import sys
+
+import numpy as np
+
+from reflectosim import __version__, dataset, priors
+from reflectosim.grid import q_grid
+from reflectosim.simulate import simulate
+
+
+def _seed(text: str):
+    parts = [int(p) for p in text.split(",")]
+    return parts[0] if len(parts) == 1 else tuple(parts)
+
+
+def _sim(args) -> int:
+    stack, inst = priors.load(args.prior)
+    q = q_grid(args.grid, inst.wavelength)
+    batch = simulate(stack, inst, q, n=args.n, seed=_seed(args.seed))
+    out = dataset.write(args.out, batch, stack, inst)
+    print(f"wrote {out}: {args.n} curves x {q.size} points, oxide {stack.oxide}, "
+          f"resolution nodes {batch.nodes or 'per point'}")  # fmt: skip
+    return 0
+
+
+def _describe(args) -> int:
+    arrays, params, meta = dataset.read(args.dataset)
+    n, nq = arrays["counts"].shape
+    print(
+        f"{args.dataset}: {n} curves x {nq} points, q {arrays['q'][0]:.4g}-{arrays['q'][-1]:.4g} 1/A"
+    )
+    width = max(len(k) for k in params)
+    for k, v in params.items():
+        ok = np.isfinite(v)
+        if ok.any():
+            print(f"  {k:<{width}}  {v[ok].min():.4g} .. {v[ok].max():.4g}  ({ok.sum()} rows)")
+    print(
+        json.dumps(
+            {
+                k: meta[k]
+                for k in ("reflectosim", "reflectofit", "seed", "resolution_nodes")
+                if k in meta
+            }
+        )
+    )
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="reflectosim", description="synthetic X-ray reflectivity data")
+    p.add_argument("--version", action="version", version=f"reflectosim {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("sim", help="simulate a dataset from a prior TOML")
+    s.add_argument(
+        "--prior", required=True, help="prior TOML: [stack], [oxide], [substrate], [instrument]"
+    )
+    s.add_argument("--n", type=int, required=True, help="number of curves")
+    s.add_argument("--grid", default="tth:0.05:8:500", help="tth:START:STOP:N or q:START:STOP:N")
+    s.add_argument("--seed", default="0", help="an int or comma-separated ints, e.g. 20261024,1")
+    s.add_argument("-o", "--out", required=True, help="output .h5 (needs h5py) or .npz")
+    s.set_defaults(run=_sim)
+
+    d = sub.add_parser("describe", help="summarise a dataset file")
+    d.add_argument("dataset")
+    d.set_defaults(run=_describe)
+
+    args = p.parse_args(argv)
+    return args.run(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

reflectosim-0.1.0/src/reflectosim/dataset.py

@@ -0,0 +1,84 @@
+"""Dataset files: HDF5 (with the `hdf5` extra) or compressed npz, chosen by the file suffix.
+
+Arrays: `q` (Q,), `counts` and `reflectivity` (n, Q), `counts_scale` (n,), and one (n,) array per
+parameter under `params/<name>` (HDF5) or `params.<name>` (npz). The metadata is one JSON string with
+the priors, the seed, the resolution node count, the package versions and the conventions, enough
+to regenerate the file.
+"""
+
+import json
+from importlib.metadata import version
+from pathlib import Path
+
+import numpy as np
+
+from reflectosim import priors
+from reflectosim.simulate import Batch
+
+CONVENTIONS = (
+    "ambient first, roughness of the interface above, Im SLD > 0 "
+    "absorbs, SLD 1e-6 A^-2, q A^-1, angles in degrees; reflectivity is I0 * smeared R + background "
+    "before noise; counts are Poisson(counts_scale * reflectivity)"
+)
+
+
+def metadata(batch: Batch, stack: priors.StackPrior, instrument: priors.InstrumentPrior) -> dict:
+    seed = list(batch.seed) if isinstance(batch.seed, tuple | list) else batch.seed
+    return {
+        "reflectosim": version("reflectosim"),
+        "stack_prior": priors.to_dict(stack),
+        "instrument_prior": priors.to_dict(instrument),
+        "seed": seed,
+        "n": int(batch.counts.shape[0]),
+        "resolution_nodes": batch.nodes,
+        "backend": "reflectosim numba float64",
+        "conventions": CONVENTIONS,
+    }
+
+
+def write(
+    path: str | Path, batch: Batch, stack: priors.StackPrior, instrument: priors.InstrumentPrior
+) -> Path:
+    path = Path(path)
+    meta = json.dumps(metadata(batch, stack, instrument))
+    arrays = {
+        "q": batch.q,
+        "counts": batch.counts.astype(np.float32),
+        "reflectivity": batch.reflectivity.astype(np.float32),
+        "counts_scale": batch.counts_scale,
+    }
+    if path.suffix in (".h5", ".hdf5"):
+        import h5py
+
+        with h5py.File(path, "w") as f:
+            for k, v in arrays.items():
+                f.create_dataset(k, data=v, compression="gzip" if v.ndim == 2 else None)
+            g = f.create_group("params")
+            for k, v in batch.params.items():
+                g.create_dataset(k, data=v)
+            f.attrs["metadata"] = meta
+    elif path.suffix == ".npz":
+        np.savez_compressed(
+            path, **arrays, **{f"params.{k}": v for k, v in batch.params.items()}, metadata=meta
+        )
+    else:
+        raise ValueError(f"unknown dataset suffix {path.suffix!r}; use .h5 or .npz")
+    return path
+
+
+def read(path: str | Path) -> tuple[dict[str, np.ndarray], dict[str, np.ndarray], dict]:
+    """(arrays, params, metadata) of a dataset file."""
+    path = Path(path)
+    if path.suffix in (".h5", ".hdf5"):
+        import h5py
+
+        with h5py.File(path, "r") as f:
+            arrays = {k: f[k][()] for k in ("q", "counts", "reflectivity", "counts_scale")}
+            params = {k: f["params"][k][()] for k in f["params"]}
+            meta = json.loads(f.attrs["metadata"])
+        return arrays, params, meta
+    with np.load(path) as z:
+        arrays = {k: z[k] for k in ("q", "counts", "reflectivity", "counts_scale")}
+        params = {k.removeprefix("params."): z[k] for k in z.files if k.startswith("params.")}
+        meta = json.loads(str(z["metadata"]))
+    return arrays, params, meta