eko.io package

Input/output interfaces, including (de)serialization.

class eko.io.EKO(recipes: Inventory[Evolution], recipes_matching: Inventory[Matching], parts: Inventory[Evolution], parts_matching: Inventory[Matching], operators: Inventory[Target], metadata: Metadata, access: AccessConfigs)

Bases: object

Operator interface.

This class offers an interface to an abstract operator, between memory and disk.

An actual operator might be arbitrarily huge, and in particular size limitations in memory are far more strict than on disk. Since manually managing, for each application, the burden of off-loading part of the operator might be hard and occasionally not possible (without a clear picture of the internals), the library itself offers this facility.

In particular, the data format on disk has a complete specification, and can hold a full operator independently of the loading procedure. In order to accomplish the former goal, the remaining task of partial loading is done by this class (for the Python library, other implementations are possible and encouraged).

For this reason, a core component of an EKO object is a path, referring to the location on disk of the corresponding operator. Any EKO has an associated path:

• for the computed object, it corresponds to the path where the actual result of the computation is already saved

• for a new object, it is the path at which any result of final or intermediate computation is stored, as soon as it is produced

The computation can be stopped at any time, without the loss of any of the intermediate results.

recipes: Inventory[Evolution]

recipes_matching: Inventory[Matching]

parts: Inventory[Evolution]

parts_matching: Inventory[Matching]

operators: Inventory[Target]

metadata: Metadata

Operator metadata.

access: AccessConfigs

Access related configurations.

property paths: InternalPaths

Accessor for internal paths.

property xgrid: XGrid

Momentum fraction internal grid.

property mu20: float

Provide squared initial scale.

property mu2grid: List[float]

Provide the list of \(Q^2\) as an array.

property evolgrid: List[Tuple[float, int]]

Provide the list of evolution points as an array.

property theory_card

Provide theory card, retrieving from the dump.

property operator_card

Provide operator card, retrieving from the dump.

update()

Write updates to structure for persistency.

assert_permissions(read=True, write=False)

Assert permissions on current operator.

property permissions

Provide permissions information.

load_recipes(recipes: List[Evolution | Matching])

Load recipes in bulk.

operator(ep: Tuple[float, int])

Retrieve an operator and discard it afterwards.

To be used as a contextmanager: the operator is automatically loaded as usual, but on the closing of the context manager it is dropped from memory.

items()

Iterate operators, with minimal load.

Pay attention, this iterator:

• is not a read-only operation from the point of view of the in-memory object (since the final result after iteration is no operator loaded)

• but it is a read-only operation from the point of view of the permanent object on-disk

Yields:

tuple – couples of (q2, operator), loaded immediately before, unloaded immediately after

approx(ep: Tuple[float, int], rtol: float = 1e-06, atol: float = 1e-10) → Tuple[float, int] | None

Look for close enough evolution point in the EKO.

The distance is mostly evaluated along the \(\mu^2\) dimension, while \(n_f\) is considered with a discrete distance: if two points have not the same, they are classified as far.

Raises:

ValueError – if multiple values are found in the neighbourhood

unload()

Fully unload the operators in memory.

deepcopy(path: Path)

Create a deep copy of current instance.

The managed on-disk object is copied as well, to the new path location. If you don’t want to copy the disk, consider using directly:

copy.deepcopy(myeko)

It will perform the exact same operation, without propagating it to the disk counterpart.

Parameters:

path – path to the permanent location of the new object (not the temporary directory)

Returns:

the copy created

Return type:

EKO

classmethod load(path: Path)

Load the EKO from disk information.

Note

No archive path is assigned to the EKO object, setting its EKO.access.path to None. If you want to properly load from an archive, use the read() constructor.

classmethod read(path: Path, extract: bool = True, dest: Path | None = None, readonly: bool = True)

Load an existing EKO.

If the extract attribute is True the EKO is loaded from its archived format. Otherwise, the path is interpreted as the location of an already extracted folder.

classmethod create(path: Path)

Create a new EKO.

classmethod edit(*args, **kwargs)

Read from and write on existing EKO.

Alias of EKO.read(…, readonly=False), see read().

dump(archive: Path | None = None)

Dump the current content to archive.

Parameters:

