Vakint

Symbolica documentation for getting started, symbolic expressions, numerical evaluation, pattern matching, and APIs in Python and Rust.

Vakint

class Vakint

Vakint engine and settings used for matching, reduction, and evaluation.

Construct one instance and reuse it: initialization processes the complete topology library.

Methods

Name	Description
__new__	Create a new Vakint instance, specifying details of the evaluation stack
evaluate	Perform the complete parametric evaluation of the Vakint integral represented by the Symbolica expression given in input
evaluate_integral	Perform the parametric evaluation of only the integral appearing in the Symbolica expression given in input representing a vakint integral
numerical_evaluation	Substitute numerical parameters into an integral already evaluated parametrically by Vakint.
numerical_result_from_expression	Interpret a Symbolica expression as a numerical Laurent series in epsilon.
numerical_result_to_expression	Convert a Vakint numerical result to a Symbolica Laurent-series expression.
tensor_reduce	Reduce the tensor integrals in a Vakint expression to scalar integrals.
to_canonical	Convert a Vakint expression to canonical momentum routing and topology numbering.

__new__

Vakint.__new__(
    run_time_decimal_precision: typing.Optional[builtins.int] = None,
    evaluation_order: typing.Optional[typing.Sequence[VakintEvaluationMethod]] = None,
    tensor_reduction_method: typing.Optional[builtins.str] = None,
    epsilon_symbol: typing.Optional[Expression] = None,
    mu_r_sq_symbol: typing.Optional[Expression] = None,
    form_exe_path: typing.Optional[builtins.str] = None,
    python_exe_path: typing.Optional[builtins.str] = None,
    verify_numerator_identification: typing.Optional[builtins.bool] = None,
    integral_normalization_factor: typing.Optional[builtins.str] = None,
    allow_unknown_integrals: typing.Optional[builtins.bool] = None,
    clean_tmp_dir: typing.Optional[builtins.bool] = None,
    number_of_terms_in_epsilon_expansion: typing.Optional[builtins.int] = None,
    use_dot_product_notation: typing.Optional[builtins.bool] = None,
    temporary_directory: typing.Optional[builtins.str] = None,
) -> Vakint

Related types: VakintEvaluationMethod, Expression

Create a new Vakint instance, specifying details of the evaluation stack. Note that the same instance can be recycled across multiple evaluations. Note that the creation of a Vakint instance involves the processing and creation of the library of all known topologies, which can be time consuming. External executables are validated when an operation needs them, so the FeynKit tensor backend can be used on systems without FORM.

Examples

>>> from symbolica.community.hepkit.vakint import Vakint
>>> vakint = Vakint(evaluation_order=[])
>>> vakint is not None
True

An empty evaluation order is appropriate for matching, canonicalization, and tensor reduction. Add explicit VakintEvaluationMethod entries before evaluating an integral; each operation validates the external executables it needs.

Parameters

• run_time_decimal_precision (Optional[int]) The decimal precision to be used during the evaluation. Default is 17.
• evaluation_order (Optional[Sequence[VakintEvaluationMethod]]) A list of VakintEvaluationMethod instances specifying the order in which evaluation methods are to be applied. Default is all available methods in a sensible order.
• tensor_reduction_method (Optional[str]) Numerator tensor-reduction backend: “feynkit” is the default, native backend and does not require FORM; “alphaloop” explicitly selects the historical FORM projector.
• epsilon_symbol (Optional[Expression]) The symbol to be used for the dimensional regularisation parameter epsilon. Default is “ε”.
• mu_r_sq_symbol (Optional[Expression]) The symbol to be used for the renormalisation scale squared. Default is “mursq”.
• form_exe_path (Optional[str]) The path to the FORM executable. Default is “form”.
• python_exe_path (Optional[str]) The path to the Python executable. Default is “python3”.
• verify_numerator_identification (Optional[bool]) Whether to verify the identification of numerator structures. Default is True.
• integral_normalization_factor (Optional[str]) The normalization factor to be used for integrals. Can be “MSbar”, “pySecDec”, “FMFTandMATAD” or a custom string. Default is “MSbar”.
• allow_unknown_integrals (Optional[bool]) Whether to allow unknown integrals to be processed. Default is True.
• clean_tmp_dir (Optional[bool]) Whether to clean the temporary directory after evaluation. Default is True, unless the environment variable VAKINT_NO_CLEAN_TMP_DIR is set.
• number_of_terms_in_epsilon_expansion (Optional[int]) The number of terms in the epsilon expansion to be computed. Default is 4.
• use_dot_product_notation (Optional[bool]) Whether to use dot product notation for scalar products. Default is False.
• temporary_directory (Optional[str]) The path to the temporary directory to be used. Default is None, in which case a system temporary directory will be used.

evaluate

Vakint.evaluate(integral_expression: Expression) -> Expression

Related type: Expression

Perform the complete parametric evaluation of the Vakint integral represented by the Symbolica expression given in input. Note that the tensor reduction will be automatically performed on the input given.

Examples

>>> from symbolica import E
>>> from symbolica.community.hepkit.vakint import Vakint, VakintEvaluationMethod
>>> vakint = Vakint(
...     evaluation_order=[VakintEvaluationMethod.new_alphaloop_method()]
... )
>>> integral = E(
...     "k(1,101)*k(1,102)*topo(prop(1,edge(1,1),k(1),muvsq,1))",
...     default_namespace="vakint",
... )
>>> evaluated = vakint.evaluate(integral)
>>> "g(101,102)" in str(evaluated)
True

