MultiPDF

class minkit.MultiPDF(name, pdfs, arg_pars=None)[source]

Bases: minkit.PDF

Base class owing many PDFs.

Parameters:

Attributes Summary

all_args All the argument parameters associated to this class.
all_pars All the parameters associated to this class.
all_pdfs Recursively get all the possible PDFs belonging to this object.
all_real_args All the argument parameters that are not ParameterFormula instances.
aop Object to do operations on arrays.
args Argument parameters this object directly depends on.
backend Backend interface.
cache Return the cached values for this PDF.
cache_type Cache type being used.
constant Whether this is a constant PDF.
data_pars Data parameters this object directly depends on.
dependencies Registry of PDFs this instance depends on.
pdfs Get the registry of PDFs within this class.
real_args Arguments that do not depend on other arguments.

Methods Summary

__call__(data[, range, normalized]) Call the PDF in the given set of data.
bind([range, normalized]) Prepare an object that will be called many times with the same set of values.
component(name) Get the PDF object with the given name.
copy([backend]) Create a copy of this PDF.
evaluate_binned(data[, normalized]) Evaluate the PDF over a binned sample.
from_json_object(obj, pars, pdfs) Build a PDF from a JSON object.
generate([size, mapsize, gensize, range, …]) Generate random data.
get_values() Get the values of the parameters within this object.
integral([integral_range, range]) Calculate the integral of a PDF.
max([range, normalized, tol, min_points, …]) Calculate the maximum value of the PDF in the given range.
norm([range]) Calculate the normalization of the PDF.
numerical_integral([integral_range, range]) Calculate the integral of a PDF.
numerical_normalization([range]) Calculate a numerical normalization.
restoring_state() Enter a context where the attributes of the parameters will be restored on exit.
set_values(**kwargs) Set the values of the parameters associated to this PDF.
to_backend(backend) Initialize this class in a different backend.
to_json_object() Dump the PDF information into a JSON object.
using_cache(ctype) Safe method to enable a cache of the PDF.

Attributes Documentation

all_args

All the argument parameters associated to this class.

Type:Registry(Parameter)
all_pars

All the parameters associated to this class. This includes also any ParameterFormula and the data parameters.

Type:Registry(Parameter)
all_pdfs

Recursively get all the possible PDFs belonging to this object.

all_real_args

All the argument parameters that are not ParameterFormula instances.

Type:Registry(Parameter)
aop

Object to do operations on arrays.

Type:ArrayOperations
args

Argument parameters this object directly depends on.

Type:Registry(Parameter)
backend

Backend interface.

Type:Backend
cache

Return the cached values for this PDF.

Type:dict
cache_type

Cache type being used.

Type:str or None
constant

Whether this is a constant PDF.

Type:bool
data_pars

Data parameters this object directly depends on.

Type:Registry(Parameter)
dependencies

Registry of PDFs this instance depends on.

Type:Registry(PDF)
pdfs

Get the registry of PDFs within this class.

Returns:PDFs owned by this class.
Return type:Registry(PDF)
real_args

Arguments that do not depend on other arguments.

Type:Registry(Parameter)

Methods Documentation

__call__(data, range='full', normalized=True)

Call the PDF in the given set of data.

Parameters:
  • data (DataSet or BinnedDataSet) – data to evaluate.
  • range (str) – normalization range.
  • normalized (bool) – whether to return a normalized output.
Returns:

Evaluation of the PDF.
Return type:

darray
bind(range='full', normalized=True)

Prepare an object that will be called many times with the same set of values. This is usefull for PDFs using a cache, to avoid creating it many times in successive calls to PDF.__call__().

Parameters:
  • range (str) – normalization range.
  • normalized (bool) – whether to return a normalized output.
component(name)[source]

Get the PDF object with the given name.

Parameters:name (str) – name of the PDF.
Returns:Component with the given name.
Return type:PDF
copy(backend=None)

Create a copy of this PDF.

Parameters:backend (Backend or None) – new backend.
Returns:A copy of this PDF.
evaluate_binned(data, normalized=True)

Evaluate the PDF over a binned sample.

Parameters:
  • data (BinnedDataSet) – input data.
  • normalized (bool) – whether to normalize the output array or not.
Returns:

Values from the evaluation.
Return type:

farray
classmethod from_json_object(obj, pars, pdfs)[source]

Build a PDF from a JSON object. This object must represent the internal structure of the PDF.

Parameters:
  • obj (dict) – JSON object.
  • pars (Registry) – parameter to build the PDF.
  • backend (Backend) – backend to build the PDF.
Returns:

This type of PDF constructed together with its parameters.

See also

PDF.to_json_object()