archive (Path or None) – path to archive, in general you should keep the default, that will make use of the registered path (default: None)

Raises:

ValueError – when trying to dump on default archive in read-only mode

close()

Close the current object, cleaning up.

If not in read-only mode, dump to permanent storage. Remove the temporary directory used.

property raw: dict

Provide raw representation of the full content.

Returns:

nested dictionary, storing all the values in the structure, but the operators themselves

Return type:

dict

class eko.io.Operator(operator: ndarray[Any, dtype[_ScalarType_co]], error: ndarray[Any, dtype[_ScalarType_co]] | None = None)

Bases: object

Operator representation.

To be used to hold the result of a computed 4-dim operator (either a raw evolution operator or a matching condition).

Note

IO works with streams in memory, in order to avoid intermediate write on disk (keep read from and write to tar file only).

operator: ndarray[Any, dtype[_ScalarType_co]]

Content of the evolution operator.

error: ndarray[Any, dtype[_ScalarType_co]] | None = None

Errors on individual operator elements (mainly used for integration error, but it can host any kind of error).

save(stream: BinaryIO) → bool

Save content of operator to bytes.

The content is saved on a stream, in order to be able to perform the operation both on disk and in memory.

The returned value tells whether the operator saved contained or not the error (this control even the format, npz with errors, npy otherwise).

classmethod load(stream: BinaryIO)

Load operator from bytes.

An input stream is used to load the operator from, in order to support the operation both on disk and in memory.

Submodules

eko.io.access module

Manage file system resources access.

exception eko.io.access.ReadOnlyOperator

Bases: RuntimeError, OutputError

It is not possible to write on a read-only operator.

In particular, the behavior would be deceitful, since writing is possible in-memory and even on the temporary folder. But eventually, no writing will happen on a persistent archive, so any modification is lost after exiting the program.

exception eko.io.access.ClosedOperator

Bases: RuntimeError, OutputError

It is not possible to write on nor to read from a closed operator.

This is milder issue than ReadOnlyOperator, since in this case not even the writing on the temporary folder would be possible.

Instead, it will look like you can access some properties, but the operator is actually closed, so it should not be used any longer in general. However, for extremely simple properties, like those available in memory from eko.io.struct.Metadata or eko.io.struct.AccessConfigs, there is no need to raise on read, since those properties are actually available, but they should always raise on writing, since there is no persistence for the content written, and it can be deceitful.

Still, the level of protection will be mild, since a thoruough protection would clutter a lot the code, requiring a lot of maintenance. “We are adult here”.

class eko.io.access.AccessConfigs(path: Path | None, readonly: bool, open: bool)

Bases: object

Configurations specified during opening of an EKO.

path: Path | None

The path to the permanent object.

readonly: bool

Read-only flag

open: bool

EKO status

property read

Check reading permission.

Reading access is always granted on open operator.

property write

Check writing permission.

assert_open()

Assert operator is open.

Raises:

exceptions.ClosedOperator – if operator is closed

assert_writeable(msg: str | None = None)

Assert operator is writeable.

Raises:

• exceptions.ClosedOperator – see assert_open()

• exceptions.ReadOnlyOperator – if operators has been declared read-only

eko.io.dictlike module

Abstraction for serializations.

A few known types are directly registered here, in order to be transparently codified in more native structures.

class eko.io.dictlike.DictLike

Bases: object

Dictionary compatibility base class, for dataclasses.

This class add compatibility to import and export from Python dict, in such a way to support serialization interfaces working with them.

Some collections and scalar objects are normalized to native Python structures, in order to simplify the on-disk representation.

classmethod from_dict(dictionary)

Deserialize, overwritable interface.

The default implementation is just DictLike._from_dict(), but it can be safely overwritten (usually transforming the input before a call to DictLike._from_dict() itself).

property raw

Overwritable serialization.

The default implementation is just DictLike._raw(), but it can be safely overwritten (usually starting from DictLike._raw() itself).

property public_raw

Serialize only public attributes.

eko.io.dictlike.load_field(type_, value)

Deserialize dataclass field.

eko.io.dictlike.load_enum(type_, value)

Deserialize enum variant.

Accepts both the name and value of variants, attempted in this order.

