yadism package

Yet Another DIS Module.

yadism.run_yadism(theory: dict, observables: dict)[source]

Call yadism runner.

Get the theory and observables description and computes the Coefficient Functions for the requested kinematics.

Parameters:

  • theory (dict) – Dictionary containing the theory Parameters

  • observables (dict) – Dictionary containing the DIS parameters such as process description and kinematic specifications

Returns:

run_yadism – output object containing the coefficient functions grids

Return type:

Output

Subpackages

Submodules

yadism.log module

Module controlling the log outputs.

yadism.log.setup(console=None, log_level=20, log_to_stdout=True, log_file=None)[source]

Initialize log outputs.

Parameters:

  • console (rich.console.Console) – rich high level console interface

  • log_level (str) – logging level

  • log_to_stdout (boolean-like) – switch on/off printing on STD output

  • log_file (str-like) – redirect output logs to file

yadism.observable_name module

High level interface to the observable names.

Wrap the name of the observables in order to perform operations on them. For instance, it checks what kind of observable is being dealt with and whether or not the given flavor is heavy.

class yadism.observable_name.ObservableName(name)[source]

Bases: object

Wrapper to observable names to easy split them into two parts.

Parameters:

name (str) – full observable name

__eq__(other)[source]

Test equality of kind and flavor.

__hash__ = None
__repr__()[source]

Return the full representation name.

apply_flavor(flavor)[source]

Create new object with given flavor and our kind.

Parameters:

flavor (str) – new flavor

Returns:

apply_flavor – our kind and new flavor

Return type:

type(self)

apply_flavor_family()[source]

Return name with abstract flavor family name.

Returns:

apply_flavor_family – new ObservableName

Return type:

type(self)

apply_kind(kind)[source]

Create new object with given kind and our flavor.

Parameters:

kind (str) – new kind

Returns:

apply_kind – new kind and our flavor

Return type:

type(self)

property flavor_family

Return abstract flavor family name.

classmethod has_heavies(names)[source]

Check if there are any heavy objects in names.

Parameters:

names (list(str)) – names to check

Returns:

has_heavies – are there heavy obs in names?

Return type:

bool

classmethod has_lights(names)[source]

Check if there are any light objects in names.

Parameters:

names (list(str)) – names to check

Returns:

has_lights – are there light obs in names?

Return type:

bool

property hqnumber

Return Heavy quark flavor number

property is_composed

Check if it is a composed flavor.

i.e. total.

property is_heavy

Check if the given flavor is heavy.

Returns:

is_heavy – is a heavy flavor?

Return type:

bool

property is_heavylight

Check if it is a heavylight flavor.

i.e. charmlight, bottomlight, or, toplight.

property is_parity_violating

Check if it is a parity violating observable.

property is_raw_heavy

Check if it is a raw heavy flavor.

i.e. charm, bottom, or, top.

classmethod is_valid(name)[source]

Test whether the name is a valid observable name.

Returns:

is_valid – is valid name?

Return type:

bool

property mass_label

Add mass label in the theory runcard.

property name

Return joint name.

property raw_flavor

Return underlying raw flavor.

yadism.output module

Output related utilities.

For the main output (that is the computed PDF independent DIS operator) three outputs are provided:

  • tar archive, containing metadata and binary numpy.lib.format arrays (this is the suggested output format)

  • single file yaml output: a single human readable (but possibly huge) file

  • PineAPPL interpolation grid: very useful to store in a standard format (supporting also non-DIS processes) and interfacing to other codes (but no loading is supported from this format)

class yadism.output.MaskedPDF(lhapdf_like, active_pids)[source]

Bases: object

Mask some pids of a PDF set to be 0.

Parameters:

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

  • active_pids (list[int]) – active PIDs

__getattr__(name)[source]
xfxQ2(pid, x, Q2)[source]

Fake lhapdf-like wrapper.

class yadism.output.Output[source]

Bases: dict

Wrapper for the output to help with application to PDFs and dumping to file.

apply_pdf(lhapdf_like)[source]

Compute all observables 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)

