5. API Reference

class Params(thicknesses: Tensor, roughnesses: Tensor, slds: Tensor)

Bases: AbstractParams

Parameter class for thickness, roughness and sld parameters

Parameters:

• thicknesses (Tensor) – batch of thicknesses (top to bottom)

• roughnesses (Tensor) – batch of roughnesses (top to bottom)

• slds (Tensor) – batch of slds (top to bottom)

reflectivity(q: Tensor, log: bool = False, **kwargs)

computes the reflectivity curves directly from the parameters

Parameters:

• q (Tensor) – the q values

• log (bool, optional) – whether to apply logarithm to the curves. Defaults to False.

Returns:

the simulated reflectivity curves

Return type:

Tensor

scale_with_q(q_ratio: float)

scales the parameters based on the q ratio

Parameters:

q_ratio (float) – the scaling ratio

property d_rhos

computes the differences in SLD values of the neighboring layers

as_tensor(use_drho: bool = False) → Tensor

converts the instance of the class to a Pytorch tensor

classmethod from_tensor(params: Tensor)

initializes an instance of the class from a Pytorch tensor containing the values of the parameters

static size2layers_num(size: int) → int

converts the number of parameters to the number of layers

static layers_num2size(layers_num: int) → int

converts the number of layers to the number of parameters

get_param_labels(**kwargs) → List[str]

gets the parameter labels, the layers are numbered from the bottom to the top (i.e. opposite to the order in the Tensors)

class PriorSampler

Bases: object

Base class for prior samplers

PARAM_CLS

alias of Params

property param_dim: int

gets the number of parameters (i.e. the parameter dimensionality)

property max_num_layers: int

gets the number of layers

sample(batch_size: int) → Params

sample a batch of parameters

scale_params(params: Params) → Tensor

scale the parameters to a ML-friendly range

restore_params(scaled_params: Tensor) → Params

restore the parameters to their original range

class BasicDataset(q_generator: QGenerator, prior_sampler: PriorSampler, intensity_noise: IntensityNoiseGenerator | None = None, q_noise: QNoiseGenerator | None = None, curves_scaler: CurvesScaler | None = None, calc_denoised_curves: bool = False, smearing: Smearing | None = None)

Bases: object

Reflectometry dataset. It generates the q positions, samples the thin film parameters from the prior, simulates the reflectivity curves and applies noise to the curves.

Parameters:

• q_generator (QGenerator) – the momentum transfer (q) generator

• prior_sampler (PriorSampler) – the prior sampler

• intensity_noise (IntensityNoiseGenerator, optional) – the intensity noise generator. Defaults to None.

• q_noise (QNoiseGenerator, optional) – the q noise generator. Defaults to None.

• curves_scaler (CurvesScaler, optional) – the reflectivity curve scaler. Defaults to an instance of LogAffineCurvesScaler, which scales the curves to the range [-1, 1], the minimum considered intensity being 1e-10.

• calc_denoised_curves (bool, optional) – whether to add the curves without noise to the dictionary. Defaults to False.

• smearing (Smearing, optional) – curve smearing generator. Defaults to None.

update_batch_data(batch_data: Dict[str, Tensor | BasicParams]) → None

implement in a subclass to edit batch_data dict inplace

get_batch(batch_size: int) → Dict[str, Tensor | BasicParams]

get a batch of data as a dictionary with keys params, scaled_params, q_values, curves, scaled_noisy_curves

Parameters:

batch_size (int) – the batch size

class QGenerator

Bases: object

Base class for momentum transfer (q) generators

class ConstantQ(q: Tensor | Tuple[float, float, int] = (0.0, 0.2, 128), device=device(type='cuda'), dtype=torch.float64, remove_zero: bool = False, fixed_zero: bool = False)

Bases: QGenerator

Q generator for reflectivity curves with fixed discretization

Parameters:

• q (Union[Tensor, Tuple[float, float, int]], optional) – tuple (q_min, q_max, num_q) defining the minimum q value, maximum q value and the number of q points. Defaults to (0., 0.2, 128).

• device (optional) – the Pytorch device. Defaults to DEFAULT_DEVICE.

• dtype (optional) – the Pytorch data type. Defaults to DEFAULT_DTYPE.

• remove_zero (bool, optional) – do not include the upper end of the interval. Defaults to False.

• fixed_zero (bool, optional) – do not include the lower end of the interval. Defaults to False.

get_batch(batch_size: int, context: dict | None = None) → Tensor

generate a batch of q values

Parameters:

batch_size (int) – the batch size

Returns:

generated batch of q values

Return type:

Tensor

class VariableQ(q_min_range: Tuple[float, float] = (0.01, 0.03), q_max_range: Tuple[float, float] = (0.1, 0.5), n_q_range: Tuple[int, int] = (64, 256), device=device(type='cuda'), dtype=torch.float64)

Bases: QGenerator

Q generator for reflectivity curves with variable discretization

Parameters:

• q_min_range (list, optional) – the range for sampling the minimum q value of the curves, q_min. Defaults to [0.01, 0.03].

• q_max_range (list, optional) – the range for sampling the maximum q value of the curves, q_max. Defaults to [0.1, 0.5].

• n_q_range (list, optional) – the range for the number of points in the curves (equidistantly sampled between q_min and q_max, the number of points varies between batches but is constant within a batch). Defaults to [64, 256].

• device (optional) – the Pytorch device. Defaults to DEFAULT_DEVICE.

• dtype (optional) – the Pytorch data type. Defaults to DEFAULT_DTYPE.

get_batch(batch_size: int, context: dict | None = None) → Tensor

generate a batch of q values (the number of points varies between batches but is constant within a batch)

Parameters:

batch_size (int) – the batch size

Returns:

generated batch of q values

Return type:

Tensor

scale_q(q)

scales the q values to the range [-1, 1]

Parameters:

q (Tensor) – unscaled q values

Returns:

scaled q values

Return type:

Tensor

class QNoiseGenerator

Bases: ProcessData

Base class for q noise generators

class IntensityNoiseGenerator

Bases: ProcessData

Base class for intensity noise generators

class MultiplicativeLogNormalNoiseGenerator(std: float | Tuple[float, float], base: float = 10, add_to_context: bool = False)

Bases: IntensityNoiseGenerator

Noise generator which applies noise as \(R_n = R * b^{\epsilon}\) , where \(b\) is a base and \(\epsilon\) is sampled from the normal distribution \(\epsilon \sim \mathcal{N}(0, std)\) . In logarithmic space, this translates to \(\log_b(R_n) = \log_b(R) + \epsilon\) .

Parameters:

• std (Union[float, Tuple[float, float]]) – the standard deviation of the normal distribution from which the noise is sampled. The standard deviation is the same for all curves in the batch if provided as a float, or uniformly sampled for each curve in the batch if provided as a tuple.

• base (float, optional) – the base of the logarithm. Defaults to 10.

apply(curves: Tensor, context: dict | None = None)

applies noise to the curves

class PoissonNoiseGenerator(relative_errors: Tuple[float, float] = (0.05, 0.35), abs_errors: float = 1e-08, add_to_context: bool = False, consistent_rel_err: bool = True, logdist: bool = False)

Bases: IntensityNoiseGenerator

Noise generator which applies Poisson noise to the reflectivity curves

Parameters:

• relative_errors (Tuple[float, float], optional) – the range of relative errors to apply to the intensity curves. Defaults to (0.05, 0.35).

• abs_errors (float, optional) – a small constant added to prevent division by zero. Defaults to 1e-8.

• consistent_rel_err (bool, optional) – If True, the same relative error is used for all points in a curve.

• logdist (bool, optional) – If True, the relative errors in are sampled in logarithmic space. Defaults to False.

