yadism.esf package

Submodules

yadism.esf.conv module

Defines DistributionVec and its API, that are used to represent distribution objects in the coefficient function definition and calculation.

yadism.esf.conv.convolution(rsl, x, pdf_func)

Convolve a yadism.coefficient_functions.partonic_channel.RSL instance with a function pdf_func.

The definition of the convolution performed is:

\[\int_x^{1} \frac{\text{d}z}{z} dvec(z) f\left(\frac{x}{z}\right)\]

(notice that is symmetryc in \(dvec \leftrightarrow f\)).

Note

The module level attributes eps_integration_abs and eps_integration_border regulate the integration process, setting respectively the absolute error and restricting the integration domain in order to avoid singularities.

Parameters:

• rsl (yadism.coefficient_functions.partonic_channel.RSL) – an object representing a distribution

• x (scalar) – the kinematics point at which the convoution is evaluated

• pdf_func (callable) – the function to be convolved with rsl (usually a PDF, or a PDF interpolator)

Returns:

• float – the result of the convolution

• float – the integration error

Note

The real name of this function is convnd.

yadism.esf.conv.convolve_operator(fnc, interpolator)

Convolve function over all basis functions over all grid points.

Parameters:

• fnc (RSL) – integration kernel

• interpolator (InterpolationDispatcher) – basis functions

Returns:

• ls (np.ndarray) – values

• els (np.ndarray) – errors

yadism.esf.conv.convolve_vector(cf, interpolator, convolution_point)

Convolve function over all basis functions.

Parameters:

• cf (RSL) – integration kernel

• interpolator (InterpolationDispatcher) – basis functions

• convolution_point (float) – convolution point

Returns:

• ls (np.ndarray) – values

• els (np.ndarray) – errors

yadism.esf.conv.eps_integration_abs = 1e-13

Set the integration target absolute error, see Integration Note

yadism.esf.conv.eps_integration_border = 1e-10

Set the integration domain restriction, see Integration Note

yadism.esf.conv.quad_ker_reg(z, x, is_log, areas, reg, reg_args)

yadism.esf.conv.quad_ker_reg_sing(z, x, is_log, areas, reg, reg_args, sing, pdf_at_x, sing_args)

yadism.esf.conv.quad_ker_sing(z, x, is_log, areas, sing, pdf_at_x, sing_args)

yadism.esf.esf module

This module provides the base class that define the interface for Structure Function calculation on a given kinematic point (x, Q2) (that is why they are called Evaluated).

class yadism.esf.esf.ESFInfo(obs_name, configs)

Bases: object

__getattribute__(name)

Return getattr(self, name).

class yadism.esf.esf.EvaluatedStructureFunction(kinematics: dict, obs_name, configs)

Bases: object

A specific kinematic point for a specific structure function.

This class implements the structure for all the coefficient functions’ providers, for a single kinematic point (x, Q2), but all the flavours (singlet, nonsinglet, valence, gluon).

Since the coefficient functions in general are distributions they are provided with an internal representation, that respects the interface defined by the class conv.DistributionVec, and the same class is used to perform the convolution with the basis functions (see eko.InterpolatorDispatcher), so the final result will consist of an array of dimension 2: one dimension corresponding to the interpolation grid, the other to the flavour.

Cache

A part of the overall caching system is implemented at this level.

The one implemented here is only a local, isolated caching, i.e.:

• the first time the instance is asked for computing the result, through the get_result() method, it registers the result;

• any following call to the get_result() method will make use of the cached result, and will never recompute it.

If another instance with the same attributes is asked for the result it will recompute it from scratch, because any instance is isolated and doesn’t keep any reference to the others.

Parameters:

• SF (StructureFunction) – the parent StructureFunction instance, provides an interface, holds references to global objects (like managers coming from eko, e.g. InterpolatorDispatcher) and implements the global caching

• kinematics (dict) – the specific kinematic point as a dict with two elements (‘x’, ‘Q2’)

__repr__()

Return repr(self).

compute_local()

Here is where the local caching is actually implemented: if the coefficient functions are already computed don’t do anything, otherwise call _compute_component() (checks are per flavour).

In any case no output is provided, but the result is stored in instance’s attributes (this method is for internal use).

get_result()

Compute actual result

Returns:

res – result

Return type:

ESFResult

property zeros

yadism.esf.exs module

class yadism.esf.exs.EvaluatedCrossSection(kin, obs_name, configs, get_esf)

Bases: object

alpha_qed_power()

get_result()

