ffsi 0.1.0__tar.gz

ffsi-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, The Science and Technology Facilities Council (STFC)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

ffsi-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: ffsi
+Version: 0.1.0
+Summary: A package for the free-form inversion of Small Angle Scattering problems arising from X-ray and Neutron sources
+Author-email: Jaroslav Fowkes <jaroslav.fowkes@maths.ox.ac.uk>
+Maintainer-email: Jaroslav Fowkes <jaroslav.fowkes@maths.ox.ac.uk>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://github.com/ralna/free-form-sas-inversion/
+Project-URL: Download, https://github.com/ralna/free-form-sas-inversion/releases/
+Project-URL: Bug Tracker, https://github.com/ralna/free-form-sas-inversion/issues/
+Project-URL: Documentation, https://ralna.github.io/free-form-sas-inversion/
+Project-URL: Source Code, https://github.com/ralna/free-form-sas-inversion/
+Keywords: physics,optimization
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: GPU
+Classifier: Environment :: GPU :: NVIDIA CUDA
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: Unix
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: setuptools
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: galahad-optrove
+Dynamic: license-file
+
+# Free-Form SAS Inversion for SAXS/SANS
+A package for the *free-form* inversion of Small Angle Scattering (SAS) problems arising from X-ray and Neutron sources.
+
+This is a much improved algorithm and implementation over that proposed in the paper:
+https://journals.iucr.org/j/issues/2022/04/00/jl5041/index.html
+
+## SAS Inversion
+Small Angle Scattering is used to probe and analyse the nanoscale structure of materials.
+An excellent introduction to (fixed-form) SAS inversion can be found in:
+https://journals.iucr.org/j/issues/2021/06/00/gj5274/gj5274.pdf
+
+## Free-Form SAS Inversion
+Free-form SAS inversion seeks to determine the distributions of structural properties of nanoparticles (e.g. radius, length),
+but cruically (unlike conventional SAS inversion) does not make any assumptions about the forms these distributions take (hence *free-form*).
+
+A Small Angle Scattering experiment records the intensity, i.e. squared amplitude, $I(q)$ of the scattered wave as a function of the scattering vector $q$.
+The scattering vector $q$ is itself a function of the small angle $\theta$ and is given by
+```math
+q = \frac{4 \pi}{\lambda} \sin\left(\frac{\theta}{2}\right)
+```
+where $\lambda$ is the wavelength of the radiation source. For small angles, $\sin(\theta) \approx \theta$ and the scattering vector reduces to 
+```math
+q \approx \frac{2 \pi}{\lambda}\theta
+```
+i.e. essentially the small angle normalised by the wavelength of the radiation. 
+
+### Form Factors (aka Green's Functions)
+The form factor $F(q)$ describes the intensity $I(q)$ of scattering from a *single* nanoparticle over a full range of q and constitutes its SAS fingerprint.
+For example, the form factor $F(q)$ for a sphere of radius $r$ is given via $j_1(z)$ the spherical Bessel function of the first kind as
+```math
+F(q) = \left[ V(r)\Delta\rho \dfrac{3j_1(qr)}{qr} \right]^2
+```
+where $V$ is the sphere volume and $\Delta\rho$ the scattering length density difference.
+
+This repository currently contains the form factors for:
+
+- [Sphere (1D)](https://www.sasview.org/docs/user/models/sphere.html) 
+- [Cylinder (1D and 2D)](https://www.sasview.org/docs/user/models/cylinder.html)
+- [Ellipsoid (1D and 2D)](https://www.sasview.org/docs/user/models/ellipsoid.html)
+
+More form-factors will be added as the project progresses (as the code in this repository is vectorized and GPU accelerated, we are unable to directly use the form factors from SASView).
+
+### Polydispersity
+In a real SAS experiment, we are likely to see a population of nanoparticles that possess size and/or orientational distributions, this is called *polydispersity*.
+The resultant intensity $I(q)$ is then averaged over the distributions. 
+For example, for spheres with different radii,
+```math
+I(q) = \int F(q,r) w(r) dr
+```
+where $w(r)$ is the distribution over the radius.

ffsi-0.1.0/README.md

@@ -0,0 +1,50 @@
+# Free-Form SAS Inversion for SAXS/SANS
+A package for the *free-form* inversion of Small Angle Scattering (SAS) problems arising from X-ray and Neutron sources.
+
+This is a much improved algorithm and implementation over that proposed in the paper:
+https://journals.iucr.org/j/issues/2022/04/00/jl5041/index.html
+
+## SAS Inversion
+Small Angle Scattering is used to probe and analyse the nanoscale structure of materials.
+An excellent introduction to (fixed-form) SAS inversion can be found in:
+https://journals.iucr.org/j/issues/2021/06/00/gj5274/gj5274.pdf
+
+## Free-Form SAS Inversion
+Free-form SAS inversion seeks to determine the distributions of structural properties of nanoparticles (e.g. radius, length),
+but cruically (unlike conventional SAS inversion) does not make any assumptions about the forms these distributions take (hence *free-form*).
+
+A Small Angle Scattering experiment records the intensity, i.e. squared amplitude, $I(q)$ of the scattered wave as a function of the scattering vector $q$.
+The scattering vector $q$ is itself a function of the small angle $\theta$ and is given by
+```math
+q = \frac{4 \pi}{\lambda} \sin\left(\frac{\theta}{2}\right)
+```
+where $\lambda$ is the wavelength of the radiation source. For small angles, $\sin(\theta) \approx \theta$ and the scattering vector reduces to 
+```math
+q \approx \frac{2 \pi}{\lambda}\theta
+```
+i.e. essentially the small angle normalised by the wavelength of the radiation. 
+
+### Form Factors (aka Green's Functions)
+The form factor $F(q)$ describes the intensity $I(q)$ of scattering from a *single* nanoparticle over a full range of q and constitutes its SAS fingerprint.
+For example, the form factor $F(q)$ for a sphere of radius $r$ is given via $j_1(z)$ the spherical Bessel function of the first kind as
+```math
+F(q) = \left[ V(r)\Delta\rho \dfrac{3j_1(qr)}{qr} \right]^2
+```
+where $V$ is the sphere volume and $\Delta\rho$ the scattering length density difference.
+
+This repository currently contains the form factors for:
+
+- [Sphere (1D)](https://www.sasview.org/docs/user/models/sphere.html) 
+- [Cylinder (1D and 2D)](https://www.sasview.org/docs/user/models/cylinder.html)
+- [Ellipsoid (1D and 2D)](https://www.sasview.org/docs/user/models/ellipsoid.html)
+
+More form-factors will be added as the project progresses (as the code in this repository is vectorized and GPU accelerated, we are unable to directly use the form factors from SASView).
+
+### Polydispersity
+In a real SAS experiment, we are likely to see a population of nanoparticles that possess size and/or orientational distributions, this is called *polydispersity*.
+The resultant intensity $I(q)$ is then averaged over the distributions. 
+For example, for spheres with different radii,
+```math
+I(q) = \int F(q,r) w(r) dr
+```
+where $w(r)$ is the distribution over the radius.

ffsi-0.1.0/ffsi/__init__.py

@@ -0,0 +1,16 @@
+"""
+Free-Form SAS Inversion
+
+Copyright (C) 2026 The Science and Technology Facilities Council (STFC)
+Author: Jaroslav Fowkes (STFC)
+"""
+CUPY_INSTALLED = False
+
+try:
+    import cupy as _cupy
+    CUPY_INSTALLED = True
+    print('INFO: CuPy is installed, GPU computation is available')
+except Exception as e:
+    print('WARNING: CuPy is not installed, cannot use GPU computation')
+    print(e)
+    print('WARNING: continuing with CPU computation only')

ffsi-0.1.0/ffsi/api.py

@@ -0,0 +1,191 @@
+"""
+Public API for free-form SAS inversion.
+"""
+import importlib.util
+from dataclasses import dataclass, field
+from importlib import import_module
+from inspect import getmembers, isabstract, isclass
+
+import numpy as np
+
+from ffsi.array_module import get_array_module, to_device, from_device
+from ffsi.models.basemodel import SASModel
+from ffsi.optimize_galahad import optimize
+from ffsi.utils import contract_tensor, xi_to_scale
+
+
+# Model names available through invert(), for error messages only
+_MODEL_NAMES = ("sphere", "cylinder", "cylinder2d", "ellipsoid", "ellipsoid2d")
+
+
+def _resolve_model(model):
+    """
+    Resolve `model` (a case-insensitive name or a `SASModel` subclass) to
+    `(class, name)`.
+
+    The model class is imported lazily from its own module `ffsi.models.<name>`
+    (module name == class name lowercased), so only the requested model is
+    loaded rather than every model up front.
+    """
+    name = (model if isinstance(model, str) else model.__name__).lower()
+
+    # return a proper error
+    if importlib.util.find_spec(f"ffsi.models.{name}") is None:
+        raise ValueError(
+            "Unknown model '{}', available models: {}".format(
+                name, ", ".join(_MODEL_NAMES)
+            )
+        )
+
+    module = import_module(f"ffsi.models.{name}")
+
+    classes = getmembers(
+        module,
+        lambda m: (
+            isclass(m)
+            and not isabstract(m)
+            and issubclass(m, SASModel)
+            and m is not SASModel
+            and m.__module__ == module.__name__
+        ),
+    )
+    if not classes:
+        raise ValueError(f"Module 'ffsi.models.{name}' defines no SASModel subclass")
+
+    return classes[0][1], name
+
+
+@dataclass
+class ParamDistribution:
+    """Fitted distribution of one model parameter."""
+
+    name: str  # model parameter name, e.g. 'r', 'l', 'rp', 're'
+    grid: np.ndarray  # bin centers
+    weights: np.ndarray  # weights
+
+    volume_weights: np.ndarray = None
+
+
+@dataclass
+class InversionResult:
+    """Output of `invert()`: I_opt = xi * Gw + background."""
+
+    model: str  # model name
+    xi: float                # raw scale factor
+    background: float
+    distributions: list = field(default_factory=list)
+    theory: np.ndarray = None  # I_opt on the input q
+    residuals: np.ndarray = None  # (theory - intensity) / intensity_std
+    chi2: float = None  # sum(residuals**2) / residuals.size
+    average_volume: float = None  # <V> under the optimal weights
+    drho: float = None  # contrast: sld - sld_solvent
+    scale: float = None  # volume fraction: xi * <V> * 1e4
+
+    def distribution(self, name):
+        """The fitted `ParamDistribution` for parameter `name`."""
+        for dist in self.distributions:
+            if dist.name == name:
+                return dist
+        raise KeyError("No distribution for parameter '{}', have: {}".format(name, ", ".join(d.name for d in self.distributions)))
+
+
+def _build_grid(spec, xp):
+    """Bin centers (on backend `xp`) from a (min, max, nbins) triple"""
+    if isinstance(spec, np.ndarray) or (np.ndim(spec) == 1 and len(spec) > 3):
+        return xp.asarray(spec, dtype=float)
+    lo, hi, nbins = spec
+    return xp.linspace(float(lo), float(hi), int(nbins))
+
+
+def invert(model, q, intensity, intensity_std, grids, *, sld, sld_solvent, sigma=None):
+    """
+    Free-form inversion of 1D SAS data.
+
+    :param model: model name ('sphere', 'cylinder', 'ellipsoid';
+    :param q: scattering vectors
+    :param intensity: measured intensity `I(q)`
+    :param intensity_std: intensity standard deviations `dI(q)`
+    :param grids: `dict` keyed by the model's parameter names; each value
+        is a `(min, max, nbins)` triple or a prebuilt 1D array of bin centers
+    :param sld: scattering length density of the particle,
+        with `sld_solvent` it gives the contrast `drho = sld - sld_solvent`
+    :param sld_solvent: scattering length density of the solvent, in 1e-6 A^-2
+    :param sigma: smoothness regularization weight (`None` disables it)
+    :return: an `InversionResult`; `scale` is the volume fraction `xi * <V> * 1e4`
+
+    Computation runs on the GPU automatically whenever CuPy is installed; inputs
+    may be plain numpy arrays (they are moved onto the GPU here), so callers need
+    no CuPy dependency of their own. Without CuPy it runs on the CPU.
+    """
+
+    # resolve a name or a SASModel subclass to (class, name)
+    model_class, model_name = _resolve_model(model)
+    param_names = list(model_class.param_names_scattering_intensity)
+
+    # contrast: drho = sld - sld_solvent
+    drho = float(sld) - float(sld_solvent)
+
+    # move host inputs onto the compute backend (GPU when CuPy is available)
+    # array-module dispatch below and everything downstream run on that backend
+    q, intensity, intensity_std = to_device(q, intensity, intensity_std)
+
+    # xp resolves to cupy when the inputs are on the GPU, else numpy
+    xp = get_array_module(q, intensity, intensity_std)
+    q = xp.ascontiguousarray(q, dtype=float)
+    intensity = xp.asarray(intensity, dtype=float)
+    intensity_std = xp.asarray(intensity_std, dtype=float)
+    # build grids on the same backend
+    param_list = [_build_grid(grids[name], xp) for name in param_names]
+
+    # scattering intensity (Green's tensor) and inversion
+    G = model_class.compute_scattering_intensity([q], param_list, drho)
+    xi, background, w_opt_list = optimize(G, intensity, intensity_std, sigma=sigma)
+    xi, background = float(xi), float(background)
+    # GALAHAD returns numpy weights; move them onto G's backend to reconstruct
+    w_list = [xp.asarray(w) for w in w_opt_list]
+
+    # fitted intensity, residuals and chi-squared
+    theory = xi * contract_tensor(G, w_list, skip_axes=[0]) + background
+    residuals = (theory - intensity) / intensity_std
+    chi2 = float(xp.sum(residuals**2) / residuals.size)
+
+    # average volume
+    volume_params = [param_list[param_names.index(name)]
+                     for name in model_class.param_names_average_volume]
+    volume_weights_list = [w_list[param_names.index(name)]
+                           for name in model_class.param_names_average_volume]
+    average_volume = float(model_class.compute_average_volume(volume_params, volume_weights_list))
+
+    # convert xi to SasView scale
+    scale = xi_to_scale(xi, average_volume)
+
+    # package results as host numpy as plotters and the GUI
+    # cannot take cupy arrays
+    distributions = []
+    for name, grid, weights in zip(param_names, param_list, w_list):
+        volume_weights = None
+        if len(param_names) == 1:
+            volume = model_class.compute_volume(param_list)
+            weighted = weights * volume
+            volume_weights = from_device(weighted / xp.sum(weighted))
+        distributions.append(
+            ParamDistribution(
+                name=name,
+                grid=from_device(grid),
+                weights=from_device(weights),
+                volume_weights=volume_weights,
+            )
+        )
+
+    return InversionResult(
+        model=model_name,
+        xi=xi,
+        background=background,
+        distributions=distributions,
+        theory=from_device(theory),
+        residuals=from_device(residuals),
+        chi2=chi2,
+        average_volume=average_volume,
+        drho=drho,
+        scale=scale,
+    )

ffsi-0.1.0/ffsi/array_module.py

@@ -0,0 +1,42 @@
+"""
+Get array module that works when CuPy is not installed
+
+Copyright (C) 2026 The Science and Technology Facilities Council (STFC)
+Author: Jaroslav Fowkes (STFC)
+"""
+import numpy as _numpy
+import scipy as _scipy
+
+from ffsi import CUPY_INSTALLED
+
+def get_array_module(*args):
+    if CUPY_INSTALLED:
+        import cupy as cp
+        return cp.get_array_module(*args)
+    else:
+        return _numpy
+
+def get_science_module(*args):
+    if CUPY_INSTALLED:
+        import cupyx.scipy as cps
+        return cps.get_array_module(*args)
+    else:
+        return _scipy
+
+def to_device(*arrays):
+    """
+    Bring arrays from the host to the device.
+    """
+    if CUPY_INSTALLED:
+        import cupy as cp
+        return (cp.asarray(a) for a in arrays)
+    return arrays
+
+def from_device(array):
+    """
+    Bring an array from the device to the host.
+    """
+    if CUPY_INSTALLED:
+        import cupy as cp
+        return cp.asnumpy(array)
+    return array

ffsi-0.1.0/ffsi/crazy_distributions.py

@@ -0,0 +1,34 @@
+"""
+Crazy distributions generator
+
+Copyright (C) 2026 The Science and Technology Facilities Council (STFC)
+Author: Jaroslav Fowkes (STFC)
+"""
+from ffsi.array_module import get_array_module
+
+def crazy_distribution(x, gaussians, noise_level, fade_start, fade_end, seed=0):
+
+    # use CPU or GPU as appropriate
+    xp = get_array_module(x)
+
+    # create
+    w_true = xp.zeros(x.shape)
+
+    # add Gaussians
+    for factor, mean, stddev in gaussians:
+        w_true += factor * xp.exp(-((x - mean) / stddev) ** 2)
+
+    # add noise
+    xp.random.seed(seed)
+    w_true += noise_level * xp.random.rand(*x.shape) * xp.random.rand(*x.shape)
+
+    # fade both ends to make it look nicer
+    if len(x) >= 3:
+        w_true[0:fade_start] = 0.
+        w_true[fade_start:fade_end] *= xp.linspace(0, 1, fade_end - fade_start)
+        w_true[-fade_start:] = 0.
+        w_true[-fade_end:-fade_start] *= xp.linspace(1, 0, fade_end - fade_start)
+
+    # normalize to 1
+    w_true /= xp.sum(w_true)
+    return w_true