apply(curves: Tensor, context: dict | None = None)

applies noise to the curves

class CurvesScaler

Bases: object

Base class for curve scalers

class LogAffineCurvesScaler(weight: float = 0.1, bias: float = 0.5, eps: float = 1e-10)

Bases: CurvesScaler

Curve scaler which scales the reflectivity curves according to the logarithmic affine transformation: \(\log_{10}(R + eps) \cdot weight + bias\).

Parameters:

• weight (float) – multiplication factor in the transformation

• bias (float) – addition term in the transformation

• eps (float) – sets the minimum intensity value of the reflectivity curves which is considered

scale(curves: Tensor)

scales the reflectivity curves to a ML-friendly range

Parameters:

curves (Tensor) – original reflectivity curves

Returns:

reflectivity curves scaled to a ML-friendly range

Return type:

Tensor

restore(curves: Tensor)

restores the physical reflectivity curves

Parameters:

curves (Tensor) – scaled reflectivity curves

Returns:

reflectivity curves restored to the physical range

Return type:

Tensor

class MeanNormalizationCurvesScaler(path: str | None = None, curves_mean: Tensor | None = None, device: device = 'cuda')

Bases: CurvesScaler

Curve scaler which scales the reflectivity curves by the precomputed mean of a batch of curves

Parameters:

• path (str, optional) – path to the precomputed mean of the curves, only used if curves_mean is None. Defaults to None.

• curves_mean (Tensor, optional) – the precomputed mean of the curves. Defaults to None.

• device (torch.device, optional) – the Pytorch device. Defaults to ‘cuda’.

scale(curves: Tensor)

scales the reflectivity curves to a ML-friendly range

Parameters:

curves (Tensor) – original reflectivity curves

Returns:

reflectivity curves scaled to a ML-friendly range

Return type:

Tensor

restore(curves: Tensor)

restores the physical reflectivity curves

Parameters:

curves (Tensor) – scaled reflectivity curves

Returns:

reflectivity curves restored to the physical range

Return type:

Tensor

static save(prior_sampler: PriorSampler, q: Tensor, path: str, num: int = 16384)

computes the mean of a batch of reflectivity curves and saves it

Parameters:

• prior_sampler (PriorSampler) – the prior sampler

• q (Tensor) – the q values

• path (str) – the path for saving the mean of the curves

• num (int, optional) – the number of curves used to compute the mean. Defaults to 16384.

get_density_profiles(thicknesses: Tensor, roughnesses: Tensor, slds: Tensor, z_axis: Tensor | None = None, num: int = 1000)

Generates SLD profiles (and their derivative) based on batches of thicknesses, roughnesses and layer SLDs.

The axis has its zero at the top (ambient medium) interface and is positive inside the film.

Parameters:

• thicknesses (Tensor) – the layer thicknesses (top to bottom)

• roughnesses (Tensor) – the interlayer roughnesses (top to bottom)

• slds (Tensor) – the layer SLDs (top to bottom)

• z_axis (Tensor, optional) – a custom depth (z) axis. Defaults to None.

• num (int, optional) – number of discretization points for the profile. Defaults to 1000.

Returns:

the z axis, the computed density profile rho(z) and the derivative of the density profile drho/dz(z)

Return type:

tuple

reflectivity(q: Tensor, thickness: Tensor, roughness: Tensor, sld: Tensor, dq: Tensor | None = None, gauss_num: int = 51, constant_dq: bool = True, log: bool = False, abeles_func=None)

Function which computes the reflectivity curves from thin film parameters. By default it uses the fast implementation of the Abeles matrix formalism.

Parameters:

• q (Tensor) – tensor of momentum transfer (q) values with shape [batch_size, n_points] or [n_points]

• thickness (Tensor) – tensor containing the layer thicknesses (ordered from top to bottom) with shape [batch_size, n_layers]

• roughness (Tensor) – tensor containing the interlayer roughnesses (ordered from top to bottom) with shape [batch_size, n_layers + 1]

• sld (Tensor) – tensors containing the layer SLDs (real or complex; ordered from top to bottom) with shape [batch_size, n_layers + 1]. It includes the substrate but excludes the ambient medium which is assumed to have an SLD of 0.

• dq (Tensor, optional) – tensor of resolutions used for curve smearing with shape [batch_size, 1]. Either dq if constant_dq is True or dq/q if constant_dq is False. Defaults to None.

• gauss_num (int, optional) – the number of gaussians for curve smearing. Defaults to 51.

• constant_dq (bool, optional) – if True the smearing is constant (constant dq at each point in the curve) otherwise the smearing is linear (constant dq/q at each point in the curve). Defaults to True.

• log (bool, optional) – if True the base 10 logarithm of the reflectivity curves is returned. Defaults to False.

• abeles_func (Callable, optional) – a function implementing the simulation of the reflectivity curves, if different than the default Abeles matrix implementation. Defaults to None.

Returns:

tensor containing the simulated reflectivity curves with shape [batch_size, n_points]

Return type:

Tensor

class Smearing(sigma_range: tuple = (0.0001, 0.005), constant_dq: bool = True, gauss_num: int = 31, share_smeared: float = 0.2)

Bases: object

Class which applies resolution smearing to the reflectivity curves. The intensity at a q point will be the average of the intensities of neighbouring q points, weighted by a gaussian profile.

Parameters:

• sigma_range (tuple, optional) – the range for sampling the resolutions. Defaults to (1e-4, 5e-3).

• constant_dq (bool, optional) – if True the smearing is constant (the resolution is given by the constant dq at each point in the curve) otherwise the smearing is linear (the resolution is given by the constant dq/q at each point in the curve). Defaults to True.

• gauss_num (int, optional) – the number of interpolating gaussian profiles. Defaults to 31.

• share_smeared (float, optional) – the share of curves in the batch for which the resolution smearing is applied. Defaults to 0.2.

class LogLikelihood(q: Tensor, exp_curve: Tensor, priors: PriorSampler, sigmas: float | Tensor)

Bases: object

Computes the gaussian log likelihood of the thin film parameters

Parameters:

• q (Tensor) – the q values

• exp_curve (Tensor) – the experimental reflectivity curve

• priors (PriorSampler) – the prior sampler

• sigmas (Union[float, Tensor]) – the sigmas (i.e. intensity error bars)

calc_log_likelihood(curves: Tensor)

computes the gaussian log likelihood

calc_log_posterior(params: Params | Tensor, curves: Tensor | None = None)

Call self as a function.

class PoissonLogLikelihood(q: Tensor, exp_curve: Tensor, priors: PriorSampler, sigmas: float | Tensor)

Bases: LogLikelihood

Computes the Poisson log likelihood of the thin film parameters

Parameters:

• q (Tensor) – the q values

• exp_curve (Tensor) – the experimental reflectivity curve

• priors (PriorSampler) – the prior sampler

• sigmas (Union[float, Tensor]) – the sigmas (i.e. intensity error bars)

calc_log_likelihood(curves: Tensor)

computes the Poisson log likelihood

class BasicExpIntensityNoise(relative_errors: Tuple[float, float] = (0.001, 0.15), abs_errors: float = 1e-08, scale_range: tuple = (-0.02, 0.02), shift_range: tuple = (-0.1, 0.002), background_range: tuple = (1e-10, 1e-08), apply_shift: bool = False, apply_scaling: bool = False, apply_background: bool = False, consistent_rel_err: bool = False, add_to_context: bool = False, logdist: bool = False)

Bases: IntensityNoiseGenerator

A composite noise generator that applies Poisson, scaling, shift and background noise to reflectivity curves.

This class combines four types of noise:

1. Poisson noise: Simulates count-based noise common in photon counting experiments.