yadism.esf.exs.GEV_CM2_CONV = 38937930000.0

Conversion factor from GeV^-2 to 10^-38 cm^2

yadism.esf.exs.xs_coeffs_polarized(kind)

Compute coefficients in the definition of a given polarized cross section.

Parameters:

kind (str) – the identifier of the cross section for which coefficients have to be computed

Returns:

the coefficients of the cross-section on the basis (g4, gL, 2xg1)

Return type:

np.ndarray

yadism.esf.exs.xs_coeffs_unpolarized(kind, y, x=None, Q2=None, params=None)

Compute coefficients in the definition of a given unpolarized cross section.

Parameters:

• kind (str) – the identifier of the cross section for which coefficients have to be computed

• y (float) – Bjorken y value for the chosen kinematic point

• x (None or float) – Bjorken x value for the chosen kinematic point

• Q2 (None or float) – photon virtuality for the chosen kinematic point

• params (None or dict) – theory parameters required to fully specify the coefficients (which ones depends on the chosen definition, i.e. on kind)

Returns:

the coefficients of the cross-section on the basis (F2, FL, xF3)

Return type:

np.ndarray

Raises:

ValueError or KeyError – in case not enough parameters have been specified

yadism.esf.result module

class yadism.esf.result.ESFResult(x, Q2, nf, orders=None)

Bases: object

Represents the output tensor for a single kinematic point

Parameters:

• x (float) – Bjorken x

• Q2 (float) – virtuality of the exchanged boson

__add__(other)

__mul__(other)

__neg__()

__rmul__(other)

__sub__(other)

apply_pdf(lhapdf_like, pids, xgrid, alpha_s, alpha_qed, xiR, xiF)

Compute the observable for the given PDF.

Parameters:

• lhapdf_like (object) – object that provides an xfxQ2 callable (as lhapdf and ekomark.toyLH.toyPDF do) (and thus is in flavor basis)

• pids (list(int)) – list of pids

• xgrid (list(float)) – interpolation grid

• xiF (float) – factorization scale ration \(\mu_F^2 = Q^2 \xi_F^2\) - beware the square!

Returns:

res – output dictionary with x, Q2, result and error

Return type:

dict

classmethod from_document(raw)

Recover element from a raw dictionary

Parameters:

raw (dict) – raw dictionary

Returns:

new_output – object representation

Return type:

cls

get_raw()

Returns the raw data ready for serialization.

Returns:

out – output dictionary

Return type:

dict

class yadism.esf.result.EXSResult(x, Q2, y, nf, orders=None)

Bases: ESFResult

__annotations__ = {}

apply_pdf(*args)

Compute the observable for the given PDF.

Parameters:

• lhapdf_like (object) –

  object that provides an xfxQ2 callable (as lhapdf and ekomark.toyLH.toyPDF do) (and thus is in flavor basis)

• pids (list(int)) – list of pids

• xgrid (list(float)) – interpolation grid

• xiF (float) – factorization scale ration \(\mu_F^2 = Q^2 \xi_F^2\) - beware the square!

Returns:

res – output dictionary with x, Q2, result and error

Return type:

dict

classmethod from_document(raw)

Recover element from a raw dictionary

Parameters:

raw (dict) – raw dictionary

Returns:

new_output – object representation

Return type:

cls

get_raw()

Returns the raw data ready for serialization.

Returns:

out – output dictionary

Return type:

dict

yadism.esf.scale_variations module

Implementation of factorization and renormalization scale variations.

class yadism.esf.scale_variations.ScaleVariations(order, interpolator, activate_ren, activate_fact)

Bases: object

Manager for scale variations.

apply_common_scale_variations(ker_orders, nf)

Add new kernels for common scale varied coefficient functions.

Parameters:

• ker_orders (list) – raw (unscale-varied) coefficient functions

• nf (int) – number of active flavors

Returns:

kernels map

Return type:

list

apply_diff_scale_variations(ker_orders, nf)

Add new kernels for different scale varied coefficient functions.

Parameters:

• ker_orders (list) – common-scale varied coefficient functions

• nf (int) – number of active flavors

Returns:

kernels map

Return type:

Iterable

apply_raw_diff_scale_variations(ker_orders, nf)

Add new kernels for different scale varied coefficient functions.

Parameters:

• ker_orders (list) – common-scale varied coefficient functions

• nf (int) – number of active flavors

Returns:

kernels map

Return type:

list

compute_raw(nf)

Compute all basic building blocks.

Parameters:

nf (int) – number of active flavors

fact_matrices(nf)