Returns:

ret – output dictionary with all structure functions for all x, Q2, result and error

Return type:

PDFOutput

apply_pdf_alphas_alphaqed_xir_xif(lhapdf_like, alpha_s, alpha_qed, xiR, xiF)[source]

Compute all observables 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)

  • alpha_s (callable) – \(\alpha_s(\mu_R)\), the running strong coupling

  • alpha_qed (callable) – \(\alpha(\mu_R)\), the running fine structure constant

  • xiR (float) – ratio renormalization scale to EW boson virtuality (linear!)

  • xiF (float) – ratio factorization scale to EW boson virtuality (linear!)

Returns:

ret – output dictionary with all structure functions for all \(x\), \(Q^2\), result and error

Return type:

PDFOutput

apply_pdf_theory(lhapdf_like, theory)[source]

Compute all observables 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)

  • theory (dict) – theory dictionary

Returns:

ret – output dictionary with all structure functions for all x, Q2, result and error

Return type:

PDFOutput

dump_tar(tarpath, runcards=True)[source]

Serialize output in a tar archive.

This is the favorite native output.

This results in a considerably smaller output file, with respect to the ‘yaml’ serialization, but it looses the readability. In most cases, there is no advantage in having a readable DIS operator, so they are serialized in binary arrays (see numpy.lib.format).

This only supports observables with a uniform order across kinematical point (as they are generated by yadism.runner.Runner), since they are stored in a unique array. They don’t have to be uniform across different observables (since they are stored in different arrays anyhow).

Parameters:

tarpath (str or os.PathLike) – target file path (it has to have the ‘.tar’ extension)

Raises:

AssertionError – If orders are not uniform within a single observable.

dump_yaml(stream=None)[source]

Serialize result as YAML.

Parameters:

stream (None or stream) – if given, dump is written on it

Returns:

dump – result of dump(output, stream), i.e. a string, if no stream is given or Null, if self is written sucessfully to stream

Return type:

any

dump_yaml_to_file(filename)[source]

Write YAML representation to a file.

Parameters:

filename (str or os.PathLike) – target file name

Returns:

ret – result of dump(output, stream), i.e. Null if written sucessfully

Return type:

any

get_raw()[source]

Serialize result as dict.

This maps the original numpy matrices to lists.

Returns:

out – dictionary which will be written on output

Return type:

dict

classmethod load_tar(tarpath)[source]

Deserialize output object from tar.

It loads an Output.dump_tar() generated tar file into an Output object.

Parameters:

tarpath (str or os.PathLike) – target file path (it has to be a ‘tar’ archive)

Returns:

loaded object

Return type:

Output

classmethod load_yaml(stream)[source]

Load YAML representation from stream.

Parameters:

stream (any) – source stream

Returns:

obj – loaded object

Return type:

Output

classmethod load_yaml_from_file(filename)[source]

Load YAML representation from file.

Parameters:

filename (str or os.PathLike) – source file name

Returns:

obj – loaded object

Return type:

Output

observables = None
theory = None
class yadism.output.PDFOutput[source]

Bases: Output

Wrapper for the PDF output to help with dumping to file.

__annotations__ = {}
dump_tables_to_csv(dirname)[source]

Write all tables to separate csv files.

Parameters:

dirname (str) – output directory name

dump_tables_to_file(filename)[source]

Write all tables to file.

Parameters:

filename (str) – output file name

get_raw()[source]

Convert the object into a native Python dictionary.

Returns:

out – raw dictionary

Return type:

dict

classmethod load_yaml(stream)[source]

Load the object from YAML.

Parameters:

stream (any) – source stream

Returns:

obj – loaded object

Return type:

PDFOutput

property tables

Convert data into a mapping structure functions -> pandas.DataFrame.

yadism.runner module

This module contains the main loop for the DIS calculations.

There are two ways of using yadism:

  • Runner: this class provides a runner that get the theory and observables descriptions as input and manage the whole observables’ calculation process

  • run_dis: a function that wraps the construction of a Runner object and calls the proper method to get the requested output