Raises:

ValueError – if value is not the name nor the value of any enum variant

eko.io.dictlike.load_typing(type_, value)

Deserialize type hint associated field.

eko.io.dictlike.raw_field(value)

Serialize DictLike field.

eko.io.exceptions module

IO generic exceptions.

exception eko.io.exceptions.OutputError

Bases: Exception

Generic Output Error.

exception eko.io.exceptions.OutputExistsError

Bases: FileExistsError, OutputError

Output file already exists.

exception eko.io.exceptions.OutputNotTar

Bases: ValueError, OutputError

Specified file is not a .tar archive.

exception eko.io.exceptions.OperatorLoadingError

Bases: ValueError, OutputError

Issue encountered while loading an operator.

exception eko.io.exceptions.OperatorLocationError(path: PathLike)

Bases: ValueError, OutputError

Path supposed to store an operator in wrong location.

eko.io.inventory module

Manage assets used during computation.

exception eko.io.inventory.LookupError

Bases: ValueError

Failure in content retrieval from inventory.

eko.io.inventory.encode(header: Header)

Extract an hash from a header.

eko.io.inventory.header_name(header: Header)

Determine header file name.

eko.io.inventory.operator_name(header: Header, err: bool)

Determine operator file name, from the associated header.

class eko.io.inventory.Inventory(path: ~pathlib.Path, access: ~eko.io.access.AccessConfigs, header_type: ~typing.Type[~eko.io.items.Header], cache: ~typing.Dict[~eko.io.inventory.H, ~eko.io.items.Operator | None] = <factory>, contentless: bool = False, name: str | None = None)

Bases: Generic[H]

Assets manager.

In particular, manage autosave, autoload, and memory caching.

path: Path

access: AccessConfigs

header_type: Type[Header]

cache: Dict[H, Operator | None]

contentless: bool = False

name: str | None = None

Only for logging purpose.

lookup(stem: str, header: bool = False) → Path

Look up for content path in inventory.

sync()

Sync the headers in the cache with the content on disk.

In particular, headers on disk that are missing in the cache are added to it, without loading actual operators in memory.

Despite the name, the operation is non-destructive, so, even if cache has been abused, nothing will be deleted nor unloaded.

empty()

Empty the in-memory cache.

eko.io.items module

Inventory items definition.

class eko.io.items.Header

Bases: object

Item header, containing metadata.

class eko.io.items.Evolution(origin: float, target: float, nf: int, cliff: bool = False)

Bases: Header

Information to compute an evolution operator.

It describes the evolution with a fixed number of light flavors between two scales.

origin: float

Starting point.

target: float

Final point.

nf: int

Number of active flavors.

cliff: bool = False

Whether the operator is reaching a matching scale.

Cliff operators are the only ones allowed to be intermediate, even though they can also be final segments of an evolution path (see eko.matchings.Atlas.path()).

Intermediate ones always have final scales mu2 corresponding to matching scales, and initial scales mu20 corresponding to either matching scales or the global initial scale of the EKO.

Note

The name of cliff operators stems from the following diagram:

nf = 3 --------------------------------------------------------
                |
nf = 4 --------------------------------------------------------
                        |
nf = 5 --------------------------------------------------------
                                                    |
nf = 6 --------------------------------------------------------

where each lane corresponds to DGLAP evolution with the relative number of running flavors, and the vertical bridges are the perturbative matchings between two different “adjacent” schemes.

classmethod from_atlas(segment: Segment, cliff: bool = False)

Create instance from analogous eko.matchings.Atlas object.

property as_atlas: Segment

The associated segment.

class eko.io.items.Matching(scale: float, hq: int, inverse: bool)

Bases: Header

Information to compute a matching operator.

Describe the matching between two different flavor number schemes.

scale: float

hq: int

inverse: bool

classmethod from_atlas(matching: Matching)

Create instance from analogous eko.matchings.Atlas object.

property as_atlas: Matching

The associated segment.

class eko.io.items.Target(scale: float, nf: int)

Bases: Header

Target evolution point, labeling evolution from origin to there.

scale: float

nf: int

classmethod from_ep(ep: Tuple[float, int])

Create instance from the EPoint analogue.

property ep: Tuple[float, int]