generate(size=10000, mapsize=1000, gensize=None, range='full', max_opts=None)

Generate random data. A call to PDF.bind() is implicit, since several calls will be done to the PDF with the same set of values.

Parameters:
  • size (int) – size (or minimum size) of the output sample.
  • mapsize (int) – number of points to consider per dimension (data parameter) in order to calculate the maximum value of the PDF.
  • gensize (int or None) – number of entries to generate per iteration. By default it is set to \(10^4\) and \(10^5\) for CPU and GPU backends, respectively.
  • max_opts (dict or None) – keyword arguments to be passed to the PDF.max() function. Allowed arguments are shown below.
  • range (str) – range of the data parameters where to generate data.
Returns:

Output sample.
Return type:

DataSet

Arguments that can be passed in max_opts are:

  • tol: relative tolerance allowed for the determination of the maximum.
  • max_call: maximum number of iterations allowed.
  • sampling_size: size of the samples used to calculate the maximum.

See also

PDF.max()

get_values()

Get the values of the parameters within this object.

Returns:Dictionary with the values of the parameters.
Return type:dict(str, float)
integral(integral_range='full', range='full')

Calculate the integral of a PDF.

Parameters:
  • integral_range (str) – range of the integral to compute.
  • range (str) – normalization range to consider.
Returns:

Integral of the PDF in the range defined by “integral_range” normalized to “range”.
Return type:

float
max(range='full', normalized=True, tol=1e-07, min_points=4, max_call=None, sampling_size=None)

Calculate the maximum value of the PDF in the given range.

Parameters:
  • range (str) – range to consider.
  • normalized (bool) – if set to True, the result corresponds to the maximum of the normalized PDF.
  • sampling_size (int) – size of the samples to use to determine the maximum.
  • tol (float) – relative dispersion that is allowed for convergence.
  • min_points (int) – minimum number of points to estimate the maximum. It must be greater than four.
  • max_call (int) – maximum number of iterations to perform. Must be greater than two.
  • sampling_size – number of elements to generate in each call.
Returns:

Maximum value.
Return type:

float

The maximum is calculated from successive random samples of size equal to sampling_size. Afterwards, a fit is done in order to polish the minimum. Once the minimization was done at least min_points times, a final fit to the function

\[f(n) = \alpha e^{-\beta n} + \delta\]

is done, where n is the iteration number and \(f(n)\) is the global maximum in that iteration. The value of \(\delta\) is returned as long as the error satisfies the given tolerance. To improve the performance, only the iterations where the achieved maximum is within the tolerance with respect to the global maximum are considered. The parameter \(\delta\) is minimized in such a way that it is always greater or equal to the global maximum achieved from the random samples.

Note

For two-dimensional PDFs, the process of calculating the maximum can turn really slow, so you might want to consider reducing the precision of the maximum value.

norm(range='full')

Calculate the normalization of the PDF.

Parameters:range (str) – normalization range to consider.
Returns:Value of the normalization.
Return type:float
numerical_integral(integral_range='full', range='full')

Calculate the integral of a PDF.

Parameters:
  • integral_range (str) – range of the integral to compute.
  • range (str) – normalization range to consider.
Returns:

Integral of the PDF in the range defined by “integral_range” normalized to “range”.
Return type:

float
numerical_normalization(range='full')

Calculate a numerical normalization.

Parameters:range (str) – normalization range.
Returns:Normalization.
Return type:float
restoring_state()

Enter a context where the attributes of the parameters will be restored on exit.

set_values(**kwargs)

Set the values of the parameters associated to this PDF.

Parameters:kwargs (dict(str, float)) – keyword arguments with “name”/”value”.

Note

Parameters of this PDF might be shared with others.

to_backend(backend)

Initialize this class in a different backend.

Parameters:backend (Backend) – new backend.
Returns:An instance of this class in the new backend.
to_json_object()

Dump the PDF information into a JSON object. The PDF can be constructed at any time by calling PDF.from_json_object().

Returns:Object that can be saved into a JSON file.
Return type:dict

See also

PDF.from_json_object()

using_cache(ctype)

Safe method to enable a cache of the PDF. There are two types of cache:

  • const: evaluation with a fixed constant state. It means that we plan to call the PDF consecutively in the same data set, but the value of the parameters that are not constant is allowed to change. This means that any PDF that has all its arguments as constant is assumed to have the same value in each evaluation.
  • bind: evaluation with the same parameter values and bounds. This is reserved for those processes where the normalization range will be the same, as well as the values of the parameters of the PDF. However, the function can be called in different data sets.
Parameters:ctype (str) – cache type.

Warning

It is responsibility of the user to ensure that the conditions for the cache to be valid are preserved.