Compute all matrices related to factorization scale variation, i.e. \(\ln(Q^2/\mu_F^2)\).

Parameters:

nf (int) – number of active flavors

Returns:

map with (target, lnf, src) -> np.ndarray

Return type:

dict

ren_coeffs(nf)

Provide the renormalization scale variation coefficients, i.e. \(\ln(\mu_F^2/\mu_R^2)\).

Parameters:

nf (int) – number of active flavors

Returns:

map with (target, lnf2r, src) -> np.ndarray

Return type:

dict

yadism.esf.scale_variations.build_orders(order)

Compute all necessary order configurations for a given power of alpha.

Parameters:

order (int) – order in pQCD

Returns:

orders – order configurations

Return type:

list(tuple)

yadism.esf.tmc module

This module contain the implementation of target mass corrections (TMC) for both the unpolarized and polarized structure functions.

Three classes are here defined:

• EvaluatedStructureFunctionTMC is the abstract class defining the machinery for TMC calculation

• ESFTMC_F2, ESFTMC_FL, and ESFTMC_F3 implements the previous one, making use of its machinery as building blocks for the actual expressions for TMC

• ESFTMC_g1, ESFTMC_g4, and ESFTMC_gL refer to spin-dependent counterparts.

The structures presented play together the role of an intermediate block between the StructureFunction interface (used to manage user request for DIS observables) the actual calculator EvaluatedStructureFunction, or even better they can be seen as a replacement for the latter, that makes use of that one under the hood.

Indeed TMC corrected structure functions are defined on top of the “bare” ones, and one of their main features is that their expression is a functione of the “bare” themselves, but evaluated to a shifted kinematics (w.r.t. to the one asked by the user, that is the physical kinematic point at which one would like to evaluate the physical structure function).

class yadism.esf.tmc.ESFTMC_F2(SF, kinematics)

Bases: EvaluatedStructureFunctionTMC

This function implements the actual formula for target mass corrections of F2, for all the three kinds described in the parent class EvaluatedStructureFunctionTMC.

Parameters:

• SF (StructureFunction) – the interface object representing the structure function kind he belongs to

• kinematics (dict) – requested kinematic point

__annotations__ = {}

_abc_impl = <_abc._abc_data object>

_get_result_APFEL()

This method is defined by subclasses to provide the implementation of TMC calculation according to the same formula used by APFEL, see [BDDF+09]

Todo

• APFEL TMC reference missing

_get_result_approx()

This method is defined by subclasses to provide the implementation of TMC calculation according to the approximate formula defined in 4 in [GR20], and already presented in [S+08].

The convenience of this formula is that the integration is approximate by a simple evaluation of the integrand in a suitable point, so the evaluation of the full expression is much faster (because integration yields an array of evaluations, ranging from 1 to the xgrid length). Despite the approximation the formula is quite in a good agreement with the exact one (for comparison see [S+08]).

_get_result_exact()

This method is defined by subclasses to provide the implementation of TMC calculation according to the exact formula defined in 2 in [GR20], and already presented in [S+08] and older literature like [GP76].

Note

This method will always involve an integration (and more than one according to the structure function). If this is to expensive check _get_result_approx().

class yadism.esf.tmc.ESFTMC_F3(SF, kinematics)

Bases: EvaluatedStructureFunctionTMC

This function implements the actual formula for target mass corrections of F3, for all the three kinds described in the parent class EvaluatedStructureFunctionTMC.

Parameters:

• SF (StructureFunction) – the interface object representing the structure function kind he belongs to

• kinematics (dict) – requested kinematic point

__annotations__ = {}

_abc_impl = <_abc._abc_data object>

_get_result_APFEL()

This method is defined by subclasses to provide the implementation of TMC calculation according to the same formula used by APFEL, see [BDDF+09]

Todo

• APFEL TMC reference missing

_get_result_approx()

This method is defined by subclasses to provide the implementation of TMC calculation according to the approximate formula defined in 4 in [GR20], and already presented in [S+08].

The convenience of this formula is that the integration is approximate by a simple evaluation of the integrand in a suitable point, so the evaluation of the full expression is much faster (because integration yields an array of evaluations, ranging from 1 to the xgrid length). Despite the approximation the formula is quite in a good agreement with the exact one (for comparison see [S+08]).

_get_result_exact()

This method is defined by subclasses to provide the implementation of TMC calculation according to the exact formula defined in 2 in [GR20], and already presented in [S+08] and older literature like [GP76].

Note

