ffsi 0.1.0__py3-none-any.whl

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/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/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/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

ffsi/optimize_galahad.py

@@ -0,0 +1,252 @@
+"""
+Free-form SAS Optimization Interface to GALAHAD
+
+Mandatory Parameters:
+G - Green's function
+I_data - intensity data
+I_data_std - error on intensity data
+
+Optional Parameters:
+sigma - regularization parameter value
+
+Returns:
+xi_opt - optimal xi
+b_opt - optimal b
+w_opt_list - list of optimal parameters
+
+Example usage:
+
+xi_opt, b_opt, w_opt_list = optimize(G, I_data, I_data_std)
+
+Copyright (C) 2026 The Science and Technology Facilities Council (STFC)
+Author: Jaroslav Fowkes (STFC)
+"""
+import numpy as np
+from galahad import snls
+
+from ffsi.array_module import get_array_module
+
+from ffsi.utils import contract_tensor
+
+
+def optimize(G, I_data, I_data_std, sigma=None):
+
+    # use CPU or GPU as appropriate
+    xp = get_array_module(G, I_data, I_data_std)
+    print("INFO: using " + xp.__name__ + " for residual and Jacobian computation")
+
+    # determine if data is 1D or 2D
+    if len(I_data.shape) == 1:
+        q_axes = (0,)
+        p_axes = tuple(range(1,G.ndim))
+        q_dims = G.shape[:1]
+        p_dims = G.shape[1:]
+    else:
+        q_axes = (0,1)
+        p_axes = tuple(range(2,G.ndim))
+        q_dims = G.shape[:2]
+        p_dims = G.shape[2:]
+
+    # w0 are uniform distributions
+    w0_list = [xp.ones(n) / n for n in p_dims]
+
+    # this averages out G over the parameters
+    G_ave = xp.sum(G, axis=p_axes) / np.prod(p_dims)
+
+    # and xi0 and b0 can be determined from
+    # min [1/sigma * (xi G_ave + b 1 - mu) ]^ 2
+    mu_over_nv = I_data / I_data_std
+    one_over_nv = 1 / I_data_std
+    G_ave_over_nv = G_ave / I_data_std
+    a11 = xp.sum(G_ave_over_nv ** 2)
+    a12 = xp.sum(G_ave_over_nv * one_over_nv)
+    a22 = xp.sum(one_over_nv ** 2)
+    b1 = xp.sum(mu_over_nv * G_ave_over_nv)
+    b2 = xp.sum(mu_over_nv * one_over_nv)
+
+    # solve xi0 and b0 using Cramer's rule
+    A = a11 * a22 - a12 * a12
+    xi0 = (b1 * a22 - b2 * a12) / A
+    b0 = (b2 * a11 - b1 * a12) / A
+    print('xi0: %.2e' % xi0)
+    print('b0: %.2e' % b0)
+
+    # determine xi0 and b0 scaling
+    xi_sc = 10 ** xp.floor(xp.log10(xp.abs(xi0)))
+    b_sc = 10 ** xp.floor(xp.log10(xp.abs(b0)))
+
+    # form residuals
+    def eval_r(x):
+
+        # move x to GPU if required
+        x = xp.asarray(x)
+
+        # extract variables and unscale
+        xi = x[0] * xi_sc
+        b = x[1] * b_sc
+        split_inds = np.cumsum(p_dims)[:-1]
+        w_list = xp.split(x[2:], split_inds)
+
+        # form Gw (the form factor)
+        Gw = contract_tensor(G, w_list, skip_axes=q_axes)
+
+        # intensity from forward model
+        I_model = xi * Gw + b
+
+        # intensity misfit
+        eps = (I_model - I_data) / I_data_std
+
+        # handle regularization
+        if sigma is None: # no regularization
+            res = eps.reshape(-1)
+        else: # regularisation terms sigma(w[i+1]-w[i])
+            reg = [sigma * xp.diff(w) for w in w_list]
+            res = xp.concatenate((eps.reshape(-1), *reg))
+
+        # move residual to CPU if required
+        if xp.__name__ == 'cupy':
+            return res.get()
+        else:
+            return res
+
+    # form Jacobian
+    def eval_Jr(x):
+
+        # move x to GPU if required
+        x = xp.asarray(x)
+
+        # extract variables and unscale
+        xi = x[0] * xi_sc
+        split_inds = np.cumsum(p_dims)[:-1]
+        w_list = xp.split(x[2:], split_inds)
+
+        # form Gw (the form factor)
+        Gw = contract_tensor(G, w_list, skip_axes=q_axes)
+
+        # preallocate storage for intensity misfit derivative
+        deps = xp.empty((*q_dims, 2+np.sum(p_dims)))
+
+        # xi derivative
+        deps[...,0] = (xi_sc *  Gw ) / I_data_std # scaled
+
+        # b derivative
+        deps[...,1] = b_sc / I_data_std # scaled
+
+        # w derivatives
+        inds = np.cumsum((2,*p_dims))
+        for i in range(len(p_dims)):
+            slice_i = slice(inds[i],inds[i+1])
+            w_contract_list = [w for k,w in enumerate(w_list) if k != i]
+            Gw_dw = contract_tensor(G, w_contract_list, skip_axes=[*q_axes,p_axes[0]+i])
+            deps[...,slice_i] = ( xi * Gw_dw ) / I_data_std[...,None]
+
+        # flatten intensity misfit derivative
+        deps = deps.reshape(-1)
+
+        # handle regularization
+        if sigma is None: # no regularization
+            jac = deps
+        else: # regularization term derivatives (sparse)
+            dreg1 = [sigma * xp.ones(n-1) for n in p_dims]  # w[i+1] terms
+            dreg2 = [-sigma * xp.ones(n - 1) for n in p_dims]  # -w[i] terms
+            jac = xp.concatenate((deps, *dreg1, *dreg2))
+
+        # move Jacobian to CPU if required
+        if xp.__name__ == 'cupy':
+            return jac.get()
+        else:
+            return jac
+
+    # set GALAHAD SNLS options
+    options = snls.initialize()
+    options['maxit'] = 1000
+    options['print_level'] = 2
+    options['jacobian_available'] = 2
+    #options['slls_options']['print_level'] = 1
+    options['slls_options']['maxit'] = 250
+    options['slls_options']['sbls_options']['factorization'] = 1 # use Schur-complement
+    options['slls_options']['sbls_options']['symmetric_linear_solver'] = 'sytr '
+    options['slls_options']['sbls_options']['definite_linear_solver'] = 'potr '
+    options['sllsb_options']['symmetric_linear_solver'] = 'sytr '
+    options['sllsb_options']['fdc_options']['symmetric_linear_solver'] = 'sytr '
+    options['sllsb_options']['cro_options']['symmetric_linear_solver'] = 'sytr '
+    # stopping criteria
+    options['stop_pg_relative'] = 1e-15
+    options['stop_pg_absolute'] = 1e-7
+
+    # form and scale initial optimization variable
+    x0_scaled = xp.hstack((xi0/xi_sc,b0/b_sc,*w0_list))
+
+    # move initial guess to CPU if required
+    if xp.__name__ == 'cupy':
+        x0_scaled = x0_scaled.get()
+
+    # set GALAHAD SNLS dimensions
+    n = 2 + np.sum(p_dims)
+    if sigma is None: # no regularization
+        m_r = np.prod(q_dims)
+    else: # regularization requested
+        m_r = np.prod(q_dims) + np.sum(np.array(p_dims)-1)
+    m_c = len(p_dims)
+
+    # set GALAHAD SNLS cohorts
+    ch_list = [i * np.ones(n, dtype=int) for i,n in enumerate(p_dims)]
+    cohort = np.concat(( np.array([-1,-1]), *ch_list))
+
+    # set GALAHAD SNLS Jacobian info
+    if sigma is None: # no regularization
+        Jr_type = 'dense'
+        Jr_ne = m_r * n
+        Jr_row = None
+        Jr_col = None
+    else: # regularization requested
+        Jr_type = 'coordinate'
+        nq = np.prod(q_dims)
+        Jr_ne = nq*n + 2*np.sum(np.array(p_dims)-1)
+        # flattened intensity misfit derivative
+        Jr_eps_row = np.tile(np.arange(nq),(n,1)).flatten('F')
+        Jr_eps_col = np.tile(np.arange(n),nq)
+        # sparse regularization derivatives for w
+        split_inds = np.cumsum(np.array(p_dims)-1)[:-1]
+        Jr_reg1_row = np.split(np.arange(nq,nq+np.sum(np.array(p_dims)-1)), split_inds)
+        Jr_reg2_row = Jr_reg1_row.copy()
+        Jr_reg1_col = [] # w[i+1] terms
+        Jr_reg2_col = [] # -w[i] terms
+        starts = np.cumsum(p_dims) + 2 - p_dims
+        for st, dim in zip(starts, p_dims):
+            Jr_reg1_col.append(np.arange(st+1, st+dim))
+            Jr_reg2_col.append(np.arange(st, st+dim-1))
+        # combined derivative
+        Jr_row = np.concat((Jr_eps_row,*Jr_reg1_row,*Jr_reg2_row))
+        Jr_col = np.concat((Jr_eps_col,*Jr_reg1_col,*Jr_reg2_col))
+    Jr_ptr_ne = 0
+    Jr_ptr = None
+
+    # initialise GALAHAD SNLS
+    snls.load(n, m_r, m_c, Jr_type, Jr_ne, Jr_row, Jr_col, Jr_ptr_ne, Jr_ptr, cohort, options)
+
+    # call GALAHAD SNLS with variable scaling
+    print('\nCalling GALAHAD SNLS...')
+    x, y, z, r, g, x_stat = snls.solve(n, m_r, m_c, x0_scaled, eval_r, Jr_ne, eval_Jr)
+
+    # get information
+    info = snls.information()
+    #print("inform:", inform)
+    print(" f: %.4f" % info['obj'])
+    print('** snls exit status:', info['status'])
+
+    # extract results and unscale
+    xi_opt = x[0] * xi_sc
+    b_opt = x[1] * b_sc
+    split_inds = np.cumsum(p_dims)[:-1]
+    w_opt_list = np.split(x[2:], split_inds)
+
+    print()
+    print('xi*: %.2e' % xi_opt)
+    print('b*: %.2e' % b_opt)
+    print('r*: %.15e' % np.linalg.norm(eval_r(x)))
+
+    # finalise GALAHAD SNLS
+    snls.terminate()
+
+    return xi_opt, b_opt, w_opt_list