2. Scaling noise: Applies a scaling transformation to the curves, equivalent to a vertical stretch or compression in logarithmic space.

3. Shift noise: Applies a multiplicative shift to the curves, equivalent to a vertical shift in logarithmic space.

4. Background noise: Adds a constant background value to the curves.

Parameters:

• relative_errors (Tuple[float, float], optional) – The range of relative errors for Poisson noise. Defaults to (0.001, 0.15).

• abs_errors (float, optional) – A small constant added to prevent division by zero in Poisson noise. Defaults to 1e-8.

• scale_range (tuple, optional) – The range of scaling factors for scaling noise. Defaults to (-2e-2, 2e-2).

• shift_range (tuple, optional) – The range of shift factors for shift noise. Defaults to (-0.1, 0.2e-2).

• background_range (tuple, optional) – The range from which the background value is sampled. Defaults to (1.0e-10, 1.0e-8).

• apply_shift (bool, optional) – If True, applies shift noise to the curves. Defaults to False.

• apply_scaling (bool, optional) – If True, applies scaling noise to the curves. Defaults to False.

• apply_background (bool, optional) – If True, applies background noise to the curves. Defaults to False.

• consistent_rel_err (bool, optional) – If True, uses a consistent relative error for Poisson noise across all points in a curve. Defaults to False.

• add_to_context (bool, optional) – If True, adds generated noise parameters to the context dictionary. Defaults to False.

• logdist (bool, optional) – If True, samples relative errors for Poisson noise in logarithmic space. Defaults to False.

apply(curves: Tensor, context: dict | None = None)

applies the specified types of noise to the input curves

class BasicQNoiseGenerator(shift_std: float = 0.001, noise_std: float | Tuple[float, float] = (0, 0.001), add_to_context: bool = False)

Bases: QNoiseGenerator

Q noise generator which applies both systematic shifts (same change for all q points in the curve) and random noise (different changes per q point in the curve)

Parameters:

• shift_std (float, optional) – the standard deviation of the normal distribution for systematic q shifts (i.e. same change applied to all q points in the curve). Defaults to 1e-3.

• noise_std (Union[float, Tuple[float, float]], optional) – the standard deviation of the normal distribution for random q noise (i.e. different changes applied to each q point in the curve). The standard deviation is the same for all curves in the batch if provided as a float, or uniformly sampled for each curve in the batch if provided as a tuple. Defaults to (0, 1e-3).

apply(qs: Tensor, context: dict | None = None)

applies random noise to the q values

class ConstantAngle(angle_range: Tuple[float, float, int] = (0.0, 0.2, 257), wavelength: float = 1.0, device=device(type='cuda'), dtype=torch.float64)

Bases: QGenerator

Q generator for reflectivity curves measured at equidistant angles

Parameters:

• angle_range (Tuple[float, float, int], optional) – the range of the incident angles. Defaults to (0., 0.2, 257).

• wavelength (float, optional) – the beam wavelength in units of angstroms. Defaults to 1.

• device (optional) – the Pytorch device. Defaults to DEFAULT_DEVICE.

• dtype (optional) – the Pytorch data type. Defaults to DEFAULT_DTYPE.

get_batch(batch_size: int, context: dict | None = None) → Tensor

generate a batch of q values

Parameters:

batch_size (int) – the batch size

Returns:

generated batch of q values

Return type:

Tensor

class SubpriorParametricSampler(param_ranges: Dict[str, Tuple[float, float]], bound_width_ranges: Dict[str, Tuple[float, float]], model_name: str, device: device = device(type='cuda'), dtype: dtype = torch.float64, max_num_layers: int = 50, logdist: bool = False, scale_params_by_ranges=False, scaled_range: Tuple[float, float] = (-1.0, 1.0), **kwargs)

Bases: PriorSampler, ScalerMixin

PARAM_CLS

alias of BasicParams

property max_num_layers: int

gets the maximum number of layers

property param_dim: int

get the number of parameters (parameter dimensionality)

sample(batch_size: int) → BasicParams

sample a batch of parameters

Parameters:

batch_size (int) – the batch size

Returns:

sampled parameters

Return type:

BasicParams

scale_params(params: BasicParams) → Tensor

scale the parameters to a ML-friendly range

Parameters:

params (BasicParams) – the parameters to be scaled

Returns:

the scaled parameters

Return type:

Tensor

restore_params(scaled_params: Tensor) → BasicParams

restore the parameters to their original range

Parameters:

scaled_params (Tensor) – the scaled parameters

Returns:

the parameters restored to their original range

Return type:

BasicParams

class BasicParams(parameters: Tensor, min_bounds: Tensor, max_bounds: Tensor, max_num_layers: int | None = None, param_model: ParametricModel | None = None)

Bases: AbstractParams

Parameter class compatible with different parameterizations of the SLD profile. It stores the parameters as well as their minimum and maximum subprior bounds.

Parameters:

• parameters (Tensor) – the values of the thin film parameters

• min_bounds (Tensor) – the minimum subprior bounds of the parameters

• max_bounds (Tensor) – the maximum subprior bounds of the parameters

• max_num_layers (int, optional) – the maximum number of layers (for box model parameterizations it is the number of layers). Defaults to None.

• param_model (ParametricModel, optional) – the parametric model. Defaults to the box model parameterization with number of layers given by max_num_layers.

get_param_labels() → List[str]

gets the parameter labels

reflectivity(q: Tensor, log: bool = False, **kwargs)

computes the reflectivity curves directly from the parameters

Parameters:

• q (Tensor) – the q values

• log (bool, optional) – whether to apply logarithm to the curves. Defaults to False.

Returns:

the simulated reflectivity curves

Return type:

Tensor

property max_layer_num: int

gets the maximum number of layers

property num_params: int

get the number of parameters (parameter dimensionality)

property thicknesses

gets the thicknesses

property roughnesses

gets the roughnesses

property slds

gets the slds

as_tensor(add_bounds: bool = True, **kwargs) → Tensor

converts the instance of the class to a Pytorch tensor

Parameters:

add_bounds (bool, optional) – whether to add the subprior bounds to the tensor. Defaults to True.

Returns:

the Pytorch tensor obtained from the instance of the class

Return type:

Tensor

classmethod from_tensor(params: Tensor, **kwargs)

initializes an instance of the class from a Pytorch tensor

Parameters:

params (Tensor) – Pytorch tensor containing the parameter values, min subprior bounds and max subprior bounds

Returns:

the instance of the class

Return type:

BasicParams

scale_with_q(q_ratio: float)

scales the parameters based on the q ratio

Parameters:

q_ratio (float) – the scaling ratio

class ParametricModel(max_num_layers: int, **kwargs)

Bases: object

Base class for parameterizations of the SLD profile.

Parameters:

max_num_layers (int) – the number of layers

property param_dim: int

get the number of parameters

Return type:

int

property sampler_strategy: SamplerStrategy

get the sampler strategy

Return type:

SamplerStrategy

reflectivity(q, parametrized_model: Tensor, **kwargs) → Tensor

computes the reflectivity curves

Parameters:

• q – the reciprocal space (q) positions

• parametrized_model (Tensor) – the values of the parameters

Returns:

the computed reflectivity curves

Return type:

Tensor

init_bounds(param_ranges: Dict[str, Tuple[float, float]], bound_width_ranges: Dict[str, Tuple[float, float]], device=None, dtype=None) → Tuple[Tensor, Tensor, Tensor, Tensor]

initializes arrays storing individually the upper and lower bounds from the dictionaries of parameter and bound width ranges

Parameters:

• param_ranges (Dict[str, Tuple[float, float]]) – parameter ranges

• bound_width_ranges (Dict[str, Tuple[float, float]]) – bound width ranges