This method will always involve an integration (and more than one according to the structure function). If this is to expensive check _get_result_approx().

_h3()

Compute raw integral over F3, making use of _convolve_FX().

\begin{align*} h_3(\xi,Q^2) &= \int_\xi^1 du \frac{F_3(u,Q^2)}{u}\\ &= \int_\xi^1 \frac{du}{u} F_3(u,Q^2)\\ &= ((z\to 1) \otimes F_3(z))(\xi) \end{align*}

Returns:

h3 – ESF output for the integral

Return type:

dict

class yadism.esf.tmc.ESFTMC_FL(SF, kinematics)

Bases: EvaluatedStructureFunctionTMC

This function implements the actual formula for target mass corrections of FL, for all the three kinds described in the parent class EvaluatedStructureFunctionTMC.

Parameters:

• SF (StructureFunction) – the interface object representing the structure function kind he belongs to

• kinematics (dict) – requested kinematic point

__annotations__ = {}

_abc_impl = <_abc._abc_data object>

_get_result_APFEL()

This method is defined by subclasses to provide the implementation of TMC calculation according to the same formula used by APFEL, see [BDDF+09]

Todo

• APFEL TMC reference missing

_get_result_approx()

This method is defined by subclasses to provide the implementation of TMC calculation according to the approximate formula defined in 4 in [GR20], and already presented in [S+08].

The convenience of this formula is that the integration is approximate by a simple evaluation of the integrand in a suitable point, so the evaluation of the full expression is much faster (because integration yields an array of evaluations, ranging from 1 to the xgrid length). Despite the approximation the formula is quite in a good agreement with the exact one (for comparison see [S+08]).

_get_result_exact()

This method is defined by subclasses to provide the implementation of TMC calculation according to the exact formula defined in 2 in [GR20], and already presented in [S+08] and older literature like [GP76].

Note

This method will always involve an integration (and more than one according to the structure function). If this is to expensive check _get_result_approx().

class yadism.esf.tmc.ESFTMC_g1(SF, kinematics)

Bases: EvaluatedStructureFunctionTMC

This function implements the actual formula for target mass corrections for parity conserving polarized structure function g1, for the two kinds described in the parent class EvaluatedStructureFunctionTMC.

The formula in question can be found in D.26 of [AM08], D.10 of [KMAT17], and references therein.

Parameters:

• SF (StructureFunction) – the interface object representing the structure function kind he belongs to

• kinematics (dict) – requested kinematic point

__annotations__ = {}

_abc_impl = <_abc._abc_data object>

_get_result_APFEL()

This method is defined by subclasses to provide the implementation of TMC calculation according to the same formula used by APFEL, see [BDDF+09]

Todo

• APFEL TMC reference missing

_get_result_approx()

This method is defined by subclasses to provide the implementation of TMC calculation according to the approximate formula defined in 4 in [GR20], and already presented in [S+08].

The convenience of this formula is that the integration is approximate by a simple evaluation of the integrand in a suitable point, so the evaluation of the full expression is much faster (because integration yields an array of evaluations, ranging from 1 to the xgrid length). Despite the approximation the formula is quite in a good agreement with the exact one (for comparison see [S+08]).

_get_result_exact()

This method is defined by subclasses to provide the implementation of TMC calculation according to the exact formula defined in 2 in [GR20], and already presented in [S+08] and older literature like [GP76].

Note

This method will always involve an integration (and more than one according to the structure function). If this is to expensive check _get_result_approx().

yadism.esf.tmc.ESFTMCmap = {'F2': <class 'yadism.esf.tmc.ESFTMC_F2'>, 'F3': <class 'yadism.esf.tmc.ESFTMC_F3'>, 'FL': <class 'yadism.esf.tmc.ESFTMC_FL'>, 'g1': <class 'yadism.esf.tmc.ESFTMC_g1'>}

mapping kind to ESF TMC classes

This dictionary is used to redirect to the correct class from a string indicating the kind of the required structure function.

Type:

dict

class yadism.esf.tmc.EvaluatedStructureFunctionTMC(SF, kinematics)

Bases: ABC

This is an abstract class, made to serve the machinery to the inheriting classes. In particular here are defined:

• shifted kinematics \(\xi\) and other aux variables (\(\mu\) and \(\rho\), see [GR20])

• integration layout and two common integrals of structure functions, \(h_2\) and \(g_2\) (see [S+08])

• an interface for picking up the chosen formulas between:

  1. APFEL

  2. approximate

  3. exact

  (see [GR20])

Parameters:

