Functions

Functions¶

The top-level component functions describes an array of mathematical functions in struct format to be used as helper objects. Similar to distributions each entry is required to have the components type and name. Other components are dependent on the kind of functions. The field name is required and may be any custom unique string. Functions in general have the following components:

name: custom unique string
type: string that determines the kind of function, e.g. sum
...: each function has individual parameter keys for the various individual parameters. For example, functions of type sum have the parameter key summands. In general, these keys can describe strings as references to other objects or numbers. Depending on the parameter and the type of function, they appear either in single item or array format.

Example: Functions

"functions": [ 
    { 
        "name" : "sum1", 
        "type" : "sum", 
        "summands" : [1.8, 4, "param_xy"] 
    }, 
    ... 
]

In the following the implemented functions are described in detail.

Product¶

A product of values or functions \(a_i\).

\[ \begin{aligned} \text{Prod} &= \prod_i^n a_i \end{aligned} \]

name: custom unique string
type: product
factors: array of names of the elements of the product or numbers.

Sum¶

A sum of values or functions \(a_i\).

\[ \begin{aligned} \text{Sum} &= \sum_i^n a_i \end{aligned} \]

name: custom unique string
type: sum
summands: array of names of the elements of the sum or numbers.

Polynomial Function¶

The polynomial function is defined as

\[ \begin{aligned} \text{Polynomial}(x, a_0, a_1,\ldots,a_n) = \sum_{i=0}^{n} a_i x^i . \end{aligned} \]

Unlike polynomial_dist, this object is a function and is not normalized.

name: custom unique string
type: polynomial
x: name of the variable \(x\)
coefficients: array of coefficients \(a_i\). The length of this array implies the degree of the polynomial.

Derivative Function¶

The derivative function represents a numerical derivative of another function with respect to a variable:

\[ \begin{aligned} \text{Derivative}(f,x,n) = \frac{d^n f}{dx^n}. \end{aligned} \]

The order is intended for first, second, or third derivatives, and eps controls the finite-difference step size.

name: custom unique string
type: derivative
function: name of the function \(f\)
x: name of the differentiation variable \(x\)
order: derivative order \(n\)
eps: step size used for the numerical derivative
normalization: array of names defining the normalization set (optional)

Gaussian Resolution Model¶

The Gaussian resolution model represents a Gaussian smearing model in the convolution variable \(x\):

\[ \begin{aligned} \text{GaussModel}(x,\mu,\sigma) = \frac{1}{\sigma\sqrt{2\pi}}\exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right). \end{aligned} \]

It can be used as a resolution model for analytical convolutions.

name: custom unique string
type: gauss_model_function
x: name of the convolution variable \(x\)
mean: value or name of the mean parameter \(\mu\)
sigma: value or name of the width parameter \(\sigma\)

Truth Resolution Model¶

The truth resolution model corresponds to perfect resolution, represented by a delta function in the convolution variable:

\[ \begin{aligned} \text{TruthModel}(x) = \delta(x). \end{aligned} \]

When used in an analytical convolution, it returns the unconvolved basis function.

name: custom unique string
type: truth_model_function
x: name of the convolution variable \(x\)

Generic Function¶

Note: Users should prefer the specific functions defined in this standard over generic functions where possible, as implementations of these will typically be more optimized. Generic functions should only be used if no equivalent specific distribution is defined. A generic function is defined by an expression. The expression must be a valid HS³-expression string (see Section Generic Expressions).

name: custom unique string
type: generic_function
expression: a string with a generic mathematical expression. Simple mathematical syntax common to programming languages should be used here, such as x-2*y+z. For any non-elementary operations, the behavior is undefined.