• device (optional) – the Pytorch device. Defaults to None.

• dtype (optional) – the Pytorch datatype. Defaults to None.

Return type:

Tuple[Tensor, Tensor, Tensor, Tensor]

get_param_labels() → List[str]

get the list with the name of the parameters

Return type:

List[str]

sample(batch_size: int, total_min_bounds: Tensor, total_max_bounds: Tensor, total_min_delta: Tensor, total_max_delta: Tensor)

samples the parameter values and their prior bounds

Parameters:

• batch_size (int) – the batch size

• total_min_bounds (Tensor) – lower bounds of the parameter ranges

• total_max_bounds (Tensor) – upper bounds of the parameter ranges

• total_min_delta (Tensor) – lower widths of the subprior intervals

• total_max_delta (Tensor) – upper widths of the subprior intervals

Returns:

sampled parameters

Return type:

Tensor

class SamplerStrategy

Bases: object

Base class for sampler strategies

class BasicSamplerStrategy(logdist: bool = False)

Bases: SamplerStrategy

Sampler strategy with no constraints on the values of the parameters

Parameters:

logdist (bool, optional) – if True the relative widths of the subprior intervals are sampled uniformly on a logarithmic scale instead of uniformly. Defaults to False.

sample(batch_size: int, total_min_bounds: Tensor, total_max_bounds: Tensor, total_min_delta: Tensor, total_max_delta: Tensor)

Parameters:

• batch_size (int) – the batch size

• total_min_bounds (Tensor) – mimimum values of the parameters

• total_max_bounds (Tensor) – maximum values of the parameters

• total_min_delta (Tensor) – minimum widths of the subprior intervals

• total_max_delta (Tensor) – maximum widths of the subprior intervals

Returns:

samples the values of the parameters and their prior bounds (params, min_bounds, max_bounds). The widths W of the subprior interval are sampled first, then the centers C of the subprior interval, such that the prior bounds are C-W/2 and C+W/2, then the parameters are sampled from [C-W/2, C+W/2] )

Return type:

tuple(Tensor)

class ConstrainedRoughnessSamplerStrategy(thickness_mask: Tensor, roughness_mask: Tensor, logdist: bool = False, max_thickness_share: float = 0.5)

Bases: BasicSamplerStrategy

Sampler strategy where the roughnesses are constrained not to exceed a fraction of the two neighboring thicknesses

Parameters:

• thickness_mask (Tensor) – indices in the tensors which correspond to thicknesses

• roughness_mask (Tensor) – indices in the tensors which correspond to roughnesses

• logdist (bool, optional) – if True the relative widths of the subprior intervals are sampled uniformly on a logarithmic scale instead of uniformly. Defaults to False.

• max_thickness_share (float, optional) – fraction of the layer thickness that the roughness should not exceed. Defaults to 0.5.

sample(batch_size: int, total_min_bounds: Tensor, total_max_bounds: Tensor, total_min_delta: Tensor, total_max_delta: Tensor)

Parameters:

• batch_size (int) – the batch size

• total_min_bounds (Tensor) – mimimum values of the parameters

• total_max_bounds (Tensor) – maximum values of the parameters

• total_min_delta (Tensor) – minimum widths of the subprior intervals

• total_max_delta (Tensor) – maximum widths of the subprior intervals

Returns:

samples the values of the parameters and their prior bounds (params, min_bounds, max_bounds), the roughnesses being constrained. The widths W of the subprior interval are sampled first, then the centers C of the subprior interval, such that the prior bounds are C - W / 2 and C + W / 2, then the parameters are sampled from [C - W / 2, C + W / 2] )

Return type:

tuple(Tensor)

class ConstrainedRoughnessAndImgSldSamplerStrategy(thickness_mask: Tensor, roughness_mask: Tensor, sld_mask: Tensor, isld_mask: Tensor, logdist: bool = False, max_thickness_share: float = 0.5, max_sld_share: float = 0.2)

Bases: BasicSamplerStrategy

Sampler strategy where the roughnesses are constrained not to exceed a fraction of the two neighboring thicknesses, and the imaginary slds are constrained not to exceed a fraction of the real slds

Parameters:

• thickness_mask (Tensor) – indices in the tensors which correspond to thicknesses

• roughness_mask (Tensor) – indices in the tensors which correspond to roughnesses

• sld_mask (Tensor) – indices in the tensors which correspond to real slds

• isld_mask (Tensor) – indices in the tensors which correspond to imaginary slds

• logdist (bool, optional) – if True the relative widths of the subprior intervals are sampled uniformly on a logarithmic scale instead of uniformly. Defaults to False.

• max_thickness_share (float, optional) – fraction of the layer thickness that the roughness should not exceed. Defaults to 0.5

• max_sld_share (float, optional) – fraction of the real sld that the imaginary sld should not exceed. Defaults to 0.2.

sample(batch_size: int, total_min_bounds: Tensor, total_max_bounds: Tensor, total_min_delta: Tensor, total_max_delta: Tensor)

Parameters:

• batch_size (int) – the batch size

• total_min_bounds (Tensor) – mimimum values of the parameters

• total_max_bounds (Tensor) – maximum values of the parameters

• total_min_delta (Tensor) – minimum widths of the subprior intervals

• total_max_delta (Tensor) – maximum widths of the subprior intervals

Returns:

samples the values of the parameters and their prior bounds (params, min_bounds, max_bounds), the roughnesses and imaginary slds being constrained. The widths W of the subprior interval are sampled first, then the centers C of the subprior interval, such that the prior bounds are C - W /2 and C + W / 2, then the parameters are sampled from [C - W / 2, C + W / 2] )

Return type:

tuple(Tensor)

class Trainer(model: ~torch.nn.modules.module.Module, loader: ~reflectorch.ml.basic_trainer.DataLoader, lr: float, batch_size: int, clip_grad_norm_max: int | None = None, train_with_q_input: bool = False, logger: ~reflectorch.ml.loggers.Logger | ~typing.Tuple[~reflectorch.ml.loggers.Logger, ...] | ~reflectorch.ml.loggers.Loggers | None = None, optim_cls: ~typing.Type[~torch.optim.optimizer.Optimizer] = <class 'torch.optim.adam.Adam'>, optim_kwargs: dict | None = None, **kwargs)

Bases: object

Trainer class

Parameters:

• model (nn.Module) – neural network

• loader (DataLoader) – data loader

• lr (float) – learning rate

• batch_size (int) – batch size

• clip_grad_norm (int, optional) – maximum norm for gradient clipping if it is not None. Defaults to None.

• logger (Union[Logger, Tuple[Logger, ...], Loggers], optional) – logger. Defaults to None.

• optim_cls (Type[torch.optim.Optimizer], optional) – Pytorch optimizer. Defaults to torch.optim.Adam.

• optim_kwargs (dict, optional) – optimizer arguments. Defaults to None.

• train_with_q_input (bool, optional) – if True the q values are also used as input. Defaults to False.

log(name: str, data)

log data

train(num_batches: int, callbacks: Tuple[TrainerCallback, ...] | TrainerCallback = (), disable_tqdm: bool = False, update_tqdm_freq: int = 10, grad_accumulation_steps: int = 1)

starts the training process

Parameters:

• num_batches (int) – total number of training iterations

• callbacks (Union[Tuple['TrainerCallback'], 'TrainerCallback']) – the trainer callbacks. Defaults to ().

• disable_tqdm (bool, optional) – if True, the progress bar is disabled. Defaults to False.

• update_tqdm_freq (int, optional) – frequency for updating the progress bar. Defaults to 10.

• grad_accumulation_steps (int, optional) – number of gradient accumulation steps. Defaults to 1.

configure_optimizer(optim_cls, lr: float, **kwargs) → Optimizer

