resolution_functions.models.ideal

class resins.models.ideal.GenericBoxcar1DModel(model_data: ModelData, width: float = 1.0, **_)

Bases: StaticSnappedPeaksMixin, SimpleBroaden1DMixin, InstrumentModel

A generic Boxcar model.

Models the resolution as a Boxcar (square) function.

A useful relationship: the standard deviation of a width-1 boxcar is √(1/12). So to produce crudely “equivalent” broadening to a Gaussian of known σ, use a boxcar width = σ √12 .

Parameters:

model_data: The data associated with the model for a given version of a given instrument.
width: The width of the Boxcar function in meV. This width is used for all values of [w, Q].

Attributes:

input: The names of the columns in the points array expected by all computation methods, i.e. the names of the independent variables ([Q, w]) that the model models.
data_class: Abstract base class for defining the data required by a model.
width: The width of the Boxcar function in meV. This width is used for all values of [w, Q].
citation: The citation for this model.

Methods

`__call__`(points, data, *meshes)	Broadens the `data` on the `meshes`.
`broaden`(points, data, mesh)	Broadens the `data` on the full `mesh` using the straightforward scheme.
`data_class`
`get_characteristics`(points)	Returns the broadening width at each value of energy transfer given by `points`.
`get_kernel`(points, mesh)	Computes the Boxcar (square) kernel centered on zero on the provided `mesh` at each value of `points` (energy transfer or momentum scalar).
`get_peak`(points, mesh)	Apply the kernel at the nearest `mesh` point for at each value of `points` energy transfer.

Warning

This model is for testing purposes - it does not do any computation and instead uses the user-provided width for all values of [w, Q]. It should not be normally used to model instruments.

data_class: alias of ModelData

get_characteristics(points: Float[np.ndarray, 'sample dimension=1']) → dict[str, Float[np.ndarray, ' sample']]

Returns the broadening width at each value of energy transfer given by points.

This model is a static test model, so it returns the same width for each value of points, which is in the form of the width of a Boxcar kernel.

Parameters:

points: The energy transfer in meV at which to compute the width in sigma of the kernel. This must be a sample x 1 2D array where sample is the number of energy transfers.

Returns:

characteristics: The characteristics of the broadening function, i.e. the Boxcar width in meV and derived standard deviation (sigma).

get_kernel(points: Float[np.ndarray, 'sample dimension=1'], mesh: Float[np.ndarray, ' mesh']) → Float[np.ndarray, 'sample mesh']

Computes the Boxcar (square) kernel centered on zero on the provided mesh at each value of points (energy transfer or momentum scalar).

Note that these kernels will always consist of an odd-integer number of full-height samples, approximately width wide, moving directly to zero at the surrounding samples. The area is normalised as though this is a trapezoid (i.e. as though lines connect the boxcar top to the surrounding samples), resulting in lower height than the ideal boxcar.

Parameters:

points: The energy transfer or momentum scalar for which to compute the kernel. This must be a Nx1 2D array where N is the number of w/Q values.
mesh: The mesh on which to evaluate the kernel. A 1D array.

Returns:

kernel: The Boxcar kernel at each value of points as given by this model, computed on the mesh and centered on zero. This is a 2D N x M array where N is the number of w/Q values and M is the length of the mesh array.

class resins.models.ideal.GenericGaussian1DModel(model_data: ModelData, sigma: float = 1.0, **_)

Bases: SimpleBroaden1DMixin, GaussianKernel1DMixin, InstrumentModel

A generic Gaussian model.

Models the resolution as a Gaussian function.

Parameters:

model_data: The data associated with the model for a given version of a given instrument.
sigma: The width (in sigma) of the Gaussian function. This width is used for all values of [w, Q].

Attributes:

input: The names of the columns in the points array expected by all computation methods, i.e. the names of the independent variables ([Q, w]) that the model models.
data_class: Abstract base class for defining the data required by a model.
sigma: The width (in sigma) of the Gaussian function. This width is used for all values of [w, Q].
citation: The citation for this model.

Methods