• SF (StructureFunction) – the interface object representing the structure function kind he belongs to

• kinematics (dict) – requested kinematic point

__annotations__ = {}

_abc_impl = <_abc._abc_data object>

_convolve_FX(kind, ker)

Implement generic structure to convolve any function ker with F2.

This method is provided for internal use, in order to factorize the machinery for TMC integrals. The implementation is flavor transparent, in the sense that takes any flavor from up and it’s passing it down in the call for a proper F2 instance (done by using self.sf.get_ESF()).

The integration is made over the interpolation basis, postponing the once more the the contraction with the PDF.

\begin{align*} \tilde{F}_X \otimes f &= \sum_i (\tilde{F}_X \otimes w_i) f_i = \left[ a + \sum_{i} ((F_X \otimes k) \otimes w_i) \right] f_i \\ & = \left[ a + \sum_{i,j} \underbrace{{F_X}_j ((w_j \otimes k)}_{\texttt{_convolve_FX}} \otimes w_i) \right] f_i \end{align*}

where \(\tilde{F}_X\) is the target mass corrected structure function, \(F_X\) is the bare structure function, \(k\) is the kernel function ker, and \(a\) is representing all the other terms not described here.

Parameters:

• kind (str) – observable kind

• ker (callable) – the kernel function to be convolved with structure functions

_g2()

Compute nested integral over F2, making use of _convolve_FX().

\begin{align*} g_2(\xi,Q^2) &= \int_\xi^1 du (u-\xi) \frac{F_2(u,Q^2)}{u^2}\\ &= \int_\xi^1 \frac{du}{u} \left(1 - \frac{\xi}{u}\right) F_2(u,Q^2)\\ &= ((z\to 1-z) \otimes F_2(z))(\xi) \end{align*}

Returns:

g2 – ESF output for the integral

Return type:

dict

abstract _get_result_APFEL()

This method is defined by subclasses to provide the implementation of TMC calculation according to the same formula used by APFEL, see [BDDF+09]

Todo

• APFEL TMC reference missing

abstract _get_result_approx()

This method is defined by subclasses to provide the implementation of TMC calculation according to the approximate formula defined in 4 in [GR20], and already presented in [S+08].

The convenience of this formula is that the integration is approximate by a simple evaluation of the integrand in a suitable point, so the evaluation of the full expression is much faster (because integration yields an array of evaluations, ranging from 1 to the xgrid length). Despite the approximation the formula is quite in a good agreement with the exact one (for comparison see [S+08]).

abstract _get_result_exact()

This method is defined by subclasses to provide the implementation of TMC calculation according to the exact formula defined in 2 in [GR20], and already presented in [S+08] and older literature like [GP76].

Note

This method will always involve an integration (and more than one according to the structure function). If this is to expensive check _get_result_approx().

_h2()

Compute raw integral over F2, making use of _convolve_FX().

\begin{align*} h_2(\xi,Q^2) &= \int_\xi^1 du \frac{F_2(u,Q^2)}{u^2}\\ &= \int_\xi^1 \frac{du}{u} \frac{1}{\xi} \frac{\xi}{u} F_2(u,Q^2)\\ &= ((z\to z/\xi) \otimes F_2(z))(\xi) \end{align*}

Returns:

h2 – ESF output for the integral

Return type:

dict

_k1()

Compute the raw integral that enters the computation of g.

The form of the integrall is exactly the same as for h2.

Returns:

k1 – ESF output for the integral

Return type:

dict

_k2()

Compute the raw integral that enters the computation of g making use of _convolve_FX().

\begin{align*} k_2(\xi,Q^2) &= \int_\xi^1 du \log(\frac{u}{\xi}) \frac{g_1(u,Q^2)}{u^2}\\ &= - \int_\xi^1 du \log(\frac{\xi}{u}) \frac{g_1(u,Q^2)}{u^2}\\ &= ((z\to - \frac{z}{\xi} \log(z)) \otimes g_1(z))(\xi) \end{align*}

Returns:

k2 – ESF output for the integral

Return type:

dict

get_result()

This is the interfaces provided to get the evaluation of the TMC corrected structure function.

The kinematics is set to be the requested one, as it should (and not the shifted one used in evaluation of expression terms).

Returns:

out – an object that stores the details and result of the calculation

Return type:

ESFResult

yadism.esf.tmc.g2_ker(z, _args)

yadism.esf.tmc.h2_ker(z, args)

yadism.esf.tmc.h3_ker(_z, _args)

yadism.esf.tmc.k2_ker(z, args)