Todo

decide about run_dis and document it properly in module header

class yadism.runner.Runner(theory: dict, observables: dict)[source]

Bases: object

Wrapper to compute a process.

Parameters:

  • theory (dict) – Dictionary with the theory parameters for the evolution (currently including PDFSet and DIS process indication).

  • observables (dict) – DIS parameters: process description, kinematic specification for the requested output.

Notes

For a full description of the content of theory and dis_observables dictionaries read ??.

Todo

  • reference on theory template

  • detailed description of dis_observables entries

banner = Align(<rich.panel.Panel object>, 'center')
drop_cache()[source]

Drop the whole cache for all observables.

This preserves final results, since they are not part of the cache.

get_result()[source]

Compute coefficient functions grid for requested kinematic points.

Returns:

output object, it will store the coefficient functions grid (flavour, interpolation-index) for each requested kinematic point (x, Q2)

Return type:

Output

get_sf(obs_name)[source]

Return associated SF object.

replace_nans_with_0(out)[source]

Replace any NaNs in output with 0.0

The small-x (i.e. large eta) limit is not addressed in LeProHQ because the high energy limit of the polarized case is not known and that is the main purpose of LeProHQ. As a result LeProHQ may return NaNs in the small-x limit, which this function replaces with 0.0.

Note that the value of x where this plays a role is below the experimental regime and thus this does not affect the description of data, but only e.g. the grids used for the FIATLUX photon computation.

class yadism.runner.RunnerConfigs(theory, managers)[source]

Bases: object

Runner Configuration.

__getattribute__(name)[source]

Return getattr(self, name).

yadism.sf module

High-level interface to Structure Function.

Todo

refer to the sf-esf overview

class yadism.sf.StructureFunction(obs_name, runner)[source]

Bases: object

Represent an abstract structure function.

This class acts as an intermediate handler between the Runner exposed to the outside and the EvaluatedStructureFunction which compute the actual observable.

Parameters:
__len__()[source]
__repr__()[source]

Return repr(self).

drop_cache()[source]

Drop temporary cache.

This preserves final results, since they are not part of the cache.

property elements

Collect the computed observables.

get_esf(obs_name, kinematics, *args, use_raw=True, force_local=False)[source]

Return a EvaluatedStructureFunction instance.

This wrappers allows

  • TMC to to access raw computations

  • heavy quark matching schemes to access their light counter parts

It also implements an internal caching system, to speed up the integrals in TMC.

Parameters:

  • obs_name (.observable_name.ObservableName) – structure function name

  • kinematics (dict) – kinematic configuration

  • args (any) – further arguments passed down to the instance

  • use_raw (bool) – eventually use the ESFTMC? (or just the uncorrected one)

Returns:

obj – created object

Return type:

EvaluatedStructureFunction

get_result()[source]

Collect the results from all childrens.

Returns:

output – all children outputs

Return type:

list(ESFResult)

load(kinematic_configs)[source]

Load all kinematic configurations from the run card.

Parameters:

kinematic_configs (list(dict)) – run card input

yadism.version module

Placeholder for versionning.

yadism.xs module

Module that computes a physical observable.

The observable could be structure functions or some linear combination of them.

class yadism.xs.CrossSection(obs_name, runner)[source]

Bases: object

Represents an abstract structure function.

This class acts as an intermediate handler between the Runner exposed to the outside and the EvaluatedStructureFunction which compute the actual observable.

Parameters:
__len__()[source]
__repr__()[source]

Return repr(self).

property elements

Collect the evaluated observable.

get_esf(obs_name, kin)[source]

Get the observable in question for given kinematics.

Parameters:

  • obs_name (str) – name of the observable

  • kin (dict) – contains the kinematic specs

Returns:

observable evaluated on some kinematics

Return type:

get_sf

get_result()[source]

Collect the results from all childrens.

Returns:

output – all children outputs

Return type:

list(ESFResult)

load(kinematic_configs)[source]

Load all kinematic configurations from the run card.

Parameters:

kinematic_configs (list(dict)) – run card input