Cast to EPoint.

class eko.io.items.Operator(operator: ndarray[Any, dtype[_ScalarType_co]], error: ndarray[Any, dtype[_ScalarType_co]] | None = None)

Bases: object

Operator representation.

To be used to hold the result of a computed 4-dim operator (either a raw evolution operator or a matching condition).

Note

IO works with streams in memory, in order to avoid intermediate write on disk (keep read from and write to tar file only).

operator: ndarray[Any, dtype[_ScalarType_co]]

Content of the evolution operator.

error: ndarray[Any, dtype[_ScalarType_co]] | None = None

Errors on individual operator elements (mainly used for integration error, but it can host any kind of error).

save(stream: BinaryIO) → bool

Save content of operator to bytes.

The content is saved on a stream, in order to be able to perform the operation both on disk and in memory.

The returned value tells whether the operator saved contained or not the error (this control even the format, npz with errors, npy otherwise).

classmethod load(stream: BinaryIO)

Load operator from bytes.

An input stream is used to load the operator from, in order to support the operation both on disk and in memory.

class eko.io.items.Item(header: Header, content: Operator)

Bases: object

Inventory item.

header: Header

content: Operator

eko.io.manipulate module

Manipulate output generate by EKO.

eko.io.manipulate.SIMGRID_ROTATION = 'ij,ajbk,kl->aibl'

Simultaneous grid rotation contraction indices.

eko.io.manipulate.rotation(new: XGrid | None, old: XGrid, check: Callable, compute: Callable) → ndarray[Any, dtype[_ScalarType_co]]

Define grid rotation.

This function returns the necessary rotation, if the checks for a non-trivial new grid are passed.

However, the check and the computation are delegated respectively to the callables check and compute.

eko.io.manipulate.xgrid_check(new: XGrid | None, old: XGrid) → bool

Check validity of new xgrid.

eko.io.manipulate.xgrid_compute_rotation(new: XGrid, old: XGrid, interpdeg: int, swap: bool = False) → ndarray[Any, dtype[_ScalarType_co]]

Compute rotation from old to new xgrid.

By default, the roation is computed for a target xgrid. Whether the function should be used for an input xgrid, the swap argument should be set to True, in order to compute it in the other direction (i.e. the transposed).

eko.io.manipulate.xgrid_reshape(elem: Operator, xgrid: XGrid, interpdeg: int, targetgrid: XGrid | None = None, inputgrid: XGrid | None = None) → Operator

Reinterpolate the operator on output and/or input grid(s).

Target corresponds to the output PDF.

eko.io.manipulate.SIMPIDS_ROTATION = 'ca,ajbk,bd->cjdk'

Simultaneous grid rotation contraction indices.

eko.io.manipulate.flavor_reshape(elem: Operator, targetpids: ndarray[Any, dtype[_ScalarType_co]] | None = None, inputpids: ndarray[Any, dtype[_ScalarType_co]] | None = None) → Operator

Change the operator to have in the output targetpids and/or in the input inputpids.

Parameters:

• elem – the operator to be rotated

• targetpids – target rotation specified in the flavor basis

• inputpids – input rotation specified in the flavor basis

eko.io.manipulate.to_evol(elem: Operator, source: bool = True, target: bool = False) → Operator

Rotate the operator into evolution basis.

Parameters:

• elem – the operator to be rotated

• source – rotate on the input tensor

• target – rotate on the output tensor

eko.io.manipulate.to_uni_evol(elem: Operator, source: bool = True, target: bool = False) → Operator

Rotate the operator into evolution basis.

Parameters:

• elem – the operator to be rotated

• source – rotate on the input tensor

• target – rotate on the output tensor

eko.io.metadata module

Define eko.EKO metadata.

class eko.io.metadata.Metadata(origin: Tuple[float, int], xgrid: XGrid, _path: Path | None = None, version: str = '0.0.0', data_version: int = 3)

Bases: DictLike

Manage metadata, and keep them synced on disk.

It is possible to have a metadata view, in which the path is not actually connected (i.e. it is set to None). In this case, no update will be possible, of course.

Note

Unfortunately, for nested structures it is not possible to detect a change in their attributes, so a call to update() has to be performed manually.