`__call__`(points, data, *meshes)	Broadens the `data` on the `meshes`.
`broaden`(points, data, mesh)	Broadens the `data` on the full `mesh` using the straightforward scheme.
`data_class`
`get_characteristics`(points)	Returns the broadening width at each value of energy transfer given by `points`.
`get_kernel`(points, mesh)	Computes the Gaussian kernel centered on zero on the provided `mesh` at each (energy transfer or momentum scalar) point in `points`.
`get_peak`(points, mesh)	Computes the Gaussian broadening peak on the provided `mesh` at each (energy transfer or momentum scalar) point in `points`.

Warning

This model is for testing purposes - it does not do any computation and instead uses the user-provided width for all values of [w, Q]. It should not be normally used to model instruments.

data_class: alias of ModelData

get_characteristics(points: Float[np.ndarray, 'sample dimension=1']) → dict[str, Float[np.ndarray, ' sample']]

Returns the broadening width at each value of energy transfer given by points.

This model is a static test model, so it returns the same width for each value of points, which is in the form of the standard deviation (sigma) of a Gaussian model.

Parameters:

points: The energy transfer in meV at which to compute the width in sigma of the kernel. This must be a sample x 1 2D array where sample is the number of energy transfers.

Returns:

characteristics: The characteristics of the broadening function, i.e. the Gaussian width as sigma in meV.

class resins.models.ideal.GenericLorentzian1DModel(model_data: ModelData, fwhm: float = 1.0, **_)

Bases: SimpleBroaden1DMixin, InstrumentModel

A generic Lorentzian model.

Models the resolution as a Lorentzian function.

Parameters:

model_data: The data associated with the model for a given version of a given instrument.
fwhm: The width (in Full-Width Half-Maximum) of the Lorentzian function. This width is used for all values of [w, Q].

Attributes:

input: The names of the columns in the points array expected by all computation methods, i.e. the names of the independent variables ([Q, w]) that the model models.
data_class: Abstract base class for defining the data required by a model.
fwhm: The width (in Full-Width Half-Maximum) of the Lorentzian function. This width is used for all values of [w, Q].
citation: The citation for this model.

Methods

`__call__`(points, data, *meshes)	Broadens the `data` on the `meshes`.
`broaden`(points, data, mesh)	Broadens the `data` on the full `mesh` using the straightforward scheme.
`data_class`
`get_characteristics`(points)	Returns the broadening width at each value of energy transfer given by `points`.
`get_kernel`(points, mesh)	Computes the Lorentzian kernel centered on zero on the provided `mesh` at each value of `points` (energy transfer or momentum scalar).
`get_peak`(points, mesh)	Computes the Lorentzian kernel on the provided `mesh` at each value of the `points` energy transfer.

Warning

This model is for testing purposes - it does not do any computation and instead uses the user-provided width for all values of [w, Q]. It should not be normally used to model instruments.

data_class: alias of ModelData

get_characteristics(points: Float[np.ndarray, 'sample dimension=1']) → dict[str, Float[np.ndarray, ' sample']]

Returns the broadening width at each value of energy transfer given by points.

This model is a static test model, so it returns the same width for each value of points, which is in the form of the Full-Width Half-Maximum of a Lorentzian model.

Parameters:

points: The energy transfer in meV at which to compute the width in sigma of the kernel. This must be a sample x 1 2D array where sample is the number of energy transfers.

Returns:

characteristics: The characteristics of the broadening function, i.e. the Lorentzian width as FWHM.

get_kernel(points: Float[np.ndarray, 'sample dimension=1'], mesh: Float[np.ndarray, ' mesh']) → Float[np.ndarray, 'sample mesh']

Computes the Lorentzian kernel centered on zero on the provided mesh at each value of points (energy transfer or momentum scalar).

Parameters:

points: The energy transfer or momentum scalar for which to compute the kernel. This must be a Nx1 2D array where N is the number of w/Q values.
mesh: The mesh on which to evaluate the kernel. A 1D array.

Returns:

kernel: The Lorentzian kernel at each value of points as given by this model, computed on the mesh and centered on zero. This is a 2D N x M array where N is the number of w/Q values and M is the length of the mesh array.

get_peak(points: Float[np.ndarray, 'sample dimension=1'], mesh: Float[np.ndarray, ' mesh']) → Float[np.ndarray, 'sample mesh']