This path uses the selected tensor backend before integral evaluation. Here the native FeynKit backend reduces the numerator; the AlphaLoop integral-evaluation method requires FORM, just as it does for evaluate_integral.

Parameters

• integral_expression (Expression) A Symbolica expression representing a vakint integral.

evaluate_integral

Vakint.evaluate_integral(integral_expression: Expression) -> Expression

Related type: Expression

Perform the parametric evaluation of only the integral appearing in the Symbolica expression given in input representing a vakint integral. The numerator is left unchanged.

Examples

>>> from symbolica import E
>>> from symbolica.community.hepkit.vakint import Vakint, VakintEvaluationMethod
>>> vakint = Vakint(
...     evaluation_order=[VakintEvaluationMethod.new_alphaloop_method()]
... )
>>> integral = E(
...     "topo(prop(1,edge(1,1),k(1),muvsq,1))",
...     default_namespace="vakint",
... )
>>> evaluated = vakint.evaluate_integral(integral)
>>> "ε" in str(evaluated)
True

The AlphaLoop evaluation method used here invokes FORM. Configure form_exe_path if FORM is not available as form on PATH.

Parameters

• integral_expression (Expression) A Symbolica expression representing a vakint integral.

numerical_evaluation

Vakint.numerical_evaluation(
    evaluated_integral: typing.Any,
    params: typing.Mapping[builtins.str, builtins.float],
    externals: typing.Optional[typing.Mapping[builtins.int, tuple[builtins.float, builtins.float, builtins.float, builtins.float]]] = None,
) -> tuple[VakintNumericalResult, typing.Optional[VakintNumericalResult]]

Related type: VakintNumericalResult

Substitute numerical parameters into an integral already evaluated parametrically by Vakint.

Examples

>>> from symbolica import E
>>> from symbolica.community.hepkit.vakint import Vakint
>>> vakint = Vakint(evaluation_order=[])
>>> evaluated = E(
...     "muvsq*vakint::ε^-1 + mursq",
...     default_namespace="vakint",
... )
>>> result, error = vakint.numerical_evaluation(
...     evaluated,
...     {"muvsq": 2.0, "mursq": 3.0},
... )
>>> sorted(exponent for exponent, _ in result.to_list())
[-1, 0]
>>> error is None
True

Parameters

• evaluated_integral (Expression) A Symbolica expression representing an integral that has been evaluated parametrically by Vakint.
• params (Dict[str, float]) A dictionary mapping parameter names to their numerical values.
• externals (Optional[Dict[int, Tuple[float, float, float, float]]]) An optional dictionary mapping external momentum indices to their numerical 4-vector values.

numerical_result_from_expression

Vakint.numerical_result_from_expression(expr: Expression) -> VakintNumericalResult

Related types: Expression, VakintNumericalResult

Interpret a Symbolica expression as a numerical Laurent series in epsilon.

Examples

>>> from symbolica import E
>>> from symbolica.community.hepkit.vakint import Vakint
>>> vakint = Vakint(evaluation_order=[])
>>> result = vakint.numerical_result_from_expression(
...     E("vakint::ε^-2 + 1 + 0.12*vakint::ε^-1")
... )
>>> sorted(exponent for exponent, _ in result.to_list())
[-2, -1, 0]

Parameters

• expr (Expression) A Symbolica expression representing a Laurent series in the dimensional regularisation parameter epsilon specified in the vakint engine.

numerical_result_to_expression

Vakint.numerical_result_to_expression(result: VakintNumericalResult) -> Expression

Related types: VakintNumericalResult, Expression

Convert a Vakint numerical result to a Symbolica Laurent-series expression.

Examples

>>> from symbolica.community.hepkit.vakint import Vakint, VakintNumericalResult
>>> vakint = Vakint(evaluation_order=[])
>>> result = VakintNumericalResult([
...     (-1, (2.0, 0.0)),
...     (0, (3.0, 0.0)),
... ])
>>> expression = vakint.numerical_result_to_expression(result)
>>> "ε" in str(expression)
True

tensor_reduce

Vakint.tensor_reduce(integral_expression: Expression) -> Expression

Related type: Expression

Reduce the tensor integrals in a Vakint expression to scalar integrals.

Examples

>>> from symbolica import E
>>> from symbolica.community.hepkit.vakint import Vakint
>>> vakint = Vakint(evaluation_order=[])
>>> integral = E(
...     "k(1,101)*k(1,102)*topo(prop(1,edge(1,1),k(1),muvsq,1))",
...     default_namespace="vakint",
... )
>>> reduced = vakint.tensor_reduce(integral)
>>> "g(101,102)" in str(reduced)
True

Parameters

• integral_expression (Expression) A Symbolica expression representing a vakint integral.

to_canonical

Vakint.to_canonical(
    integral_expression: Expression,
    short_form: typing.Optional[builtins.bool] = None,
) -> Expression

Related type: Expression

Convert a Vakint expression to canonical momentum routing and topology numbering.

Examples

>>> from symbolica import E
>>> from symbolica.community.hepkit.vakint import Vakint
>>> vakint = Vakint(evaluation_order=[])
>>> integral = E(
...     "topo(prop(18,edge(7,7),k(99),muvsq,1))",
...     default_namespace="vakint",
... )
>>> canonical = vakint.to_canonical(integral, short_form=True)
>>> "I1L" in str(canonical)
True

Parameters

• integral_expression (Expression) A Symbolica expression representing a vakint integral.
• short_form (Optional[bool]) Whether to use the short form for the topology representation. Default is False.