origin: Tuple[float, int]

Inital scale.

xgrid: XGrid

Interpolation grid.

version: str = '0.0.0'

Library version used to create the corresponding file.

data_version: int = 3

Specs version, to which the file adheres.

classmethod load(path: PathLike)

Load metadata from open folder.

Parameters:

path (os.PathLike) – the path to the open EKO folder

Returns:

loaded metadata

Return type:

Metadata

update()

Update the disk copy of metadata.

property path

Access temporary dir path.

Raises:

RuntimeError – if path has not been initialized before

property raw

Override default DictLike.raw() representation to exclude path.

eko.io.paths module

Define paths inside an eko.EKO object.

class eko.io.paths.InternalPaths(root: Path)

Bases: object

Paths inside an EKO folder.

This structure exists to locate in a single place the internal structure of an EKO folder.

The only value required is the root path, everything else is computed relative to this root. In case only the relative paths are required, just create this structure with root equal to emtpty string or ".".

root: Path

The root of the EKO folder (use placeholder if not relevant)

property metadata

Metadata file.

property recipes

Recipes folder.

property recipes_matching

Matching recipes folder.

property parts

Parts folder.

property parts_matching

Matching parts folder.

property operators

Operators folder.

This is the one containing the actual EKO components, after computation has been performed.

property theory_card

Theory card dump.

property operator_card

Operator card dump.

bootstrap(theory: dict, operator: dict, metadata: dict)

Create directory structure.

eko.io.raw module

Utilities to manipulate unstructured IO.

The content is treated independently on the particular data content, but as generic uknown data in an abstract file format, e.g. a tar archive or YAML data file, as opposed to structured YAML representing a specific runcard.

eko.io.raw.is_within_directory(directory: PathLike, target: PathLike) → bool

Check if target path is contained in directory.

Thanks to TrellixVulnTeam for the idea.

Parameters:

• directory – the directory where the target is supposed to be contained

• target – the target file to check

eko.io.raw.safe_extractall(tar: TarFile, path: PathLike | None = None, members: Sequence[TarInfo] | None = None, *, numeric_owner: bool = False)

Extract a tar archive avoiding CVE-2007-4559 issue.

Thanks to TrellixVulnTeam for the contribution.

All undocumented parameters have the same meaning of the analogue ones in TarFile.extractall().

Parameters:

• tar – the tar archive object to be extracted

• path – the path to extract to, if not specified the current directory is used

eko.io.runcards module

Structures to hold runcards information.

All energy scales in the runcards should be saved linearly, not the squared value, for consistency. Squares are consistently taken inside.

class eko.io.runcards.TheoryCard(order: Tuple[int, int], couplings: CouplingsInfo, heavy: HeavyInfo, xif: float, n3lo_ad_variation: Tuple[int, int, int, int, int, int, int], use_fhmruvv: bool | None = True, matching_order: Tuple[int, int] | None = None)

Bases: DictLike

Represents general theory settings.

This describes the general settings, which define the parameters for the general framework rather than a specific operator. Important settings are e.g. perturbative order, quark masses, or the reference value of the couplings.

order: Tuple[int, int]

Perturbative order tuple, (QCD, QED).

The entries correspond to the power of the respective couplings, e.g. (1,0) refers to \(a_s^1 a_{em}^0\), i.e. LO QCD evolution.

couplings: CouplingsInfo

Couplings configuration.

heavy: HeavyInfo

Heavy quarks related information.

xif: float

Ratio between factorization scale and process scale.

n3lo_ad_variation: Tuple[int, int, int, int, int, int, int]

(gg, gq, qg, qq, nsp, nsm, nsv).

Type:

N3LO anomalous dimension variation

use_fhmruvv: bool | None = True

If True use the FHMRUVV N3LO anomalous dimensions.

matching_order: Tuple[int, int] | None = None

Matching conditions perturbative order tuple, (QCD, QED).

Similar, to order the entries refer to the powers of the respective couplings. QED OME are currently not available. Note that for LO QCD evolution one needs (0,0) as matching_order, because the matching conditions are shifted by one order (since they are related to processes). If not provided it will use this assumption as default.

class eko.io.runcards.Debug(skip_singlet: bool = False, skip_non_singlet: bool = False)