Computes the Lorentzian kernel on the provided mesh at each value of the points energy transfer.

Parameters:

points: The energy transfer in meV for which to compute the kernel. This must be a Nx1 2D array where N is the number of energy transfers.
mesh: The mesh on which to evaluate the kernel. This is a 1D array which must span the points transfer space of interest.

Returns:

kernel: The Lorentzian kernel at each value of points as given by this model, computed on the mesh and centered on the corresponding energy transfer. This is a 2D N x M array where N is the number of w/Q values and M is the length of the mesh array.

class resins.models.ideal.GenericTrapezoid1DModel(model_data: ModelData, long_base: float = 1.0, short_base: float = 0.5, **_)

Bases: SimpleBroaden1DMixin, StaticSnappedPeaksMixin, InstrumentModel

A generic Trapezoid model.

Models the resolution as an isosceles Trapezoid function.

Note that shape and area are only exactly correct when base lengths correspond to an even number of bin widths. The get_peak() and broaden() methods will snap input points to the nearest mesh value; this results in a consistent peak shape.

Parameters:

model_data: The data associated with the model for a given version of a given instrument.
long_base: The length of the longer (bottom) base of the Trapezoid function. This width is used for all values of [w, Q].
short_base: The length of the shorter (top) base of the Trapezoid function. This width is used for all values of [w, Q].

Attributes:

input: The names of the columns in the points array expected by all computation methods, i.e. the names of the independent variables ([Q, w]) that the model models.
data_class: Abstract base class for defining the data required by a model.
long_base: The length of the longer (bottom) base of the Trapezoid function. This width is used for all values of [w, Q].
short_base: The length of the shorter (top) base of the Trapezoid function. This width is used for all values of [w, Q].
citation: The citation for this model.

Methods

`__call__`(points, data, *meshes)	Broadens the `data` on the `meshes`.
`broaden`(points, data, mesh)	Broadens the `data` on the full `mesh` using the straightforward scheme.
`data_class`
`get_characteristics`(points)	Returns the characteristics of a Trapezoid function for each value of energy transfer given by `points`.
`get_kernel`(points, mesh)	Computes the Trapezoid kernel centered on zero on the provided `mesh` at each value of `points` (energy transfer or momentum scalar).
`get_peak`(points, mesh)	Apply the kernel at the nearest `mesh` point for at each value of `points` energy transfer.

Warning

This model is for testing purposes - it does not do any computation and instead uses the user-provided width for all values of [w, Q]. It should not be normally used to model instruments.

data_class: alias of ModelData

get_characteristics(points: Float[np.ndarray, 'sample dimension=1']) → dict[str, Float[np.ndarray, ' sample']]

Returns the characteristics of a Trapezoid function for each value of energy transfer given by points.

This model is a static test model, so it returns the same characteristics for each value of points. A Trapezoid model has two characteristics:

long_base - the length of the longer (bottom) base of a trapezoid
short_base - the length of the shorter (top) base of a trapezoid.

Parameters:

points: The energy transfer in meV at which to compute the width in sigma of the kernel. This must be a sample x 1 2D array where sample is the number of energy transfers.

Returns:

characteristics: The characteristics of the broadening function.

get_kernel(points: Float[np.ndarray, 'sample dimension=1'], mesh: Float[np.ndarray, ' mesh']) → Float[np.ndarray, 'sample mesh']

Computes the Trapezoid kernel centered on zero on the provided mesh at each value of points (energy transfer or momentum scalar).

Note that shape and area are only exactly correct when base lengths correspond to an even number of bin widths.

Parameters:

points: The energy transfer or momentum scalar for which to compute the kernel. This must be a Nx1 2D array where N is the number of w/Q values.
mesh: The mesh on which to evaluate the kernel. A 1D array.

Returns:

kernel: The Trapezoid kernel at each value of points as given by this model, computed on the mesh and centered on zero. This is a 2D N x M array where N is the number of w/Q values and M is the length of the mesh array.

class resins.models.ideal.GenericTriangle1DModel(model_data: ModelData, fwhm: float = 1.0, **_)

Bases: SimpleBroaden1DMixin, StaticSnappedPeaksMixin, InstrumentModel