configure the optimizer based on the optimizer class, the learning rate and the optimizer keyword arguments

Parameters:

• optim_cls – the class of the optimizer

• lr (float) – the learning rate

Return type:

torch.optim.Optimizer

lr(param_group: int = 0) → float

get the learning rate

set_lr(lr: float, param_group: int = 0) → None

set the learning rate

class TrainerCallback

Bases: object

Base class for trainer callbacks

start_training(trainer: Trainer) → None

add functionality the start of training

Parameters:

trainer (Trainer) – the trainer object

end_training(trainer: Trainer) → None

add functionality at the end of training

Parameters:

trainer (Trainer) – the trainer object

end_batch(trainer: Trainer, batch_num: int) → bool | None

add functionality at the end of the iteration / batch

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the index of the current iteration / batch

Return type:

Union[bool, None]

class PeriodicTrainerCallback(step: int = 1, last_epoch: int = -1)

Bases: TrainerCallback

Base class for trainer callbacks which perform an action periodically after a number of iterations

Parameters:

• step (int, optional) – Number of iterations after which the action is repeated. Defaults to 1.

• last_epoch (int, optional) – the last training iteration for which the action is performed. Defaults to -1.

end_batch(trainer: Trainer, batch_num: int) → bool | None

add functionality at the end of the iteration / batch

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the index of the current iteration / batch

Return type:

Union[bool, None]

class SaveBestModel(path: str, freq: int = 50, average: int = 10)

Bases: TrainerCallback

Callback for periodically saving the best model weights

Parameters:

• path (str) – path for saving the model weights

• freq (int, optional) – frequency in iterations at which the current average loss is evaluated. Defaults to 50.

• average (int, optional) – number of recent iterations over which the average loss is computed. Defaults to 10.

end_batch(trainer: Trainer, batch_num: int) → None

checks if the current average loss has improved from the previous save, if true the model is saved

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the current iteration / batch

save(trainer: Trainer, batch_num: int)

saves a dictionary containing the network weights, the learning rates, the losses and the current best loss with its corresponding iteration to the disk

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the current iteration / batch

class LogLosses

Bases: TrainerCallback

Callback for logging the training losses

end_batch(trainer: Trainer, batch_num: int) → None

log loss at the current iteration

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the index of the current iteration / batch

class Logger

Bases: object

Base class defining a common interface for logging

class Loggers(*loggers)

Bases: Logger

Class for using multiple loggers

class PrintLogger

Bases: Logger

Logger which prints to the console

class ScheduleBatchSize(step: int, gamma: int = 2, last_epoch: int = -1, mode: str = 'add')

Bases: PeriodicTrainerCallback

Batch size scheduler

Parameters:

• step (int) – number of iterations after which the batch size is modified.

• gamma (int, optional) – quantity which is added to or multiplied with the current batch size. Defaults to 2.

• last_epoch (int, optional) – the last training iteration for which the batch size is modified. Defaults to -1.

• mode (str, optional) – 'add' for addition or 'multiply' for multiplication. Defaults to ‘add’.

class ScheduleLR(lr_scheduler_cls, **kwargs)

Bases: TrainerCallback

Base class for learning rate schedulers

Parameters:

lr_scheduler_cls – class of the learning rate scheduler

start_training(trainer: Trainer) → None

initializes a learning rate scheduler based on its class and keyword arguments at the start of training

Parameters:

trainer (Trainer) – the trainer object

end_batch(trainer: Trainer, batch_num: int) → None

modifies the learning rate at the end of each iteration

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – index of the current iteration

class StepLR(step_size: int, gamma: float, last_epoch: int = -1, **kwargs)

Bases: ScheduleLR

Learning rate scheduler which decays the learning rate of each parameter group by gamma every step_size epochs.

Parameters:

• step_size (int) – Period of learning rate decay

• gamma (float) – Multiplicative factor of learning rate decay

• last_epoch (int, optional) – The index of last iteration. Defaults to -1.

start_training(trainer: Trainer) → None

initializes a learning rate scheduler based on its class and keyword arguments at the start of training

Parameters:

trainer (Trainer) – the trainer object

class CyclicLR(base_lr, max_lr, step_size_up: int = 2000, cycle_momentum: bool = False, gamma: float = 1.0, mode: str = 'triangular', **kwargs)

Bases: ScheduleLR

Cyclic learning rate scheduler

Parameters:

• base_lr (float) – Initial learning rate which is the lower boundary in the cycle

• max_lr (float) – Upper learning rate boundary in the cycle

• step_size_up (int, optional) – Number of training iterations in the increasing half of a cycle. Defaults to 2000.

• cycle_momentum (bool, optional) – If True, momentum is cycled inversely to learning rate between base_momentum and max_momentum. Defaults to False.

• gamma (float, optional) – Constant in ‘exp_range’ mode scaling function: gamma^(cycle iterations). Defaults to 1.

• mode (str, optional) – One of: 'triangular' (a basic triangular cycle without amplitude scaling), 'triangular2' (a basic triangular cycle that scales initial amplitude by half each cycle), 'exp_range' (a cycle that scales initial amplitude by gamma^iterations at each cycle iteration). Defaults to ‘triangular’.

class LogCyclicLR(base_lr, max_lr, period: int = 2000, gamma: float | None = None, log: bool = True, param_groups: tuple = (0,), start_period: int = 25)

Bases: TrainerCallback

Cyclic learning rate scheduler on a logarithmic scale

Parameters:

• base_lr (float) – Lower learning rate boundary in the cycle

• max_lr (float) – Upper learning rate boundary in the cycle

• period (int, optional) – Number of training iterations in the cycle. Defaults to 2000.

• gamma (float, optional) – Constant for scaling the amplitude as gamma ^ iterations. Defaults to 1.

• start_period (int, optional) – Number of starting iterations with the default learning rate.

• log (bool, optional) – If True, the cycle is in the logarithmic domain.

• param_groups (tupe, optional) – Parameter groups of the optimizer.

end_batch(trainer: Trainer, batch_num: int)

add functionality at the end of the iteration / batch

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the index of the current iteration / batch

Return type:

Union[bool, None]

class ReduceLROnPlateau(gamma: float = 0.5, patience: int = 500, average: int = 50, loss_key: str = 'total_loss', param_groups: tuple = (0,))

Bases: TrainerCallback

Learning rate scheduler which reduces the learning rate when the loss stops decreasing

Parameters:

• gamma (float, optional) – Multiplicative factor of learning rate decay. Defaults to 0.5.

• patience (int, optional) – The number of allowed iterations with no improvement after which the learning rate will be reduced. Defaults to 500.

• average (int, optional) – Size of the window over which the average loss is computed. Defaults to 50.

• loss_key (str, optional) – Defaults to ‘total_loss’.

• param_groups (tuple, optional) – Defaults to (0,).

end_batch(trainer: Trainer, batch_num: int) → None

add functionality at the end of the iteration / batch

Parameters:

• trainer (Trainer) – the trainer object

• batch_num (int) – the index of the current iteration / batch

Return type:

Union[bool, None]

class OneCycleLR(max_lr: float, total_steps: int, pct_start: float = 0.3, div_factor: float = 25.0, final_div_factor: float = 10000.0, three_phase: bool = True, **kwargs)

Bases: ScheduleLR