Bases: DictLike

Debug configurations.

skip_singlet: bool = False

Whether to skip singlet computation.

skip_non_singlet: bool = False

Whether to skip non-singlet computation.

class eko.io.runcards.Configs(evolution_method: EvolutionMethod, ev_op_max_order: Tuple[int, int], ev_op_iterations: int, scvar_method: ScaleVariationsMethod | None, inversion_method: InversionMethod | None, interpolation_polynomial_degree: int, interpolation_is_log: bool, polarized: bool, time_like: bool, n_integration_cores: int = 1)

Bases: DictLike

Solution specific configurations.

evolution_method: EvolutionMethod

Evolution mode.

ev_op_max_order: Tuple[int, int]

Maximum order to use in U matrices expansion.

Used only in perturbative solutions.

ev_op_iterations: int

Number of intervals in which to break the evolution integral.

scvar_method: ScaleVariationsMethod | None

Scale variation method.

inversion_method: InversionMethod | None

Which method to use for backward matching conditions.

interpolation_polynomial_degree: int

Degree of elements of the interpolation polynomial basis.

interpolation_is_log: bool

Whether to use polynomials in \(\log(x)\).

If false, polynomials are in \(x\).

polarized: bool

If true do polarized evolution.

time_like: bool

If true do time-like evolution.

n_integration_cores: int = 1

Number of cores used to parallelize integration.

class eko.io.runcards.OperatorCard(init: Tuple[float, int], mugrid: List[Tuple[float, int]], xgrid: XGrid, configs: Configs, debug: Debug, eko_version: str = '0.0.0')

Bases: DictLike

Represents specific operator settings.

This describes the specific settings for a given set of operator, rather than the general theory settings. Important settings are e.g. the initial and final evolution points, or the solution method.

init: Tuple[float, int]

Initial evolution point.

mugrid: List[Tuple[float, int]]

Final list of evolution points.

xgrid: XGrid

Momentum fraction interpolation grid.

configs: Configs

Specific configuration to be used during the calculation of these operators.

debug: Debug

Debug configurations.

eko_version: str = '0.0.0'

Version of EKO package used for generation.

property mu20

Squared value of initial scale.

property mu2grid: ndarray[Any, dtype[_ScalarType_co]]

Grid of squared final scales.

property evolgrid: List[Tuple[float, int]]

Grid of squared final evolution points.

property pids

Internal flavor basis, used for computation.

class eko.io.runcards.Legacy(theory: Dict[str, Any], operator: Dict[str, Any])

Bases: object

Upgrade legacy runcards.

theory: Dict[str, Any]

operator: Dict[str, Any]

MOD_EV2METHOD = {'EXA': 'iterate-exact', 'EXP': 'iterate-expanded', 'TRN': 'truncated'}

static heavies(pattern: str, old_th: dict)

Retrieve a set of values for all heavy flavors.

static fallback(*args: T, default: T | None = None) → T

Return the first not None argument.

property new_theory

Build new format theory runcard.

property new_operator

Build new format operator runcard.

eko.io.runcards.default_atlas(masses: list, matching_ratios: list)

Create default threshold landscape.

This method should not be used to write new runcards, but rather to have a consistent default for comparison with other softwares and existing PDF sets. There is no one-to-one relation between number of running flavors and final scales, unless matchings are all applied. But this is a custom choice, since it is possible to have PDF in different FNS at the same scales.

eko.io.runcards.flavored_mugrid(mugrid: list, masses: list, matching_ratios: list)

Upgrade \(\mu^2\) grid to contain also target number flavors.

It determines the number of flavors for the PDF set at the target scale, inferring it according to the specified scales.

This method should not be used to write new runcards, but rather to have a consistent default for comparison with other softwares and existing PDF sets. There is no one-to-one relation between number of running flavors and final scales, unless matchings are all applied. But this is a custom choice, since it is possible to have PDF in different FNS at the same scales.

eko.io.runcards.masses(theory: TheoryCard, evmeth: EvolutionMethod) → List[float]

Compute masses in the chosen scheme.

eko.io.struct module

Define output representation structures.

eko.io.struct.inventories(path: Path, access: AccessConfigs) → dict