A generic Triangle model.

Models the resolution as an isosceles Triangle function.

Note that shape and area are only exactly correct when FHWM equals an integer number of bins.

Parameters:

model_data: The data associated with the model for a given version of a given instrument.
fwhm: The width (in Full-Width Half-Maximum) of the Triangle function. This width is used for all values of [w, Q].

Attributes:

input: The names of the columns in the points array expected by all computation methods, i.e. the names of the independent variables ([Q, w]) that the model models.
data_class: Abstract base class for defining the data required by a model.
fwhm: The width (in Full-Width Half-Maximum) of the Triangle function. This width is used for all values of [w, Q].
citation: The citation for this model.

Methods

`__call__`(points, data, *meshes)	Broadens the `data` on the `meshes`.
`broaden`(points, data, mesh)	Broadens the `data` on the full `mesh` using the straightforward scheme.
`data_class`
`get_characteristics`(points)	Returns the broadening width at each value of energy transfer given by `points`.
`get_kernel`(points, mesh)	Computes the Triangle kernel centered on zero on the provided `mesh` at each value of `points` (energy transfer or momentum scalar).
`get_peak`(points, mesh)	Apply the kernel at the nearest `mesh` point for at each value of `points` energy transfer.

Warning

This model is for testing purposes - it does not do any computation and instead uses the user-provided width for all values of [w, Q]. It should not be normally used to model instruments.

data_class: alias of ModelData

get_characteristics(points: Float[np.ndarray, 'sample dimension=1']) → dict[str, Float[np.ndarray, ' sample']]

Returns the broadening width at each value of energy transfer given by points.

This model is a static test model, so it returns the same width for each value of points, which is in the form of the Full-Width Half-Maximum of a Triangle model.

Parameters:

points: The energy transfer in meV at which to compute the width in sigma of the kernel. This must be a sample x 1 2D array where sample is the number of energy transfers.

Returns:

characteristics: The characteristics of the broadening function, i.e. the Triangle width as FWHM.

get_kernel(points: Float[np.ndarray, 'sample dimension=1'], mesh: Float[np.ndarray, ' mesh']) → Float[np.ndarray, 'sample mesh']

Computes the Triangle kernel centered on zero on the provided mesh at each value of points (energy transfer or momentum scalar).

Note that shape and area are only exactly correct when FHWM equals an integer number of bins.

Parameters:

points: The energy transfer or momentum scalar for which to compute the kernel. This must be a Nx1 2D array where N is the number of w/Q values.
mesh: The mesh on which to evaluate the kernel. A 1D array.

Returns:

kernel: The Triangle kernel at each value of points as given by this model, computed on the mesh and centered on zero. This is a 2D N x M array where N is the number of w/Q values and M is the length of the mesh array.

class resins.models.ideal.StaticSnappedPeaksMixin

Bases: object

Mixin providing a get_peak() by copying kernel to nearest bins

This results in ‘snapping’ to the nearest bin rather than a more accurate evaluation at the true point position. However it also eliminates surprising changes to the kernel shape based on the sub-bin position, and gives similar results to convolution with pre-binned data.

get_kernel() must be provided by the inheriting class or another Mixin.

Methods

get_peak(points, mesh)

Apply the kernel at the nearest mesh point for at each value of points energy transfer.

get_peak(points: Float[np.ndarray, 'sample dimension=1'], mesh: Float[np.ndarray, ' mesh']) → Float[np.ndarray, 'sample mesh']

Apply the kernel at the nearest mesh point for at each value of points energy transfer.

The kernel is obtained by calling get_kernel() for the first item of points: this is intended for use with energy-independent (“static”) broadening functions.

Note that peak positions are quantized to the nearest mesh point. As a result, the position of peaks in this approach does not vary smoothly with the input parameters.

Parameters:

points: The energy transfer in meV for which to compute the kernel. This must be a Nx1 2D array where N is the number of energy transfers.
mesh: The mesh on which to evaluate the kernel. This is a 1D array which must span the points transfer space of interest.

Returns:

peaks: Broadening kernel aligned to nearest mesh point for each input point. This is a 2D N x M array where N is the length of points (i.e. number of ω values) and M is the length of the mesh array.