One-cycle learning rate scheduler (https://arxiv.org/abs/1708.07120)

Parameters:

• max_lr (float) – Upper learning rate boundary in the cycle

• total_steps (int) – The total number of steps in the cycle

• pct_start (float, optional) – The percentage of the cycle (in number of steps) spent increasing the learning rate. Defaults to 0.3.

• div_factor (float, optional) – Determines the initial learning rate via initial_lr = max_lr / div_factor. Defaults to 25..

• final_div_factor (float, optional) – Determines the minimum learning rate via min_lr = initial_lr / final_div_factor. Defaults to 1e4.

• three_phase (bool, optional) – If True, use a third phase of the schedule to annihilate the learning rate according to final_div_factor instead of modifying the second phase. Defaults to True.

class ReflectivityDataLoader(q_generator: QGenerator, prior_sampler: PriorSampler, intensity_noise: IntensityNoiseGenerator | None = None, q_noise: QNoiseGenerator | None = None, curves_scaler: CurvesScaler | None = None, calc_denoised_curves: bool = False, smearing: Smearing | None = None)

Bases: BasicDataset, DataLoader

Dataloader for reflectivity data, combining functionality from the BasicDataset (basic dataset class for reflectivity) and the DataLoader (which inherits from TrainerCallback) classes

class RealTimeSimTrainer(model: ~torch.nn.modules.module.Module, loader: ~reflectorch.ml.basic_trainer.DataLoader, lr: float, batch_size: int, clip_grad_norm_max: int | None = None, train_with_q_input: bool = False, logger: ~reflectorch.ml.loggers.Logger | ~typing.Tuple[~reflectorch.ml.loggers.Logger, ...] | ~reflectorch.ml.loggers.Loggers | None = None, optim_cls: ~typing.Type[~torch.optim.optimizer.Optimizer] = <class 'torch.optim.adam.Adam'>, optim_kwargs: dict | None = None, **kwargs)

Bases: Trainer

Trainer with functionality to customize the sampled batch of data

get_batch_by_idx(batch_num: int)

Gets a batch of data with the default batch size

get_batch_by_size(batch_size: int)

Gets a batch of data with a custom batch size

class PointEstimatorTrainer(model: ~torch.nn.modules.module.Module, loader: ~reflectorch.ml.basic_trainer.DataLoader, lr: float, batch_size: int, clip_grad_norm_max: int | None = None, train_with_q_input: bool = False, logger: ~reflectorch.ml.loggers.Logger | ~typing.Tuple[~reflectorch.ml.loggers.Logger, ...] | ~reflectorch.ml.loggers.Loggers | None = None, optim_cls: ~typing.Type[~torch.optim.optimizer.Optimizer] = <class 'torch.optim.adam.Adam'>, optim_kwargs: dict | None = None, **kwargs)

Bases: RealTimeSimTrainer

Trainer for the regression inverse problem with incorporation of prior bounds

get_loss_dict(batch_data)

computes the loss dictionary

class ConvEncoder(in_channels: int = 1, hidden_channels: tuple = (32, 64, 128, 256, 512), dim_latent: int = 64, dim_avpool: int = 1, use_batch_norm: bool = True, activation: str = 'relu')

Bases: Module

A 1D CNN encoder / embedding network

Parameters:

• in_channels (int, optional) – the number of input channels. Defaults to 1.

• hidden_channels (tuple, optional) – the number of intermediate channels of each convolutional layer. Defaults to (32, 64, 128, 256, 512).

• dim_latent (int, optional) – the dimension of the output latent embedding. Defaults to 64.

• dim_avpool (int, optional) – the output size of the adaptive average pooling layer. Defaults to 1.

• use_batch_norm (bool, optional) – whether to use batch normalization. Defaults to True.

• activation (str, optional) – the type of activation function. Defaults to ‘relu’.

class FnoEncoder(ch_in: int = 2, dim_embedding: int = 128, modes: int = 32, width_fno: int = 64, n_fno_blocks: int = 6, activation: str = 'gelu', fusion_self_attention: bool = False)

Bases: Module

An embedding network based on the Fourier Neural Operator (FNO) architecture

Parameters:

• ch_in (int) – number of input channels

• dim_embedding (int) – dimension of the output embedding

• modes (int) – number of Fourier modes

• width_fno (int) – number of channels of the intermediate representations

• n_fno_blocks (int) – number of FNO blocks

• activation (str) – the activation function

• fusion_self_attention (bool) – if True a fusion layer is used after the FNO blocks to produce the final embedding

class NetworkWithPriorsConvEmb(in_channels: int = 1, hidden_channels: tuple = (32, 64, 128, 256, 512), dim_embedding: int = 128, dim_avpool: int = 1, embedding_net_activation: str = 'gelu', use_batch_norm: bool = False, dim_out: int = 8, layer_width: int = 512, num_blocks: int = 4, repeats_per_block: int = 2, mlp_activation: str = 'gelu', dropout_rate: float = 0.0, use_selu_init: bool = False, pretrained_embedding_net: str | None = None, residual: bool = True, adaptive_activation: bool = False, conditioning: str = 'concat')

Bases: Module

MLP network with 1D CNN embedding network

Parameters:

• in_channels (int, optional) – the number of input channels of the 1D CNN. Defaults to 1.

• hidden_channels (tuple, optional) – list with the number of channels for each layer of the 1D CNN. Defaults to (32, 64, 128, 256, 512).

• dim_embedding (int, optional) – the dimension of the embedding produced by the 1D CNN. Defaults to 128.

• dim_avpool (int, optional) – the type of activation function in the 1D CNN. Defaults to 1.

• embedding_net_activation (str, optional) – the type of activation function in the 1D CNN. Defaults to ‘gelu’.

• use_batch_norm (bool, optional) – whether to use batch normalization (in both the 1D CNN and the MLP). Defaults to False.

• dim_out (int, optional) – the dimension of the output produced by the MLP. Defaults to 8.

• layer_width (int, optional) – the width of a linear layer in the MLP. Defaults to 512.

• num_blocks (int, optional) – the number of residual blocks in the MLP. Defaults to 4.

• repeats_per_block (int, optional) – the number of normalization/activation/linear repeats in a block. Defaults to 2.

• mlp_activation (str, optional) – the type of activation function in the MLP. Defaults to ‘gelu’.

• dropout_rate (float, optional) – dropout rate for each block. Defaults to 0.0.

• use_selu_init (bool, optional) – whether to use the special weights initialization for the ‘selu’ activation function. Defaults to False.

• pretrained_embedding_net (str, optional) – the path to the weights of a pretrained embedding network. Defaults to None.

• residual (bool, optional) – whether the blocks have a residual skip connection. Defaults to True.

• adaptive_activation (bool, optional) – must be set to True if the activation function is adaptive. Defaults to False.

• conditioning (str, optional) – the manner in which the prior bounds are provided as input to the network. Defaults to ‘concat’.

forward(curves: Tensor, bounds: Tensor, q_values: Tensor | None = None)

Parameters:

• curves (Tensor) – reflectivity curves

• bounds (Tensor) – prior bounds

• q_values (Tensor, optional) – q values. Defaults to None.

Returns:

prediction

Return type:

Tensor

class NetworkWithPriorsFnoEmb(in_channels: int = 2, dim_embedding: int = 128, modes: int = 16, width_fno: int = 64, embedding_net_activation: str = 'gelu', n_fno_blocks: int = 6, fusion_self_attention: bool = False, dim_out: int = 8, layer_width: int = 512, num_blocks: int = 4, repeats_per_block: int = 2, use_batch_norm: bool = False, mlp_activation: str = 'gelu', dropout_rate: float = 0.0, use_selu_init: bool = False, residual: bool = True, adaptive_activation: bool = False, conditioning: str = 'concat')

Bases: Module

MLP network with FNO embedding network

Parameters:

• in_channels (int, optional) – the number of input channels to the FNO-based embedding network. Defaults to 2.

• dim_embedding (int, optional) – the dimension of the embedding produced by the FNO. Defaults to 128.

• modes (int, optional) – the number of Fourier modes that are utilized. Defaults to 16.

• width_fno (int, optional) – the number of channels in the FNO blocks. Defaults to 64.

• embedding_net_activation (str, optional) – the type of activation function in the embedding network. Defaults to ‘gelu’.

• n_fno_blocks (int, optional) – the number of FNO blocks. Defaults to 6.

• fusion_self_attention (bool, optional) – if True a fusion layer is used after the FNO blocks to produce the final output. Defaults to False.

• dim_out (int, optional) – the dimension of the output produced by the MLP. Defaults to 8.

• layer_width (int, optional) – the width of a linear layer in the MLP. Defaults to 512.

• num_blocks (int, optional) – the number of residual blocks in the MLP. Defaults to 4.

• repeats_per_block (int, optional) – the number of normalization/activation/linear repeats in a block. Defaults to 2.

• use_batch_norm (bool, optional) – whether to use batch normalization (only in the MLP). Defaults to False.

• mlp_activation (str, optional) – the type of activation function in the MLP. Defaults to ‘gelu’.

• dropout_rate (float, optional) – dropout rate for each block. Defaults to 0.0.

• use_selu_init (bool, optional) – whether to use the special weights initialization for the ‘selu’ activation function. Defaults to False.

• residual (bool, optional) – whether the blocks have a residual skip connection. Defaults to True.

• adaptive_activation (bool, optional) – must be set to True if the activation function is adaptive. Defaults to False.

• conditioning (str, optional) – the manner in which the prior bounds are provided as input to the network. Defaults to ‘concat’.

forward(curves: Tensor, bounds: Tensor, q_values: Tensor | None = None)

Parameters:

• curves (Tensor) – reflectivity curves

• bounds (Tensor) – prior bounds

• q_values (Tensor, optional) – q values. Defaults to None.

Returns:

prediction

Return type:

Tensor

to_np(arr)

Converts Pytorch tensor or Python list to Numpy array

Parameters:

arr (torch.Tensor or list) – Input Pytorch tensor or Python list

Returns:

Converted Numpy array

Return type:

numpy.ndarray

to_t(arr, device=None, dtype=None)

Converts Numpy array or Python list to Pytorch tensor

Parameters:

• arr (numpy.ndarray or list) – Input

• device (torch.device or str, optional) – device for the tensor (‘cpu’, ‘cuda’)

• dtype (torch.dtype, optional) – data type of the tensor (e.g. torch.float32)

Returns:

converted Pytorch tensor

Return type:

torch.Tensor

angle_to_q(scattering_angle: ndarray, wavelength: float)

Conversion from full scattering angle (degrees) to scattering vector (inverse angstroms)

q_to_angle(q: ndarray, wavelength: float)

Conversion from scattering vector (inverse angstroms) to full scattering angle (degrees)

energy_to_wavelength(energy: float)

Conversion from photon energy (eV) to photon wavelength (angstroms)

wavelength_to_energy(wavelength: float)

Conversion from photon wavelength (angstroms) to photon energy (eV)

train_from_config(config: dict)

Train a model from a configuration dictionary

Parameters:

config (dict) – configuration dictionary

Returns:

the trainer object

Return type:

Trainer

get_trainer_from_config(config: dict, folder_paths: dict | None = None)

Initializes a trainer from a configuration dictionary

Parameters:

• config (dict) – the configuration dictionary

• folder_paths (dict, optional) – dictionary containing the folder paths

Returns:

the trainer object

Return type:

Trainer

get_paths_from_config(config: dict, mkdir: bool = False)

Get the directory paths from a configuration dictionary

Parameters:

• config (dict) – configuration dictionary

• mkdir (bool, optional) – option to create a new directory for the saved model weights and losses.

Returns:

dictionary containing the folder paths

Return type:

dict

get_callbacks_from_config(config: dict, folder_paths: dict | None = None) → Tuple[TrainerCallback, ...]

Initializes the training callbacks from a configuration dictionary

Returns:

tuple of callbacks

Return type:

tuple

get_trainer_by_name(config_name, config_dir=None, model_path=None, load_weights: bool = True, inference_device: str = 'cuda')

Initializes a trainer object based on a configuration file (i.e. the model name) and optionally loads saved weights into the network

Parameters:

• config_name (str) – name of the configuration file

• config_dir (str) – path of the configuration directory

• model_path (str, optional) – path to the network weights.

• load_weights (bool, optional) – if True the saved network weights are loaded into the network. Defaults to True.

• inference_device (str, optional) – overwrites the device in the configuration file for the purpose of inference on a different device then the training was performed on. Defaults to ‘cuda’.

Returns:

the trainer object

Return type:

Trainer

convert_pt_to_safetensors(input_dir)

Creates ‘.safetensors’ files for all the model state dictionaries inside ‘.pt’ files in the specified directory.

Parameters:

input_dir (str) – directory containing model weights

load_config(config_name: str, config_dir: str | None = None) → dict

Loads a configuration dictionary from a YAML configuration file located in the configuration directory

Parameters:

• config_name (str) – name of the YAML configuration file

• config_dir (str) – path of the configuration directory

Returns:

the configuration dictionary

Return type:

dict

class EasyInferenceModel(config_name: str | None = None, model_name: str | None = None, root_dir: str | None = None, weights_format: str = 'safetensors', repo_id: str = 'valentinsingularity/reflectivity', trainer: PointEstimatorTrainer | None = None, device='cuda')

Bases: object

Facilitates the inference process using pretrained models

Parameters:

• config_name (str, optional) – the name of the configuration file used to initialize the model (either with or without the ‘.yaml’ extension). Defaults to None.

• model_name (str, optional) – the name of the file containing the weights of the model (either with or without the ‘.pt’ extension), only required if different than: ‘model_’ + config_name + ‘.pt’. Defaults to None

• root_dir (str, optional) – path to root directory containing the ‘configs’ and ‘saved_models’ subdirectories, if different from the package root directory (ROOT_DIR). Defaults to None.

• weights_format (str, optional) – format (extension) of the weights file, either ‘pt’ or ‘safetensors’. Defaults to ‘safetensors’.

• repo_id (str, optional) – the id of the Huggingface repository from which the configuration files and model weights should be downloaded automatically if not found locally (in the ‘configs’ and ‘saved_models’ subdirectories of the root directory). Defaults to ‘valentinsingularity/reflectivity’.

• trainer (PointEstimatorTrainer, optional) – if provided, this trainer instance is used directly instead of being initialized from the configuration file. Defaults to None.

• device (str, optional) – the Pytorch device (‘cuda’ or ‘cpu’). Defaults to ‘cuda’.

load_model(config_name: str, model_name: str, root_dir: str) → None

Loads a model for inference

Parameters:

• config_name (str) – the name of the configuration file used to initialize the model (either with or without the ‘.yaml’ extension).

• model_name (str) – the name of the file containing the weights of the model (either with or without the ‘.pt’ or ‘.safetensors’ extension), only required if different than: ‘model_’ + config_name + extension.

• root_dir (str) – path to root directory containing the ‘configs’ and ‘saved_models’ subdirectories, if different from the package root directory (ROOT_DIR).

predict(reflectivity_curve: ndarray | Tensor, q_values: ndarray | Tensor | None = None, prior_bounds: ndarray | List[Tuple] | None = None, clip_prediction: bool = False, polish_prediction: bool = False, fit_growth: bool = False, max_d_change: float = 5.0, use_q_shift: bool = False, calc_pred_curve: bool = True, calc_pred_sld_profile: bool = False)

Predict the thin film parameters

Parameters:

• reflectivity_curve (Union[np.ndarray, Tensor]) – The reflectivity curve (which has been already preprocessed, normalized and interpolated).

• q_values (Union[np.ndarray, Tensor], optional) – The momentum transfer (q) values for the reflectivity curve (in units of inverse angstroms).

• prior_bounds (Union[np.ndarray, List[Tuple]], optional) – the prior bounds for the thin film parameters.

• clip_prediction (bool, optional) – If True, the values of the predicted parameters are clipped to not be outside the interval set by the prior bounds. Defaults to False.

• polish_prediction (bool, optional) – If True, the neural network predictions are further polished using a simple least mean squares (LMS) fit. Only for the standard box-model parameterization. Defaults to False.

• fit_growth (bool, optional) – If True, an additional parameters is introduced during the LMS polishing to account for the change in the thickness of the upper layer during the in-situ measurement of the reflectivity curve (a linear growth is assumed). Defaults to False.

• max_d_change (float) – The maximum possible change in the thickness of the upper layer during the in-situ measurement, relevant when polish_prediction and fit_growth are True. Defaults to 5.

• use_q_shift – If True, the prediction is performed for a batch of slightly shifted versions of the input curve and the best result is returned, which is meant to mitigate the influence of imperfect sample alignment, as introduced in Greco et al. (only for models with fixed q-discretization). Defaults to False.

• calc_pred_curve (bool, optional) – Whether to calculate the curve corresponding to the predicted parameters. Defaults to True.

• calc_pred_sld_profile (bool, optional) – Whether to calculate the SLD profile corresponding to the predicted parameters. Defaults to False.

Returns:

dictionary containing the predictions

Return type:

dict

async predict_using_widget(reflectivity_curve: ndarray | Tensor, **kwargs)

Use an interactive Python widget for specifying the prior bounds before the prediction (works only in a Jupyter notebook). The other arguments are the same as for the predict method.

class HuggingfaceQueryMatcher(repo_id='valentinsingularity/reflectivity', config_dir='configs')

Bases: object

Downloads the available configurations files to a temporary directory and provides functionality for filtering those configuration files matching user specified queries.

Parameters:

• repo_id (str) – The Hugging Face repository ID.

• config_dir (str) – Directory within the repo where YAML files are stored.

get_matching_configs(query)

retrieves configuration files that match the user specified query.

Parameters:

query (dict) – Dictionary of key-value pairs to filter configurations, e.g. query = {'dset.prior_sampler.kwargs.max_num_layers': 3, 'dset.prior_sampler.kwargs.param_ranges.slds': [0., 100.]}. For keys containing the param_ranges subkey a configuration is selected if the value of the query (i.e. desired parameter range) is a subrange of the parameter range in the configuration, in all other cases the values must match exactly.

Returns:

List of file names that match the query.

Return type:

list

standard_preprocessing(intensity: ndarray, scattering_angle: ndarray, attenuation: ndarray, q_interp: ndarray, wavelength: float, beam_width: float, sample_length: float, min_intensity: float = 1e-10, beam_shape: Literal['gauss', 'box'] = 'gauss', normalize_mode: Literal['first', 'max', 'incoming_intensity'] = 'max', incoming_intensity: float | None = None, max_q: float | None = None, max_angle: float | None = None) → dict

Preprocesses a raw experimental reflectivity curve by applying attenuation correction, footprint correction, cutting at a maximum q value and interpolation

Parameters:

• intensity (np.ndarray) – array of intensities of the reflectivity curve

• scattering_angle (np.ndarray) – array of scattering angles

• attenuation (np.ndarray) – attenuation factors for each measured point

• q_interp (np.ndarray) – reciprocal space points used for the interpolation

• wavelength (float) – the wavelength of the beam

• beam_width (float) – the beam width

• sample_length (float) – the sample length

• min_intensity (float, optional) – intensities lower than this value are removed. Defaults to 1e-10.

• beam_shape (BEAM_SHAPE, optional) – the shape of the beam, either “gauss” or “box”. Defaults to “gauss”.

• normalize_mode (NORMALIZE_MODE, optional) – normalization mode, either “first”, “max” or “incoming_intensity”. Defaults to “max”.

• incoming_intensity (float, optional) – array of intensities for the “incoming_intensity” normalization. Defaults to None.

• max_q (float, optional) – the maximum q value at which the curve is cut. Defaults to None.

• max_angle (float, optional) – the maximum scattering angle at which the curve is cut; only used if max_q is not provided. Defaults to None.

Returns:

dictionary containing the interpolated reflectivity curve, the curve before interpolation, the q values before interpolation, the q values after interpolation and the q ratio of the cutting

Return type:

dict

class ReflGradientFit(q: Tensor, exp_curve: Tensor, prior_sampler: PriorSampler, params: Tensor, fit_indices: Tensor, sigmas: Tensor | None = None, optim_cls=None, lr: float = 0.01, rel_err: float = 0.1, abs_err: float = 1e-07)

Bases: object

Directly optimizes the thin film parameters using a Pytorch optimizer

Parameters:

• q (Tensor) – the q positions

• exp_curve (Tensor) – the experimental reflectivity curve

• prior_sampler (PriorSampler) – the prior sampler

• params (Tensor) – the initial thin film parameters

• fit_indices (Tensor) – the indices of the thin film parameters which are to be fitted

• sigmas (Tensor, optional) – error bars of the reflectivity curve, if not provided they are derived from rel_err and abs_err. Defaults to None.

• optim_cls (Type[torch.optim.Optimizer], optional) – the Pytorch optimizer class. Defaults to None.

• lr (float, optional) – the learning rate. Defaults to 1e-2.

• rel_err (float, optional) – the relative error in the reflectivity curve. Defaults to 0.1.

• abs_err (float, optional) – the absolute error in the reflectivity curve. Defaults to 1e-7.

run(num_iterations: int = 500, disable_tqdm: bool = False)

Runs the optimization process

Parameters:

• num_iterations (int, optional) – number of iterations the optimization is run for. Defaults to 500.

• disable_tqdm (bool, optional) – whether to disable the prograss bar. Defaults to False.

interp_reflectivity(q_interp, q, reflectivity, min_value: float = 1e-10)

Interpolate data on a base 10 logarithmic scale

Parameters:

• q_interp (array-like) – reciprocal space points used for the interpolation

• q (array-like) – reciprocal space points of the measured reflectivity curve

• reflectivity (array-like) – reflectivity curve measured at the points q

• min_value (float, optional) – minimum intensity of the reflectivity curve. Defaults to 1e-10.

Returns:

interpolated reflectivity curve

Return type:

array-like

apply_attenuation_correction(intensity: ndarray, attenuation: ndarray, scattering_angle: ndarray | None = None, correct_discontinuities: bool = True) → ndarray

Applies attenuation correction to experimental reflectivity curves

Parameters:

• intensity (np.ndarray) – intensities of an experimental reflectivity curve

• attenuation (np.ndarray) – attenuation factors for each measured point

• scattering_angle (np.ndarray, optional) – scattering angles of the measured points. Defaults to None.

• correct_discontinuities (bool, optional) – whether to correct discontinuities in the measured curves. Defaults to True.

Returns:

the corrected reflectivity curve

Return type:

np.ndarray

apply_footprint_correction(intensity: ndarray, scattering_angle: ndarray, beam_width: float, sample_length: float, beam_shape: Literal['gauss', 'box'] = 'gauss') → ndarray

Applies footprint correction to an experimental reflectivity curve

Parameters:

• intensity (np.ndarray) – reflectivity curve

• scattering_angle (np.ndarray) – array of scattering angles

• beam_width (float) – the beam width

• sample_length (float) – the sample length

• beam_shape (BEAM_SHAPE, optional) – the shape of the beam, either “gauss” or “box”. Defaults to “gauss”.

Returns:

the footprint corrected reflectivity curve

Return type:

np.ndarray