Set up empty inventories for object initialization.

class eko.io.struct.EKO(recipes: Inventory[Evolution], recipes_matching: Inventory[Matching], parts: Inventory[Evolution], parts_matching: Inventory[Matching], operators: Inventory[Target], metadata: Metadata, access: AccessConfigs)

Bases: object

Operator interface.

This class offers an interface to an abstract operator, between memory and disk.

An actual operator might be arbitrarily huge, and in particular size limitations in memory are far more strict than on disk. Since manually managing, for each application, the burden of off-loading part of the operator might be hard and occasionally not possible (without a clear picture of the internals), the library itself offers this facility.

In particular, the data format on disk has a complete specification, and can hold a full operator independently of the loading procedure. In order to accomplish the former goal, the remaining task of partial loading is done by this class (for the Python library, other implementations are possible and encouraged).

For this reason, a core component of an EKO object is a path, referring to the location on disk of the corresponding operator. Any EKO has an associated path:

• for the computed object, it corresponds to the path where the actual result of the computation is already saved

• for a new object, it is the path at which any result of final or intermediate computation is stored, as soon as it is produced

The computation can be stopped at any time, without the loss of any of the intermediate results.

recipes: Inventory[Evolution]

recipes_matching: Inventory[Matching]

parts: Inventory[Evolution]

parts_matching: Inventory[Matching]

operators: Inventory[Target]

metadata: Metadata

Operator metadata.

access: AccessConfigs

Access related configurations.

property paths: InternalPaths

Accessor for internal paths.

property xgrid: XGrid

Momentum fraction internal grid.

property mu20: float

Provide squared initial scale.

property mu2grid: List[float]

Provide the list of \(Q^2\) as an array.

property evolgrid: List[Tuple[float, int]]

Provide the list of evolution points as an array.

property theory_card

Provide theory card, retrieving from the dump.

property operator_card

Provide operator card, retrieving from the dump.

update()

Write updates to structure for persistency.

assert_permissions(read=True, write=False)

Assert permissions on current operator.

property permissions

Provide permissions information.

load_recipes(recipes: List[Evolution | Matching])

Load recipes in bulk.

operator(ep: Tuple[float, int])

Retrieve an operator and discard it afterwards.

To be used as a contextmanager: the operator is automatically loaded as usual, but on the closing of the context manager it is dropped from memory.

items()

Iterate operators, with minimal load.

Pay attention, this iterator:

• is not a read-only operation from the point of view of the in-memory object (since the final result after iteration is no operator loaded)

• but it is a read-only operation from the point of view of the permanent object on-disk

Yields:

tuple – couples of (q2, operator), loaded immediately before, unloaded immediately after

approx(ep: Tuple[float, int], rtol: float = 1e-06, atol: float = 1e-10) → Tuple[float, int] | None

Look for close enough evolution point in the EKO.

The distance is mostly evaluated along the \(\mu^2\) dimension, while \(n_f\) is considered with a discrete distance: if two points have not the same, they are classified as far.

Raises:

ValueError – if multiple values are found in the neighbourhood

unload()

Fully unload the operators in memory.

deepcopy(path: Path)

Create a deep copy of current instance.

The managed on-disk object is copied as well, to the new path location. If you don’t want to copy the disk, consider using directly:

copy.deepcopy(myeko)

It will perform the exact same operation, without propagating it to the disk counterpart.

Parameters:

path – path to the permanent location of the new object (not the temporary directory)

Returns:

the copy created

Return type:

EKO

classmethod load(path: Path)

Load the EKO from disk information.

Note

No archive path is assigned to the EKO object, setting its EKO.access.path to None. If you want to properly load from an archive, use the read() constructor.

classmethod read(path: Path, extract: bool = True, dest: Path | None = None, readonly: bool = True)

Load an existing EKO.

If the extract attribute is True the EKO is loaded from its archived format. Otherwise, the path is interpreted as the location of an already extracted folder.

classmethod create(path: Path)

Create a new EKO.

classmethod edit(*args, **kwargs)

Read from and write on existing EKO.

Alias of EKO.read(…, readonly=False), see read().

dump(archive: Path | None = None)

Dump the current content to archive.

Parameters:

archive (Path or None) – path to archive, in general you should keep the default, that will make use of the registered path (default: None)

Raises:

ValueError – when trying to dump on default archive in read-only mode

close()

Close the current object, cleaning up.

If not in read-only mode, dump to permanent storage. Remove the temporary directory used.

property raw: dict

Provide raw representation of the full content.

Returns:

nested dictionary, storing all the values in the structure, but the operators themselves

Return type:

dict

class eko.io.struct.Builder(path: Path, access: AccessConfigs, theory: TheoryCard | None = None, operator: OperatorCard | None = None, eko: EKO | None = None)

Bases: object

Build EKO instances.

path: Path

Path on disk to the EKO.

access: AccessConfigs

Access related configurations.

theory: TheoryCard | None = None

operator: OperatorCard | None = None

eko: EKO | None = None

load_cards(theory: TheoryCard, operator: OperatorCard)

Load both theory and operator card.

build() → EKO

Build EKO instance.

Returns:

the constructed instance

Return type:

EKO

Raises:

RuntimeError – if not enough information is available (at least one card missing)

eko.io.types module

Common type definitions, only used for static analysis.

class eko.io.types.ReferenceRunning(iterable=(), /)

Bases: list, Generic[T]

Running quantities reference point.

To simplify serialization, the class is just storing the content as a list, but:

• it is constructed with a Running.typed(T, Scale) signature

• it should always be used through the property accessors, rather then using the list itself

classmethod typed(value: T, scale: float)

Define constructor from individual values.

This is the preferred constructor for references, since respects the intended types of the values. It is not the default one only to simplify (de)serialization.

property value: T

Reference value, given at a specified scale.

property scale: float

Reference scale, at which the value of the function is given.

eko.io.types.FlavNumRef

alias of ReferenceRunning[int]

eko.io.types.LinearScaleRef

alias of ReferenceRunning[float]

class eko.io.types.EvolutionMethod(value)

Bases: Enum

DGLAP solution method.

ITERATE_EXACT = 'iterate-exact'

ITERATE_EXPANDED = 'iterate-expanded'

PERTURBATIVE_EXACT = 'perturbative-exact'

PERTURBATIVE_EXPANDED = 'perturbative-expanded'

TRUNCATED = 'truncated'

ORDERED_TRUNCATED = 'ordered-truncated'

DECOMPOSE_EXACT = 'decompose-exact'

DECOMPOSE_EXPANDED = 'decompose-expanded'

class eko.io.types.ScaleVariationsMethod(value)

Bases: Enum

Method used to account for factorization scale variation.

EXPONENTIATED = 'exponentiated'

EXPANDED = 'expanded'

class eko.io.types.InversionMethod(value)

Bases: Enum

Method used to invert the perturbative matching conditions.

EXACT = 'exact'

EXPANDED = 'expanded'

eko.io.v1 module

Legacy interface to files created with v0.13.5.

Although the data version v1 was already before v0.13.5 we only support that API version.

eko.io.v1.update_metadata(paths: InternalPaths, raw: dict) → dict

Modify the raw metadata to the new format.

Parameters:

• paths – base paths to the EKO

• raw – raw yaml content

Returns:

compatible raw yaml content

Return type:

dict

eko.io.v1.update_theory(raw: dict) → dict

Modify the raw theory card to the new format.

Parameters:

raw – raw yaml content

Returns:

compatible raw yaml content

Return type:

dict

eko.io.v1.update_operator(raw_op: dict, raw_th) → dict

Modify the raw operator card to the new format.

Parameters:

• raw_op – raw operator yaml content

• raw_th – raw theory yaml content

Returns:

compatible raw yaml content

Return type:

dict

eko.io.v2 module

Legacy interface to files created with v0.14.

Although the data version v2 was never assigned to v0.14 we use it for exactly that API version.

eko.io.v2.update_metadata(paths: InternalPaths, raw: dict) → dict

Modify the raw metadata to the new format.

Parameters:

• paths – base paths to the EKO

• raw – raw yaml content

Returns:

compatible raw yaml content

Return type:

dict

eko.io.v2.update_theory(raw: dict) → dict

eko.io.v2.update_operator(raw_op: dict, raw_th) → dict